New: the AI firewall watches the whole platform and explains each incident in plain words. See how it works

Build and sign firmware for updates

The signature kinds Hermetry accepts for over-the-air updates, how to sign an OpenWrt or ESP32 image so it is accepted, and exactly what Hermetry checks.

This page is for firmware authors who prepare images for over-the-air updates. It covers the signature kinds Hermetry accepts, how to sign an image so the upload is accepted, and what Hermetry checks. Uploading, assigning and following updates are in Firmware updates (OTA).

Important

Hermetry never signs firmware and never holds a private signing key. You sign images in your own release pipeline and register only public keys.

Signature kinds

Kind (as shown in Hermetry)ForWhat you registerWhat you upload
usign (OpenWrt)OpenWrt devices, or any device whose updater checks a usign (Ed25519) signatureThe whole public key file (.pub)The image and its detached signature file (.sig)
ESP32 Secure Boot V2ESP32 devices with Secure Boot V2 and an RSA signing keyThe 64-character SHA-256 key digestThe signed image; the signature is inside it
Not signedTest devices onlyNothingThe image. It can be assigned only where the profile has Allow unsigned images on.

Sign an OpenWrt image with usign

Make a key pair once and keep the secret key in your release pipeline, never in Hermetry. Then sign every image and check the signature before you upload it.

# 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

What Hermetry checks:

  • The .sig file is a usign signature file: an untrusted comment: line and one base64 line, at most 1,024 characters.
  • The key number in the signature picks one of your registered usign keys. If none matches, the upload is refused.
  • The Ed25519 signature is verified over the whole file you upload. Sign the final file: any change after signing, even padding, breaks the signature.

On the device, Hermetry delivers the signature in fw_sig as usign: followed by the base64 of the .sig file text. Decode it into a .sig file and verify the downloaded image with your own key, for example usign -V -m <image> -x <sig> -P <keyring directory>. Check fw_checksum (SHA-256) as well.

Sign an ESP32 image for Secure Boot V2

Hermetry accepts images with a Secure Boot V2 signature block made with an RSA key. With Espressif’s espsecure.py (part of 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

If your build already signs the application image, upload the signed file it produces.

What Hermetry checks:

  • The image is a whole number of 4 KiB sectors, at least 8 KiB, and its last 4 KiB sector holds the signature block.
  • The first signature block is a version 2 block, and the image digest in it equals the SHA-256 of everything before the signature sector.
  • The SHA-256 of the public key in that block equals one of your registered ESP32 key digests. Only the first signature block is compared: if you sign with more than one key, register the key that signs first.

Hermetry does not verify the RSA signature itself: the device’s bootloader enforces it. Hermetry’s check stops an image made for the wrong key from being rolled out. For these images fw_sig is esp-secure-boot.

Register signing keys

Only owners can add or revoke signing keys.

  1. Open Firmware and then Signing keys.
  2. Select Add key.
  3. Give it a Name (1 to 120 characters) and choose its Kind.
  4. Paste the Public key: for usign the whole .pub file, for ESP32 the 64-character key digest.
MessageMeaning
This is not a public key of the chosen kind.The text is not a usign public key file, or not a 64-character hex digest
This key is already registered.An active key of that kind with the same fingerprint exists

To change keys, register the new public key before the first image signed with it is uploaded. Revoking a key revokes every package signed with it, and updates with those packages that have not started installing are stopped. Revoke a key only when its images must no longer be installed.

What the upload checks

When you upload a package, Hermetry checks in this order:

  1. The SHA-256 of the file equals the checksum sent with it. The upload form works it out in your browser; compare it with the one your build gave you.
  2. The signature, against your active signing keys of the chosen kind.
  3. A virus scan. The package is Ready when the scan is clean.

The largest package is 64 MiB by default. A refused signature names the reason:

MessageFix
The signature is not in the expected format. Pick the .sig file made for this image.Upload the .sig file made by usign -S, or an ESP32 image that ends with its signature sector
The image is signed with a key that is not registered here. Add its public key under “Signing keys” first.Register the public key (usign) or key digest (ESP32), then upload again
The signature does not match this image. Pick the .sig file made for this exact file.The file changed after signing, or the signature belongs to another file. Sign the final file again.

Checklist for a release build

  • Give the package the title and version your device reports as current_fw_title and current_fw_version after it boots.
  • Sign the final image last; do not change it afterwards.
  • Keep secret keys in your release pipeline. Hermetry needs only the public part.
  • Use Not signed only with a test profile that allows unsigned images.
  • The device must refuse an image whose signature does not verify, even when the checksum matches.