Novedad: el cortafuegos de IA supervisa toda la plataforma y explica cada incidente con palabras sencillas. Vea cómo funciona

Compilar y firmar firmware para actualizaciones

Los tipos de firma que Hermetry acepta para actualizaciones over-the-air, cómo firmar una imagen OpenWrt o ESP32 para que sea aceptada y exactamente lo que comprueba Hermetry.

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)ParaLo que registraLo 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 V2Dispositivos ESP32 con Secure Boot V2 y una clave de firma RSAEl resumen SHA-256 de la clave de 64 caracteresLa imagen firmada; la firma está dentro de ella
Not signedSolo dispositivos de pruebaNadaLa 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 .sig es un archivo de firma usign: una línea untrusted 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.

  1. Abra Firmware y después Signing keys.
  2. Seleccione Add key.
  3. Indique un Name (de 1 a 120 caracteres) y elija su Kind.
  4. Pegue la Public key: para usign, el archivo .pub completo; para ESP32, el resumen de clave de 64 caracteres.
MensajeSignificado
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:

  1. 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.
  2. La firma, frente a sus claves de firma activas del tipo elegido.
  3. 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:

MensajeSolució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_title y current_fw_version tras 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.