Outil de provisionnement d'usine OpenWeave

Voir la source sur GitHub

L'outil de provisionnement de l'usine OpenWeave fournit un moyen pratique de provisionner des informations de configuration persistantes sur chaque appareil compatible avec Weave. L'outil Factory Provisioning est destiné à être utilisé dans le cadre d'un processus de ligne de fabrication qui tamponne les appareils individuels avec des informations d'identification et d'identification uniques avant de les expédier aux clients. Les développeurs peuvent également l'utiliser pour personnaliser le matériel en préproduction pendant le processus de développement.

Théorie des opérations

L'objectif de l'outil de provisionnement d'usine OpenWeave est d'injecter certaines informations de configuration dans un magasin de configuration persistant d'appareil, où les données peuvent être récupérées et utilisées par le micrologiciel de l'appareil au moment de l'exécution. La configuration persistante de l'appareil est généralement stockée dans le flash interne de l'appareil. Toutefois, les détails de la façon exacte dont les données sont stockées et dans quel format varient d'une plate-forme à l'autre. L'outil de provisionnement de fabrique est indépendant du format de stockage final et s'appuie sur le code du micrologiciel de l'appareil pour écrire les données de manière appropriée. L'interface utilisateur de cet outil est également entièrement indépendante du type de matériel configuré, ce qui signifie que des processus de fabrication similaires peuvent être utilisés pour toutes les gammes de produits basées sur différentes plates-formes matérielles.

L'outil de provisionnement Factory est conçu pour fonctionner sur une machine hôte connectée à un appareil cible via une interface de débogage ou de contrôle, par exemple un port JTAG ou SWD. Cet outil fonctionne en injectant des informations de provisionnement dans la mémoire RAM de l'appareil dans un format spécialement codé. L'appareil est ensuite invité à redémarrer, puis le code intégré au micrologiciel de l'appareil localise les données encodées, valide son intégrité et écrit les valeurs qu'il contient dans un format de stockage persistant adapté à la plate-forme.

Le code intégré à l'appareil qui détecte et traite les données de provisionnement injectées est intégré à la couche de l'appareil OpenWeave et peut être activé sur n'importe quelle plate-forme compatible. Une fois activé, le code s'exécute automatiquement à chaque démarrage de l'appareil, à un stade précoce du processus d'initialisation de l'appareil. Le code fonctionne en analysant une région RAM spécifique à la plate-forme. Sur les plates-formes avec des installations de mémoire modestes (par exemple, <1M), l'analyse englobe toute la RAM disponible.

Lorsqu'elles sont placées dans la mémoire RAM, les données de provisionnement sont encodées avec un préfixe facilement identifiable, ce qui permet de les trouver rapidement lors du processus d'analyse. Une valeur de vérification de l'intégrité basée sur un hachage cryptographique permet de confirmer la validité des données avant le traitement.

Par défaut, l'outil de provisionnement sélectionne l'emplacement RAM à partir duquel les données de provisionnement sont injectées en fonction de la plate-forme de l'appareil cible. Ce choix peut être ignoré via un argument de l'outil. En général, il n'est pas nécessaire que le micrologiciel de l'appareil réserve un emplacement RAM spécifique pour recevoir les données de provisionnement. Plus généralement, les données de provisionnement sont écrites dans un emplacement RAM alloué à d'autres fins, mais sont généralement inutilisées au début du processus de démarrage de l'appareil. Les choix les plus courants sont le haut de la pile système initiale ou l'extrémité d'un segment de segment de mémoire.

L'outil de provisionnement Factory s'appuie sur un ensemble d'outils de développement externe pour établir une interface avec l'appareil cible. Les outils utilisés dépendent du type d'appareil cible. Deux interfaces d'appareil sont actuellement compatibles:

• une vérification de débogage J-Link SEGGER connectée à un port JTAG ou SWD d'un appareil
• Un port série USB connecté à un Espressif ESP32

L'interface J-Link repose sur l'outil SEGGER J-Link Commander (JLinkExe), qui doivent être installés séparément sur la machine hôte.

L'interface ESP32 repose sur la commande Esesif esptool.py, qui est fournie dans le SDK ESP-IDF d'Espressif.

Types d'informations pouvant être provisionnées

L'outil de provisionnement de l'usine OpenWeave permet de provisionner les types d'informations suivants:

• Numéro de série de l'appareil
• ID de l'appareil Weave attribué par le fabricant
• Certificat Weave et clé privée attribués par le fabricant
• Code d'association Weave
• Numéro de révision de produit
• Date de fabrication

Même si un appareil a généralement besoin de toutes les informations ci-dessus pour fonctionner correctement, il n'est pas obligatoire de fournir toutes les informations en même temps. Ainsi, le provisionnement de différents types d'informations peut se produire à des étapes distinctes du processus de fabrication. En outre, il est possible de remplacer les valeurs précédemment provisionnées par de nouvelles lors d'une étape ultérieure de provisionnement.

Sources d'informations sur la gestion des comptes

Pour fournir des informations sur le provisionnement des appareils à l'outil de configuration d'usine, deux possibilités s'offrent à vous:

• Arguments de ligne de commande
• Utiliser un fichier CSV de provisionnement
• En récupérant les valeurs d'un serveur de provisionnement Nest

Ligne de commande

Dans la forme la plus simple, les informations de provisionnement des appareils sont spécifiées directement dans la ligne de commande de l'outil de provisionnement d'usine OpenWeave. Exemple :

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
    --pairing-code NESTUS --mfg-date 2019/04/01

Les valeurs de données binaires, telles que le certificat Weave et la clé privée, peuvent être spécifiées sous forme de chaînes de base 64 ou de noms de fichiers contenant les données souhaitées sous forme brute (binaire).

Vous trouverez ci-dessous la liste complète des arguments de ligne de commande disponibles.

Configuration du fichier CSV...

Pour faciliter le provisionnement d'appareils, la configuration d'usine peut également lire les données de provisionnement à partir d'un fichier de données au format CSV. Les colonnes de ce fichier doivent correspondre à des types de données de provisionnement spécifiques (Serial_Num, Certificate, Private_Key, etc.). Les lignes du fichier fournissent des valeurs individuelles pour des appareils spécifiques, indexées par ID d'appareil Weave (Device_Id). L'ID de l'appareil à provisionner doit être spécifié sur la ligne de commande. Exemple :

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
    --prov-csv-file ./dev-provisioning-data.csv

Les colonnes CSV suivantes sont acceptées:

Nom	Format	Description
Device_Id	16 chiffres hexadécimaux	ID de l'appareil Weave. Doit être présent.
Serial_Num	chaîne	Numéro de série de l'appareil
Certificate	chaîne en base64	Certificat appareil Weave attribué par le fabricant.
Private_Key	chaîne en base64	Clé privée Weave attribuée par le fabricant.
Pairing_Code	chaîne	Code d'association Weave.
Product_Rev	entier	Numéro de révision du produit.
Mfg_Date	AAAA/MM/JJ	Date de fabrication de l'appareil.

Les colonnes peuvent apparaître dans le fichier CSV dans n'importe quel ordre. Toutes les colonnes sont facultatives, à l'exception de celles de Device_Id. Les valeurs non présentes dans le fichier CSV ne sont tout simplement pas provisionnées sur l'appareil.

L'utilisateur peut spécifier des valeurs de provisionnement spécifiques dans la ligne de commande, en plus du fichier CSV. Dans ce cas, la valeur de la ligne de commande est prioritaire par rapport à celle du fichier CSV.

Le format de fichier CSV est pris en charge par l'outil de configuration d'usine. Il est compatible avec la sortie de la commande gen-provisioning-data de l'outil weave.

Serveur de provisionnement Nest

L'outil de provisionnement Factory permet de récupérer les informations de provisionnement à partir d'un serveur de provisionnement Nest à l'aide d'un protocole HTTPS. Le protocole de serveur de provisionnement permet de récupérer le certificat d'appareil Weave attribué par le fabricant, la clé privée correspondante et le code d'association Weave du serveur de provisionnement.

L'emplacement réseau du serveur de provisionnement est spécifié en fournissant une URL de base sur la ligne de commande de l'outil de provisionnement. Les informations de provisionnement souhaitées sont sélectionnées en spécifiant l'ID de l'appareil Weave dans la ligne de commande. Exemple :

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
    --prov-server https://192.168.172.2:8000/

L'utilisateur peut spécifier des valeurs de provisionnement individuelles dans la ligne de commande, en plus de l'URL du serveur de provisionnement. Dans ce cas, les valeurs fournies sur la ligne de commande prévalent sur celles renvoyées par le serveur.

Activer / Désactiver la compatibilité avec le provisionnement des configurations d'usine

La prise en charge du provisionnement des usines OpenWeave dans le micrologiciel de l'appareil est contrôlée par l'option de configuration WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING. Cette option est activée par défaut. Vous pouvez désactiver cette fonctionnalité en remplaçant l'option correspondante dans le fichier WeaveProjectConfig.h de l'application. Exemple :

#define WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING 0

En général, vous pouvez activer le provisionnement des appareils en production dans le micrologiciel de l'appareil en production, à condition que l'interface de débogage de l'appareil soit correctement désactivée sur les appareils en production. Pour ce faire, vous pouvez utiliser le matériel (par exemple, en filtrant les fusibles dans le SoC) ou un logiciel (par exemple, via un bootloader sécurisé qui bloque l'accès au débogage durant le processus de démarrage).

Exécuter l'outil de provisionnement d'usine

L'outil de provisionnement de l'usine OpenWeave est compatible avec les options de ligne de commande suivantes:

Option	Description
--target <string>	Type d'appareil ciblé. Les choix possibles sont nrf52840, esp32.
--load-addr <hex-digits>	Adresse dans la mémoire de l'appareil où les données de provisionnement seront écrites.
--verbose -v	Ajustez le niveau de verbosité de la sortie. Utilisez plusieurs arguments pour augmenter la verbosité.
--series-num <chaîne>	Définissez le numéro de série de l'appareil.
--device-id <hex-digits>	Définissez l'ID de l'appareil attribué par le fabricant.
--device-cert <base-64> | <nom-fichier>	Définissez le certificat de l'appareil Weave attribué par le fabricant.
--device-key <base-64> | <nom-fichier>	Définissez la clé privée de l'appareil Weave attribuée par le fabricant.
--pair-code <chaîne>	Définissez le code d'association de l'appareil.
--product-rev <integer>.	Définissez la révision des produits pour l'appareil.
--mfg-date <AAAA/MM/JJ> | aujourd'hui | maintenant	Définissez la date de fabrication de l'appareil.
--jlink-cmd <chemin-nom>	Chemin d'accès à la commande JLink. La valeur par défaut est 'JLinkExe'.
--jlink-if SWD | JTAG	Type d'interface J-Link. La valeur par défaut est SWD.
--jlink-speed <integer> | adaptable | auto	Vitesse de l'interface J-Link
--jlink-sn <chaîne>	Numéro de série de la vérification J-Link.
--esptool-cmd <chemin-nom>	Chemin d'accès à la commande esptool. La valeur par défaut est 'esptool.py'.
--port <chemin-nom>	Nom du port COM pour ESP32. La valeur par défaut est /tty/USB0.
--speed <integer>.	Débit en Baud pour le port COM. La valeur par défaut est 115200.
--prov-csv-file <nom-fichier>	Lire les données de provisionnement d'appareils à partir d'un fichier CSV de provisionnement.
--prov-server <url>	Lire les données de provisionnement d'appareils à partir d'un serveur de provisionnement.
--disable-server-validation	Lorsque vous utilisez HTTPS, désactivez la validation du certificat présenté par le serveur de provisionnement.

Examples

La commande suivante définit l'ID de l'appareil, le numéro de série, la révision du produit et le code d'association sur des valeurs spécifiques. La date de fabrication est définie sur la date actuelle. Le certificat et la clé privée de l'appareil sont définis pour tester les valeurs fournies dans un fichier CSV fourni avec le dépôt source openweave-core.

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000042 \
    --serial-num JAYS_DEVICE_42 --product-rev 1 --pairing-code NESTUS --mfg-date today \
    --prov-csv-file ~/projects/openweave-core/certs/development/device/test-dev-provisioning-data.csv