Zum Inhalt

English

Mit Yocto und RAUC installieren

Für Hersteller, die ihr Gateway-Image selbst mit Yocto bauen und mit RAUC aktualisieren. Ein Agent kommt in Ihr Image: der Bootstrap-Agent, ein einziger Dienst, der als eigener unprivilegierter Benutzer läuft. Das Starten Ihrer Software, die LEDs und das Löschen von Daten überlässt er Ihnen. Einen Überblick gibt Gateway-Überblick.

Release-Kandidat

Diese Seite beschreibt cproto-v0.2.0-rc.2, einen Release-Kandidaten. Das Rezept in diesem Release verweist noch auf den vorigen Kandidaten (cproto-v0.2.0-rc.1): Setzen Sie RELEASE, PV und die beiden SHA-256-Pins darin mit der Tabelle unten auf dieses Release um, bevor Sie ein Image damit bauen. Das Rezept in unserem Layer verweist bereits auf dieses Release.

Was Sie bekommen

Ein signiertes Release-Archiv pro Version, drei Dateien: das Archiv bootstrap-agent-cproto-v0.2.0-rc.2-linux-armv7.tar.gz, seine Signatur (.sig) und seine Prüfsumme (.sha256). Das Archiv enthält:

Pfad im Archiv Was
bootstrap-agent der Agent (armv7, dynamisch gelinkt)
systemd/bootstrap-agent.service die eine Service-Unit
examples/ die Beispiele für .path und .service aus Software starten und bestätigen
tmpfiles/bootstrap-agent.conf legt das Zustandsverzeichnis und das Socket-Verzeichnis an
env/bootstrap-agent.env Konfigurations-Vorgabe
local-api-v1.openapi.yaml, wire-v1.md der Vertrag der lokalen Schnittstelle und der Vertrag mit der Plattform
VERSION, CHECKSUMS.sha256 die Version und eine Prüfsumme für jede andere Datei

Das Archiv enthält kein Installationsskript, und der Agent lädt kein Programm herunter: Er holt nur seine Konfiguration.

Download

Die drei Dateien des Releases cproto-v0.2.0-rc.2, ohne Konto:

https://packages.pxdc.io/bootstrap-agent/cproto-v0.2.0-rc.2/bootstrap-agent-cproto-v0.2.0-rc.2-linux-armv7.tar.gz
https://packages.pxdc.io/bootstrap-agent/cproto-v0.2.0-rc.2/bootstrap-agent-cproto-v0.2.0-rc.2-linux-armv7.tar.gz.sig
https://packages.pxdc.io/bootstrap-agent/cproto-v0.2.0-rc.2/bootstrap-agent-cproto-v0.2.0-rc.2-linux-armv7.tar.gz.sha256
Datei SHA-256
bootstrap-agent-cproto-v0.2.0-rc.2-linux-armv7.tar.gz fad9e36e7b3b412f198effcda621d55cab0c4963aa98c8d1f8ba332c8ee65700
bootstrap-agent-cproto-v0.2.0-rc.2-linux-armv7.tar.gz.sig ce2d4a9d8ea9a99c707ce93f4640a0274c0e44d3252bc6ba825f073b32b117a8
bootstrap-agent-cproto-v0.2.0-rc.2-linux-armv7.tar.gz.sha256 fc4a8295998ceb8030e6c7ebb1f7ae4deefc21f2427c2fcc4a997f9ba1db2b47

Signatur prüfen

Die Signatur ist Ed25519, erzeugt mit dem eigenen Release-Schlüssel des Agenten. Der Schlüssel ist stabil: Es gibt keine Schlüssel pro Release.

Sie brauchen sha256sum und OpenSSL 3. Ältere Versionen kennen die Option -rawin nicht, die die Prüfung benutzt: OpenSSL 1.1.1 und LibreSSL 3.3 brechen mit unknown option -rawin ab; OpenSSL 3.5 und 3.6 funktionieren.

1. Speichern Sie den öffentlichen Schlüssel als wlpc-agent-ed25519.pub. Er liegt auch in unserem Yocto-Layer unter demselben Namen.

-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAN8+mCK4/qSV4xO6uFNHrc5+8Dje5wK609NI7WEGqYa4=
-----END PUBLIC KEY-----

2. Vergleichen Sie den Fingerabdruck mit dem unten, der auf dieser Seite steht, nicht im Download-Verzeichnis, und mit dem, den Ihnen der Support getrennt schickt. Ein Schlüssel vom selben Ort wie das Archiv beweist für sich nichts; erst die zweite Quelle macht die Prüfung etwas wert.

openssl pkey -pubin -in wlpc-agent-ed25519.pub -outform DER | sha256sum
# 79c12a4d7b4cc3868129a0afac587fd2441246e5c61382bd8221bc2ec52d402a

3. Prüfen Sie die drei heruntergeladenen Dateien in einem Verzeichnis:

sha256sum -c bootstrap-agent-cproto-v0.2.0-rc.2-linux-armv7.tar.gz.sha256
openssl pkeyutl -verify -pubin -rawin -inkey wlpc-agent-ed25519.pub \
  -sigfile bootstrap-agent-cproto-v0.2.0-rc.2-linux-armv7.tar.gz.sig \
  -in bootstrap-agent-cproto-v0.2.0-rc.2-linux-armv7.tar.gz

Signature Verified Successfully ist die einzige gute Antwort. Ein geändertes Byte im Archiv oder eine Signatur mit einem anderen Schlüssel wird abgelehnt. Prüfen Sie danach die Dateien im Archiv gegen CHECKSUMS.sha256:

mkdir agent-files
tar -xzf bootstrap-agent-cproto-v0.2.0-rc.2-linux-armv7.tar.gz -C agent-files
(cd agent-files && sha256sum -c CHECKSUMS.sha256)

Das Yocto-Rezept

Das Rezept bootstrap-agent-c_1.0.bb in unserem Layer lädt das Archiv über HTTPS, lehnt es ab, wenn seine SHA-256 nicht der im Rezept festgelegten entspricht, prüft die Signatur gegen den festgelegten Schlüssel, bevor es entpackt, prüft CHECKSUMS.sha256 und installiert:

Pfad Was
/usr/bin/bootstrap-agent der Agent
/usr/lib/systemd/system/bootstrap-agent.service die eine Unit, per Preset aktiviert
/usr/lib/wlpc/bootstrap-agent.env Konfigurations-Vorgabe
/usr/lib/tmpfiles.d/bootstrap-agent.conf legt das Zustandsverzeichnis und das Socket-Verzeichnis an

Das Rezept legt außerdem den Benutzer bootstrap-agent und die Gruppen tss und wlpc an. Es installiert nur diese eine Unit, auch nicht die Beispiele. Ihre Software schreibt /run/wlpc als Mitglied der Gruppe wlpc; die tmpfiles-Regel aus dem Archiv legt dieses Verzeichnis für die Gruppe an, siehe Wer /run/wlpc schreiben darf. Eine neue Version zu wählen heißt, die Version und die beiden Hashes im Rezept zu ändern; nichts anderes ändert sich unbemerkt.

Bibliotheken und bekannte Probleme des Rezepts

Der Agent ist dynamisch gelinkt, Ihr Image muss also diese Bibliotheken liefern, und das Rezept führt sie als Abhängigkeiten auf: libtss2-esys.so.0, libtss2-mu.so.0, libcurl.so.4, libssl.so.3, libcrypto.so.3, libjson-c.so.5 und glibc (die höchste Symbolversion, die das Programm braucht, ist GLIBC_2.34).

Was für das Rezept geprüft wurde und was nicht:

  • Geprüft: Download, Hash-Pin, Signaturprüfung und do_install aus einem leeren Build-Verzeichnis, gegen das Rezept auf dem Entwicklungszweig, bei entfernten Build-Abhängigkeiten.
  • Offenes Problem 1, das Arbeitsverzeichnis. In einem vollständigen Testbau (Yocto scarthgap, qemuarm) hielt das Rezept in do_package an: S auf ${WORKDIR}/pkg verbirgt auch ${WORKDIR}/pkgdata vor dem Werkzeug, das Dateibesitz verfolgt. Eine Testkopie mit anderem Verzeichnisnamen kam daran vorbei. Das Rezept ist noch nicht geändert.
  • Offenes Problem 2, ein Versions-Tag der curl-Bibliothek. Danach meldete die Paketprüfung (file-rdeps), dass das Programm libcurl.so.4(CURL_OPENSSL_4) braucht und kein Paket es liefert: Das Programm wurde gegen eine curl-Bibliothek mit versionierten Symbolen gelinkt, die von Yocto gebaute hat keine. Nicht gelöst; ob das Programm gegen diese Bibliothek läuft, wurde nicht gemessen.
  • Nicht gemacht: kein Image-Bau (do_rootfs) und kein Start auf einem Yocto-Image.

Updates mit RAUC

Der Agent schreibt nur /etc/iot-config (seinen Zustand) und /run/bootstrap-agent; alles andere kann nur lesbar sein. Die Unit enthält RequiresMountsFor=/etc/iot-config, der Agent startet also nach diesem Mount. Der Zustand muss Neustarts und RAUC-Slot-Wechsel überleben:

  • Liegt /etc auf der Datenpartition, ist nichts weiter nötig.
  • Ist /etc auf Ihrem Image Teil des Root-Dateisystems, binden Sie /etc/iot-config von der Datenpartition ein. systemd akzeptiert die Mount-Unit nur unter dem aus dem Pfad abgeleiteten Namen, etc-iot\x2dconfig.mount (systemd-escape -p --suffix=mount /etc/iot-config); unter jedem anderen Namen ignoriert es die Unit, und der Zustand bleibt im Slot.
  • Ein Zustandsverzeichnis im Slot ist nach dem Wechsel leer, und das Gerät richtet sich neu ein.

Dieser Agent wurde noch nicht durch einen RAUC-A/B-Wechsel oder einen Rollback geführt. Testen Sie ihn auf Ihrem Image.

Einstellungen

Die Plattformadresse gehört in /etc/bootstrap-agent/agent.env, nie in das Image, damit dasselbe Image mit Ihrer eigenen Plattform-Instanz funktioniert. Die Unit liest zuerst die Vorgaben aus /usr/lib/wlpc/bootstrap-agent.env und danach diese Datei.

BOOTSTRAP_AGENT_URL=https://bootstrap.ztd.dev.pxdc.io
BOOTSTRAP_AGENT_TRUST_BUNDLE=
Einstellung Pflicht Bedeutung
BOOTSTRAP_AGENT_URL Pflicht Die Adresse der Plattform für Gateways. Ohne sie startet der Agent und bedient seine lokale Schnittstelle, meldet aber state: error.
BOOTSTRAP_AGENT_TRUST_BUNDLE Optional Leer: Das Zertifikat der Plattform wird gegen die Liste vertrauenswürdiger Stellen des Images geprüft. Die ausgelieferte Vorgabe zeigt auf /etc/bootstrap-agent/platform-ca.pem; gibt es diese Datei nicht, protokolliert der Agent reading trust bundle und erreicht die Plattform nicht. Nutzen Sie nur dann eine Datei, wenn der Support Ihnen eine gegeben hat.
BOOTSTRAP_AGENT_NTP_SERVERS Optional Zeitserver, durch Komma getrennt. Der Agent wartet, bis die Uhr mit einem davon übereinstimmt, bevor er irgendeine TLS-Verbindung öffnet. Leer: Er weist nur eine offensichtlich ungestellte Uhr ab.
BOOTSTRAP_AGENT_AK_HANDLE Optional Das TPM-Handle des Attestierungsschlüssels, siehe Das TPM.

Das TPM

Der Agent hält seinen Attestierungsschlüssel (AK) als ein persistentes Objekt im TPM, damit ein Start den Schlüssel liest, statt ihn neu abzuleiten.

  • Ein Handle, von Ihnen bestimmt. BOOTSTRAP_AGENT_AK_HANDLE in /etc/bootstrap-agent/agent.env: ein persistentes Handle im Owner-Bereich des TPM. Leer nimmt das Standard-Handle, das wir mit Ihnen abstimmen. off hält den Schlüssel transient.
  • Nur dieses Handle, nur solange es leer ist. Der erste Start macht den Schlüssel dort mit einem Aufruf von TPM2_EvictControl persistent und speichert seinen TPM-Namen in /etc/iot-config/ak. Liegt auf dem Handle etwas anderes, lässt der Agent es unberührt und arbeitet mit einem transienten Schlüssel.
  • Owner-Autorisierung. Ist eine Owner-Hierarchie-Autorisierung gesetzt, macht der Agent nichts persistent.
  • Werksreset. Bevor Ihr Reset die Datenpartition löscht, stoppen Sie den Agenten und führen bootstrap-agent --release-ak aus. Es entfernt den Schlüssel des Agenten, und nur, wenn das Objekt am gespeicherten Handle den gespeicherten Namen trägt.
  • Aufräumen beim Start. Beim Start entfernt der Agent seine eigenen übrig gebliebenen Schlüsselobjekte (in der Form eines Endorsement- oder Attestierungsschlüssels), die er über /dev/tpmrm0 sieht. Er entfernt nichts anderes und berührt das Rohgerät /dev/tpm0 nicht, siehe TPM-Slots.

Das ist Ihre Sache

Das Starten und Beaufsichtigen Ihrer Gateway-Software, die LEDs und das Löschen von Daten (ein Werksreset) gehören zu Ihrem Image. Der Agent tut nichts davon; für seinen Schlüssel im TPM führt Ihr Reset zuerst bootstrap-agent --release-ak aus (oben). Wie Ihre Software startet und ihr Ziel bestätigt: Software starten und bestätigen. Wie sie ihre Konfiguration liest: Referenz der lokalen API.