Echtes Gateway registrieren¶

Zweck¶

Welche Werte Gerät hinzufügen für ein echtes Gateway mit TPM braucht, und wie Sie jeden davon am Gateway selbst ablesen. Zum Hinzufügen des Geräts brauchen Sie die Rolle Org Admin oder Editor.

Was Sie eintragen¶

Feld	Pflicht	Woher der Wert kommt	Braucht das TPM?
EUI	Ja	Die EUI-64 des Gateways, 16 Hex-Zeichen, z. B. `0000000000000001`. Sie steht auf dem Typenschild, manchmal mit Doppelpunkten, Bindestrichen, Punkten oder Leerzeichen: Sie können sie mit oder ohne eintippen. Gespeichert wird sie als 16 Zeichen in Kleinbuchstaben.	Nein
Serial	Ja	Die Seriennummer auf dem Typenschild. Freier Text, außer die Bestellung Ihrer Organisation legt ein Format fest.	Nein
AK fingerprint	Ja	Vom Hersteller, mit dem Gateway: aus seiner Chargenliste oder von seinem Etikett. Nur wenn Sie ihn nicht haben, aus dem TPM des Gateways lesen, siehe unten. 64 Hex-Zeichen in Kleinbuchstaben.	Nur bei Weg A und B
Name	Nein	Alles, woran Sie das Gateway wiedererkennen.	Nein

Warum der AK-Fingerprint und nicht das EK-Zertifikat. Die Plattform erkennt ein Gateway mit TPM allein an seinem AK-Fingerprint: dem SHA-256-Hash des öffentlichen Teils des Attestierungsschlüssels (AK), den der Bootstrap-Agent in seinem TPM ableitet. Ein Gerät ohne diesen Wert könnte die Plattform nie finden, wenn sich das Gateway meldet. Das EK-Zertifikat brauchen Sie zum Registrieren nicht, und der Dialog Add device fragt auch nicht danach. Welche Zertifikate ein Gateway trägt und wie die Plattform sie prüft: Wie die Geräteidentität funktioniert.

Woher der AK-Fingerprint kommt¶

Der übliche Weg: vom Hersteller¶

Der Hersteller liest den AK-Fingerprint aus, wenn er das Gateway baut, und gibt ihn mit dem Gateway weiter: in der Chargenliste (eine Zeile pro Gateway mit EUI, Seriennummer und AK-Fingerprint) oder auf dem Etikett des Gateways. Nehmen Sie ihn von dort. Für viele Gateways auf einmal geht die Chargenliste über Massenimport und Claim als Spalte ak_fingerprint ein. Auf dem Gateway läuft dafür nichts.

Wenn Sie ihn nicht vom Hersteller haben¶

Die beiden Wege unten sind Notlösungen für ein einzelnes Gateway. Das TPM eines Gateways hat nur sehr wenige Plätze für geladene Schlüssel: drei auf der Referenz-Hardware. Der Agent braucht sie bei jedem Check-in. Ein Schlüssel, der geladen bleibt, belegt einen Platz, bis das TPM geleert wird. Sind alle Plätze belegt, meldet sich das Gateway nicht mehr. Bei jedem Befehl unten steht deshalb, ob er einen Platz belegt.

Weg A: die Plattform liest ihn aus (kein zusätzlicher TPM-Befehl)¶

Bereiten Sie das Gateway vor und installieren Sie die Gateway-Software wie in Erste Schritte, Schritt 7, beschrieben.
Das Gateway meldet sich von selbst bei der Plattform. Weil es noch nicht registriert ist, weist die Plattform es ab („unbekanntes Gerät“) und merkt sich den AK-Fingerprint dieses Versuchs.
Fragen Sie den Support nach dem Fingerprint und nennen Sie die Uhrzeit, zu der das Gateway gestartet wurde. Fügen Sie das Gerät dann damit hinzu.
Starten Sie den Agenten neu, damit er es sofort erneut versucht: systemctl restart bootstrap-agent.service. Sonst wartet er nach der Abweisung eine Stunde.

Auf dem Gateway läuft dabei nichts außer dem normalen Start des Agenten.

Weg B: am Gateway berechnen¶

Dafür brauchen Sie tpm2-tools 5.x auf dem Gateway und eine Root-Shell.

Nur /dev/tpmrm0 verwenden, nie /dev/tpm0

Die Befehle unten müssen über den Ressourcenmanager des Kernels laufen (/dev/tpmrm0). Er entlädt die Schlüssel eines Befehls, sobald dieser endet. Laufen tpm2_createprimary und tpm2_readpublic direkt gegen /dev/tpm0, bleibt nach jedem ein Schlüssel geladen, und diese zwei Plätze bleiben belegt, bis jemand das TPM leert.

Ist der Agent schon installiert, halten Sie ihn zuerst an, damit er nicht um die Plätze konkurriert:
```
systemctl stop bootstrap-agent.service
```
Wechseln Sie dann in ein beschreibbares Verzeichnis für die Dateien der nächsten Schritte, und richten Sie die Werkzeuge auf den Ressourcenmanager:
```
cd /tmp
export TPM2TOOLS_TCTI=device:/dev/tpmrm0
```

Notieren Sie die freien Plätze. Belegt keinen Platz.

tpm2_getcap properties-variable | grep TPM2_PT_HR_TRANSIENT_AVAIL

Schreiben Sie den unique-Wert der Schlüsselvorlage: eine 2 Byte lange Längenangabe (256, little-endian), gefolgt von 256 Null-Bytes. Ohne TPM.
```
{ printf '\x00\x01'; head -c 256 /dev/zero; } > ak-unique.bin
```
Mit einer Datei aus nur 256 Null-Bytes, oder ganz ohne -u, leitet das TPM einen anderen Schlüssel ab, und der Fingerprint passt nicht.

Leiten Sie den AK des Agenten ab. Belegt einen Platz, solange der Befehl läuft; danach wird er frei.

tpm2_createprimary -C o -g sha256 -G rsa2048:rsassa-sha256:null -a 'fixedtpm|fixedparent|sensitivedataorigin|userwithauth|restricted|sign' -u ak-unique.bin -c ak.ctx

Exportieren Sie seinen öffentlichen Teil. Belegt einen Platz, solange der Befehl läuft; danach wird er frei.
```
tpm2_readpublic -c ak.ctx -f tss -o ak.pub
```
Berechnen Sie den Fingerprint: SHA-256 über den öffentlichen Teil, ohne das 2 Byte lange Größenfeld, das tpm2_readpublic voranstellt. Ohne TPM.
```
tail -c +3 ak.pub | sha256sum | cut -d' ' -f1
```

Prüfen Sie die freien Plätze erneut. Belegt keinen Platz. Die Zahl muss dieselbe sein wie in Punkt 2. Starten Sie dann den Agenten wieder:

tpm2_getcap properties-variable | grep TPM2_PT_HR_TRANSIENT_AVAIL

systemctl start bootstrap-agent.service

rm -f ak.ctx ak.pub ak-unique.bin

Wie dieses Rezept geprüft wurde

Am 2026-11-11 lief jeder Befehl oben genau so auf dem Labor-Gateway (armv7, Hardware-TPM, tpm2-tools 5.5, mit dem Agenten von cproto-v0.2.0-rc.2 installiert): vorher 3 freie Plätze und nachher 3, und der in Schritt 6 ausgegebene Fingerprint war genau der, der für dieses Gerät in der Konsole hinterlegt ist. Schon am 2026-09-29 stimmte dasselbe Rezept auf einem Software-TPM (swtpm, tpm2-tools 5.4) mit dem Wert des Agenten überein.

Ergebnis¶

Das Gerät steht unter Devices mit der Markierung Manually created und dem Status CLAIMED, wie unter Gerät hinzufügen. Beim nächsten Check-in erkennt die Plattform das Gateway an seinem AK-Fingerprint, und der Status wechselt zu PROVISIONED (siehe Erste Schritte, Schritt 8).

Wenn etwas schiefgeht¶

Anzeichen	Was Sie tun
`ak_fingerprint must be 64 hex characters…`	Kopieren Sie nur den 64 Zeichen langen Hash aus Punkt 6, sonst nichts.
Das Gateway meldet sich, wird aber nicht erkannt	Der Fingerprint wurde mit einer anderen Vorlage berechnet. Wiederholen Sie die Punkte 3 bis 6 genau, oder nehmen Sie Weg A.
Punkt 7 zeigt weniger freie Plätze als Punkt 2	Ein Schlüssel ist geladen geblieben, meist weil die Befehle gegen `/dev/tpm0` liefen. Starten Sie den Agenten nicht; wenden Sie sich an den Support.