Cette page s’adresse aux auteurs de micrologiciels qui préparent des images pour les mises à jour à distance (OTA). Elle couvre les types de signature acceptés par Hermetry, la manière de signer une image pour que l’envoi soit accepté, et ce que Hermetry vérifie. L’envoi, l’affectation et le suivi des mises à jour sont décrits dans Mises à jour du micrologiciel (OTA).
Important
Hermetry ne signe jamais le micrologiciel et ne détient jamais de clé de signature privée. Vous signez les images dans votre propre chaîne de publication et n’enregistrez que des clés publiques.
Types de signature
| Type (tel qu’affiché dans Hermetry) | Pour | Ce que vous enregistrez | Ce que vous envoyez |
|---|---|---|---|
| usign (OpenWrt) | Appareils OpenWrt, ou tout appareil dont le programme de mise à jour vérifie une signature usign (Ed25519) | Le fichier de clé publique complet (.pub) | L’image et son fichier de signature détaché (.sig) |
| ESP32 Secure Boot V2 | Appareils ESP32 avec Secure Boot V2 et une clé de signature RSA | L’empreinte SHA-256 de la clé, sur 64 caractères | L’image signée ; la signature se trouve à l’intérieur |
| Non signé | Appareils de test uniquement | Rien | L’image. Elle ne peut être affectée que lorsque le profil a Autoriser les images non signées activé. |
Signer une image OpenWrt avec usign
Créez une paire de clés une seule fois et conservez la clé secrète dans votre chaîne de publication, jamais dans Hermetry. Signez ensuite chaque image et vérifiez la signature avant de l’envoyer.
# once: a key pair
usign -G -s release.sec -p release.pub -c "firmware release key"
# for every image
usign -S -m firmware.bin -s release.sec -x firmware.bin.sig
# check before you upload
usign -V -m firmware.bin -x firmware.bin.sig -p release.pub
Ce que Hermetry vérifie :
- Le fichier
.sigest un fichier de signature usign : une ligneuntrusted comment:et une ligne en base64, au plus 1 024 caractères. - Le numéro de clé dans la signature désigne l’une de vos clés usign enregistrées. Si aucune ne correspond, l’envoi est refusé.
- La signature Ed25519 est vérifiée sur le fichier entier que vous envoyez. Signez le fichier final : toute modification après la signature, même un bourrage, rompt la signature.
Sur l’appareil, Hermetry transmet la signature dans fw_sig sous la forme usign: suivi du base64 du texte du fichier .sig. Décodez-la dans un fichier .sig et vérifiez l’image téléchargée avec votre propre clé, par exemple usign -V -m <image> -x <sig> -P <répertoire du trousseau>. Vérifiez également fw_checksum (SHA-256).
Signer une image ESP32 pour Secure Boot V2
Hermetry accepte les images dotées d’un bloc de signature Secure Boot V2 réalisé avec une clé RSA. Avec espsecure.py de Espressif (fourni avec esptool) :
# once: an RSA-3072 signing key
espsecure.py generate_signing_key --version 2 --scheme rsa3072 signing_key.pem
# for every image: append the signature sector
espsecure.py sign_data --version 2 --keyfile signing_key.pem --output app-signed.bin app.bin
# once: the key digest you register in Hermetry (64 hex characters)
espsecure.py digest_sbv2_public_key --keyfile signing_key.pem --output key_digest.bin
xxd -p -c 32 key_digest.bin
Si votre build signe déjà l’image de l’application, envoyez le fichier signé qu’il produit.
Ce que Hermetry vérifie :
- L’image est un nombre entier de secteurs de 4 Kio, d’au moins 8 Kio, et son dernier secteur de 4 Kio contient le bloc de signature.
- Le premier bloc de signature est un bloc version 2, et l’empreinte de l’image qu’il contient est égale au SHA-256 de tout ce qui précède le secteur de signature.
- Le SHA-256 de la clé publique de ce bloc est égal à l’une de vos empreintes de clés ESP32 enregistrées. Seul le premier bloc de signature est comparé : si vous signez avec plusieurs clés, enregistrez la clé qui signe en premier.
Hermetry ne vérifie pas la signature RSA elle-même : c’est le chargeur de démarrage de l’appareil qui l’impose. La vérification de Hermetry empêche le déploiement d’une image produite pour la mauvaise clé. Pour ces images, fw_sig vaut esp-secure-boot.
Enregistrer les clés de signature
Seuls les propriétaires peuvent ajouter ou révoquer des clés de signature.
- Ouvrez Micrologiciel, puis Clés de signature.
- Sélectionnez Ajouter une clé.
- Donnez-lui un Nom (de 1 à 120 caractères) et choisissez son Type.
- Collez la Clé publique : pour usign le fichier
.pubcomplet, pour ESP32 l’empreinte de clé de 64 caractères.
| Message | Signification |
|---|---|
| Ce n’est pas une clé publique du type choisi. | Le texte n’est pas un fichier de clé publique usign, ni une empreinte hexadécimale de 64 caractères |
| Cette clé est déjà enregistrée. | Une clé active de ce type avec la même empreinte existe |
Pour changer de clés, enregistrez la nouvelle clé publique avant l’envoi de la première image signée avec elle. Révoquer une clé révoque chaque paquet signé avec elle, et les mises à jour de ces paquets qui n’ont pas encore commencé à s’installer sont arrêtées. Ne révoquez une clé que lorsque ses images ne doivent plus être installées.
Ce que l’envoi vérifie
Lorsque vous envoyez un paquet, Hermetry vérifie dans cet ordre :
- Le SHA-256 du fichier est égal à la somme de contrôle envoyée avec lui. Le formulaire d’envoi la calcule dans votre navigateur ; comparez-la à celle fournie par votre build.
- La signature, par rapport à vos clés de signature actives du type choisi.
- Une analyse antivirus. Le paquet passe à Prêt lorsque l’analyse est propre.
Le plus grand paquet fait 64 Mio par défaut. Une signature refusée indique la raison :
| Message | Correction |
|---|---|
| La signature n’est pas dans le format attendu. Choisissez le fichier .sig réalisé pour cette image. | Envoyez le fichier .sig produit par usign -S, ou une image ESP32 qui se termine par son secteur de signature |
| L’image est signée avec une clé qui n’est pas enregistrée ici. Ajoutez d’abord sa clé publique sous « Clés de signature ». | Enregistrez la clé publique (usign) ou l’empreinte de clé (ESP32), puis envoyez à nouveau |
| La signature ne correspond pas à cette image. Choisissez le fichier .sig réalisé pour ce fichier exact. | Le fichier a été modifié après la signature, ou la signature appartient à un autre fichier. Signez à nouveau le fichier final. |
Liste de contrôle pour un build de publication
- Donnez au paquet le titre et la version que votre appareil indique sous
current_fw_titleetcurrent_fw_versionaprès son démarrage. - Signez l’image finale en dernier ; ne la modifiez plus ensuite.
- Conservez les clés secrètes dans votre chaîne de publication. Hermetry n’a besoin que de la partie publique.
- Utilisez Non signé uniquement avec un profil de test qui autorise les images non signées.
- L’appareil doit refuser une image dont la signature ne se vérifie pas, même lorsque la somme de contrôle correspond.

