Neu: Die KI-Firewall überwacht die gesamte Plattform und erklärt jeden Vorfall in einfachen Worten. So funktioniert es

Firmware für Updates bauen und signieren

Die Signaturarten, die Hermetry für Over-the-Air-Updates akzeptiert, wie Sie ein OpenWrt- oder ESP32-Image so signieren, dass es angenommen wird, und genau was Hermetry prüft.

Diese Seite richtet sich an Firmware-Entwickler, die Images für Over-the-Air-Updates vorbereiten. Sie behandelt die Signaturarten, die Hermetry akzeptiert, wie Sie ein Image so signieren, dass der Upload angenommen wird, und was Hermetry prüft. Hochladen, Zuweisen und Verfolgen von Updates finden Sie unter Firmware-Updates (OTA).

Wichtig

Hermetry signiert niemals Firmware und verwahrt nie einen privaten Signaturschlüssel. Sie signieren Images in Ihrer eigenen Release-Pipeline und registrieren nur öffentliche Schlüssel.

Signaturarten

Art (wie in Hermetry angezeigt)FürWas Sie registrierenWas Sie hochladen
usign (OpenWrt)OpenWrt-Geräte oder jedes Gerät, dessen Updater eine usign-(Ed25519-)Signatur prüftDie vollständige öffentliche Schlüsseldatei (.pub)Das Image und die separate Signaturdatei (.sig)
ESP32 Secure Boot V2ESP32-Geräte mit Secure Boot V2 und einem RSA-SignaturschlüsselDer 64-stellige SHA-256-SchlüsselhashDas signierte Image; die Signatur ist im Image enthalten
Nicht signiertNur TestgeräteNichtsDas Image. Es kann nur dort zugewiesen werden, wo das Profil Allow unsigned images aktiviert hat.

Ein OpenWrt-Image mit usign signieren

Erstellen Sie einmalig ein Schlüsselpaar und bewahren Sie den geheimen Schlüssel in Ihrer Release-Pipeline auf, niemals in Hermetry. Signieren Sie dann jedes Image und prüfen Sie die Signatur, bevor Sie es hochladen.

# 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

Was Hermetry prüft:

  • Die Datei .sig ist eine usign-Signaturdatei: eine Zeile untrusted comment: und eine Base64-Zeile, höchstens 1.024 Zeichen.
  • Die Schlüsselnummer in der Signatur wählt einen Ihrer registrierten usign-Schlüssel aus. Passt keiner, wird der Upload abgelehnt.
  • Die Ed25519-Signatur wird über die gesamte Datei geprüft, die Sie hochladen. Signieren Sie die endgültige Datei: Jede Änderung nach dem Signieren, auch Auffüllbytes, bricht die Signatur.

Auf dem Gerät liefert Hermetry die Signatur in fw_sig als usign:, gefolgt vom Base64-Wert des Textes der Datei .sig. Dekodieren Sie ihn in eine Datei .sig und prüfen Sie das heruntergeladene Image mit Ihrem eigenen Schlüssel, zum Beispiel usign -V -m <image> -x <sig> -P <keyring directory>. Prüfen Sie zusätzlich fw_checksum (SHA-256).

Ein ESP32-Image für Secure Boot V2 signieren

Hermetry akzeptiert Images mit einem Secure-Boot-V2-Signaturblock, der mit einem RSA-Schlüssel erstellt wurde. Mit espsecure.py von Espressif (Teil von 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

Signiert Ihr Build das Anwendungsimage bereits, laden Sie die signierte Datei hoch, die er erzeugt.

Was Hermetry prüft:

  • Das Image besteht aus einer ganzen Anzahl von 4-KiB-Sektoren, ist mindestens 8 KiB groß, und sein letzter 4-KiB-Sektor enthält den Signaturblock.
  • Der erste Signaturblock ist ein Block der Version 2, und der darin enthaltene Image-Hash entspricht dem SHA-256 aller Daten vor dem Signatursektor.
  • Der SHA-256 des öffentlichen Schlüssels in diesem Block entspricht einem Ihrer registrierten ESP32-Schlüsselhashes. Verglichen wird nur der erste Signaturblock: Signieren Sie mit mehreren Schlüsseln, registrieren Sie den Schlüssel, der zuerst signiert.

Hermetry prüft die RSA-Signatur selbst nicht: Das Bootloader des Geräts erzwingt sie. Die Prüfung von Hermetry verhindert, dass ein für den falschen Schlüssel erstelltes Image ausgerollt wird. Bei diesen Images ist fw_sig gleich esp-secure-boot.

Signaturschlüssel registrieren

Nur Eigentümer können Signaturschlüssel hinzufügen oder widerrufen.

  1. Öffnen Sie Firmware und dann Signing keys.
  2. Wählen Sie Add key.
  3. Geben Sie ihm einen Name (1 bis 120 Zeichen) und wählen Sie seine Kind.
  4. Fügen Sie den Public key ein: bei usign die vollständige Datei .pub, bei ESP32 den 64-stelligen Schlüsselhash.
MeldungBedeutung
Dies ist kein öffentlicher Schlüssel der gewählten Art.Der Text ist keine usign-Schlüsseldatei oder kein 64-stelliger Hex-Hash
Dieser Schlüssel ist bereits registriert.Ein aktiver Schlüssel dieser Art mit demselben Fingerabdruck existiert bereits

Um Schlüssel zu wechseln, registrieren Sie den neuen öffentlichen Schlüssel, bevor das erste mit ihm signierte Image hochgeladen wird. Das Widerrufen eines Schlüssels widerruft jedes mit ihm signierte Paket, und Updates mit diesen Paketen, deren Installation noch nicht begonnen hat, werden gestoppt. Widerrufen Sie einen Schlüssel nur dann, wenn seine Images nicht mehr installiert werden dürfen.

Was der Upload prüft

Beim Hochladen eines Pakets prüft Hermetry in dieser Reihenfolge:

  1. Der SHA-256 der Datei entspricht der mitgesendeten Prüfsumme. Das Upload-Formular berechnet sie in Ihrem Browser; vergleichen Sie sie mit der, die Ihr Build erzeugt hat.
  2. Die Signatur, geprüft gegen Ihre aktiven Signaturschlüssel der gewählten Art.
  3. Einen Virenscan. Das Paket ist Ready, wenn der Scan sauber ist.

Das größte Paket ist standardmäßig 64 MiB groß. Eine abgelehnte Signatur nennt den Grund:

MeldungAbhilfe
Die Signatur hat nicht das erwartete Format. Wählen Sie die .sig-Datei, die für dieses Image erstellt wurde.Laden Sie die .sig-Datei hoch, die mit usign -S erstellt wurde, oder ein ESP32-Image, das mit seinem Signatursektor endet
Das Image ist mit einem Schlüssel signiert, der hier nicht registriert ist. Fügen Sie zuerst dessen öffentlichen Schlüssel unter „Signing keys“ hinzu.Registrieren Sie den öffentlichen Schlüssel (usign) bzw. den Schlüsselhash (ESP32) und laden Sie dann erneut hoch
Die Signatur passt nicht zu diesem Image. Wählen Sie die .sig-Datei, die für genau diese Datei erstellt wurde.Die Datei wurde nach dem Signieren geändert, oder die Signatur gehört zu einer anderen Datei. Signieren Sie die endgültige Datei erneut.

Checkliste für einen Release-Build

  • Geben Sie dem Paket den Titel und die Version, die Ihr Gerät nach dem Start als current_fw_title und current_fw_version meldet.
  • Signieren Sie das endgültige Image zuletzt; ändern Sie es danach nicht mehr.
  • Bewahren Sie geheime Schlüssel in Ihrer Release-Pipeline auf. Hermetry benötigt nur den öffentlichen Teil.
  • Verwenden Sie Not signed nur mit einem Testprofil, das unsignierte Images erlaubt.
  • Das Gerät muss ein Image ablehnen, dessen Signatur nicht geprüft werden kann, auch wenn die Prüfsumme übereinstimmt.