Outil de provisionnement d'usine OpenWeave

Afficher la source sur GitHub

L'outil de provisionnement d'usine OpenWeave permet de provisionner des informations de configuration persistantes par appareil sur les appareils compatibles avec Weave. L'outil de provisionnement en usine est destiné à être utilisé dans le cadre d'un processus de ligne de fabrication qui appose sur chaque appareil des informations d'identité et d'identifiant uniques avant leur expédition aux clients. Les développeurs peuvent également l'utiliser pour personnaliser le matériel de préproduction utilisé pendant le processus de développement.

Fonctionnement

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

L'outil de provisionnement d'usine est conçu pour s'exécuter sur un ordinateur hôte connecté à un appareil cible via une interface de débogage ou de contrôle, par exemple un port JTAG ou SWD. L'outil injecte des informations de provisionnement dans la RAM de l'appareil sous une forme spécialement encodée. L'appareil est ensuite invité à redémarrer, à quel point le code intégré au micrologiciel de l'appareil localise les données encodées, valide leur intégrité et écrit les valeurs contenues dans un stockage persistant dans un format adapté à la plate-forme.

Le code sur l'appareil qui détecte et traite les données de provisionnement injectées est intégré à la couche d'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 de RAM spécifique à la plate-forme. Sur les plates-formes disposant de quantités de mémoire modestes (par exemple, moins de 1 Mo), l'analyse couvre toute la RAM disponible.

Lorsqu'elles sont placées dans la 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 est utilisée pour confirmer la validité des données avant le traitement.

Par défaut, l'outil de provisionnement sélectionne l'emplacement de la RAM dans lequel injecter les données de provisionnement en fonction de la plate-forme de l'appareil cible. Ce choix peut être remplacé par 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 de RAM spécifiquement pour recevoir les données de provisionnement. Plus généralement, les données de provisionnement sont écrites dans un emplacement de RAM alloué à d'autres fins, mais généralement inutilisé au début du processus de démarrage de l'appareil. Les choix courants sont le sommet de la pile système initiale ou l'extrémité d'une zone de tas.

L'outil de provisionnement d'usine s'appuie sur un ensemble d'outils de développement externes pour interagir avec l'appareil cible. Les outils spécifiques utilisés dépendent du type d'appareil cible. Deux interfaces d'appareil sont actuellement compatibles:

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

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

L'interface ESP32 s'appuie sur la commande esptool.py d'Espressif, fournie dans le SDK ESP-IDF d'Espressif.

Types d'informations pouvant être fournies

L'outil OpenWeave Factory Provisioning est capable de fournir les types d'informations suivants:

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

Bien qu'un appareil ait généralement besoin de toutes les informations ci-dessus pour fonctionner correctement, il n'est pas nécessaire de provisionner toutes les informations en même temps. Ainsi, différents types d'informations peuvent être fournis à différents stades du processus de fabrication. De plus, il est possible de remplacer les valeurs provisionnées précédemment par de nouvelles valeurs lors d'une étape de provisionnement ultérieure.

Sources d'informations de provisionnement

Vous pouvez fournir les informations de provisionnement de l'appareil à l'outil de provisionnement d'usine de différentes manières:

• Arguments de ligne de commande
• À l'aide d'un fichier CSV de provisionnement
• En récupérant des valeurs à partir d'un serveur de provisionnement Nest

Ligne de commande

Dans sa forme la plus simple, les informations de provisionnement des appareils sont spécifiées directement dans la ligne de commande dans 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 en base64 ou sous forme 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.

Provisionnement du fichier CSV...

Pour permettre le provisionnement groupé des appareils, l'outil de provisionnement en usine peut également lire les données de provisionnement à partir d'un fichier de données de provisionnement au format CSV. Les colonnes de ce fichier doivent correspondre à des types de données de provisionnement spécifiques, c'est-à-dire Serial_Num, Certificate, Private_Key, etc. Les lignes du fichier indiquent des valeurs individuelles pour des appareils spécifiques, indexés par l'ID de l'appareil Weave (Device_Id). L'ID de l'appareil spécifique à 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 d'appareil Weave attribué par le fabricant.
Private_Key	Chaîne base-64	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 Device_Id. Les valeurs qui ne sont pas 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 individuelles sur la ligne de commande en plus du fichier CSV. Dans ce cas, la valeur de la ligne de commande prévaut sur celles du fichier.

La prise en charge du format de fichier CSV par l'outil de provisionnement d'usine est compatible avec la sortie de la commande gen-provisioning-data de l'outil weave.

Serveur de provisionnement Nest

L'outil de configuration d'usine permet de récupérer certaines informations de provisionnement à partir d'un serveur de provisionnement Nest à l'aide d'un protocole HTTPS. Le protocole du serveur d'approvisionnement peut être utilisé pour récupérer le certificat d'appareil Weave attribué par le fabricant, la clé privée correspondante et le code d'association Weave à partir du serveur d'approvisionnement.

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 sur 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 sur la ligne de commande en plus de l'URL du serveur de provisionnement. Dans ce cas, les valeurs indiquées sur la ligne de commande prévalent sur les valeurs renvoyées par le serveur.

Activer / Désactiver la prise en charge du provisionnement d'usine

La prise en charge du provisionnement d'usine OpenWeave dans le micrologiciel de l'appareil est contrôlée par l'option de configuration au moment de la compilation 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 dans le fichier WeaveProjectConfig.h de l'application. Exemple :

#define WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING 0

En général, il est possible d'activer le provisionnement en usine dans le micrologiciel d'appareil en production à condition que l'interface de débogage de l'appareil soit correctement désactivée sur les appareils en production. Cela peut être réalisé par des moyens matériels (par exemple, en faisant sauter des fusibles dans le SoC) ou par logiciel (par exemple, via un bootloader sécurisé qui bloque l'accès au débogage lors du processus de démarrage).

Exécuter l'outil de provisionnement d'usine

L'outil de provisionnement d'usine OpenWeave prend en charge les options de ligne de commande suivantes:

Option	Description
--target <chaîne>	Type d'appareil cible. Les options disponibles sont: nrf52840, esp32
--load-addr <chiffres hexadécimaux>	Adresse dans la mémoire de l'appareil à laquelle les données de provisionnement seront écrites.
--verbose, -v	Ajustez le niveau de détails de la sortie. Utilisez plusieurs arguments pour augmenter le niveau de verbosité.
--serial-num <chaîne>	Définissez le numéro de série de l'appareil.
--device-id <chiffres-hex>	Définissez l'ID de l'appareil attribué par le fabricant.
--device-cert <base-64> | <nom-fichier>	Définissez le certificat d'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.
--code-pair <chaîne>	Définissez le code d'association de l'appareil.
--product-rev <nombre entier>	Définissez la version du produit pour l'appareil.
--mfg-date <AAAA/MM/JJ> | today | now	Définissez la date de fabrication de l'appareil.
--jlink-cmd <nom-chemin>	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 <entier> | adaptive | auto	Vitesse de l'interface J-Link.
--jlink-sn <chaîne>	Numéro de série de la sonde J-Link.
--esptool-cmd <nom-chemin>	Chemin d'accès à la commande esptool. La valeur par défaut est "esptool.py".
--port <nom-chemin>	Nom de l'appareil du port COM pour l'ESP32. La valeur par défaut est /tty/USB0.
--speed <integer>	Débit en bauds pour le port COM. La valeur par défaut est 115200.
--prov-csv-file <nom-fichier>	Lire les données de provisionnement de l'appareil à partir d'un fichier CSV de provisionnement
--prov-server <url>	Lire les données de provisionnement des 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.

Exemples

La commande suivante définit l'ID de l'appareil, le numéro de série, la version 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 de l'appareil et la clé privée sont définis sur des valeurs de test 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