Esta página es para los autores de firmware que preparan imágenes para actualizaciones over-the-air. Cubre los tipos de firma que acepta Hermetry, cómo firmar una imagen para que la subida sea aceptada y qué comprueba Hermetry. La subida, asignación y seguimiento de actualizaciones se describen en Firmware updates (OTA).
Importante
Hermetry nunca firma el firmware ni guarda una clave privada de firma. Usted firma las imágenes en su propio pipeline de publicación y registra solo claves públicas.
Tipos de firma
| Tipo (tal como se muestra en Hermetry) | Para | Lo que registra | Lo que sube |
|---|---|---|---|
| usign (OpenWrt) | Dispositivos OpenWrt, o cualquier dispositivo cuyo actualizador compruebe una firma usign (Ed25519) | El archivo de clave pública completo (.pub) | La imagen y su archivo de firma separado (.sig) |
| ESP32 Secure Boot V2 | Dispositivos ESP32 con Secure Boot V2 y una clave de firma RSA | El resumen SHA-256 de la clave de 64 caracteres | La imagen firmada; la firma está dentro de ella |
| Not signed | Solo dispositivos de prueba | Nada | La imagen. Solo puede asignarse donde el perfil tenga Allow unsigned images activado. |
Firmar una imagen OpenWrt con usign
Genere un par de claves una vez y guarde la clave secreta en su pipeline de publicación, nunca en Hermetry. Después firme cada imagen y compruebe la firma antes de subirla.
# 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
Lo que comprueba Hermetry:
- El archivo
.siges un archivo de firma usign: una líneauntrusted comment:y una línea base64, de como máximo 1.024 caracteres. - El número de clave de la firma elige una de sus claves usign registradas. Si ninguna coincide, la subida se rechaza.
- La firma Ed25519 se verifica sobre el archivo completo que sube. Firme el archivo final: cualquier cambio después de firmar, incluso el relleno, rompe la firma.
En el dispositivo, Hermetry entrega la firma en fw_sig como usign: seguido del base64 del texto del archivo .sig. Decodifíquelo en un archivo .sig y verifique la imagen descargada con su propia clave, por ejemplo usign -V -m <image> -x <sig> -P <keyring directory>. Compruebe también fw_checksum (SHA-256).
Firmar una imagen ESP32 para Secure Boot V2
Hermetry acepta imágenes con un bloque de firma Secure Boot V2 creado con una clave RSA. Con espsecure.py de Espressif (parte de 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 su compilación ya firma la imagen de la aplicación, suba el archivo firmado que produce.
Lo que comprueba Hermetry:
- La imagen es un número entero de sectores de 4 KiB, de al menos 8 KiB, y su último sector de 4 KiB contiene el bloque de firma.
- El primer bloque de firma es un bloque versión 2, y el resumen de imagen que contiene es igual al SHA-256 de todo lo que hay antes del sector de firma.
- El SHA-256 de la clave pública de ese bloque es igual a uno de sus resúmenes de clave ESP32 registrados. Solo se compara el primer bloque de firma: si firma con más de una clave, registre la clave que firma primero.
Hermetry no verifica la firma RSA en sí: la aplica el bootloader del dispositivo. La comprobación de Hermetry evita que se distribuya una imagen creada para la clave equivocada. Para estas imágenes fw_sig es esp-secure-boot.
Registrar claves de firma
Solo los propietarios pueden añadir o revocar claves de firma.
- Abra Firmware y después Signing keys.
- Seleccione Add key.
- Indique un Name (de 1 a 120 caracteres) y elija su Kind.
- Pegue la Public key: para usign, el archivo
.pubcompleto; para ESP32, el resumen de clave de 64 caracteres.
| Mensaje | Significado |
|---|---|
| Esta no es una clave pública del tipo elegido. | El texto no es un archivo de clave pública usign, ni un resumen hexadecimal de 64 caracteres |
| Esta clave ya está registrada. | Existe una clave activa de ese tipo con la misma huella |
Para cambiar claves, registre la nueva clave pública antes de subir la primera imagen firmada con ella. Revocar una clave revoca todos los paquetes firmados con ella, y las actualizaciones con esos paquetes que aún no han empezado a instalarse se detienen. Revoque una clave solo cuando sus imágenes ya no deban instalarse.
Lo que comprueba la subida
Al subir un paquete, Hermetry comprueba en este orden:
- El SHA-256 del archivo es igual a la suma de comprobación enviada con él. El formulario de subida la calcula en su navegador; compárela con la que generó su compilación.
- La firma, frente a sus claves de firma activas del tipo elegido.
- Un análisis antivirus. El paquete está Ready cuando el análisis está limpio.
El paquete más grande admitido es de 64 MiB por defecto. Una firma rechazada indica el motivo:
| Mensaje | Solución |
|---|---|
| La firma no tiene el formato esperado. Elija el archivo .sig creado para esta imagen. | Suba el archivo .sig creado por usign -S, o una imagen ESP32 que termine con su sector de firma |
| La imagen está firmada con una clave que no está registrada aquí. Primero añada su clave pública en «Signing keys». | Registre la clave pública (usign) o el resumen de clave (ESP32) y vuelva a subir |
| La firma no corresponde a esta imagen. Elija el archivo .sig creado para este archivo exacto. | El archivo cambió después de firmarlo, o la firma pertenece a otro archivo. Vuelva a firmar el archivo final. |
Lista de comprobación para una compilación de publicación
- Dé al paquete el título y la versión que su dispositivo informa como
current_fw_titleycurrent_fw_versiontras arrancar. - Firme la imagen final en último lugar; no la modifique después.
- Guarde las claves secretas en su pipeline de publicación. Hermetry necesita solo la parte pública.
- Use Not signed solo con un perfil de prueba que permita imágenes sin firmar.
- El dispositivo debe rechazar una imagen cuya firma no se verifique, aunque la suma de comprobación coincida.

