Register a real gateway¶

Purpose¶

Which values Add device needs for a real gateway with a TPM, and how to read each one on the gateway itself. Adding the device needs the role Org Admin or Editor.

What to enter¶

Field	Required	Where it comes from	Uses the TPM?
EUI	Yes	The gateway's EUI-64, 16 hex characters, e.g. `0000000000000001`. Printed on the gateway label, sometimes with colons, dashes, dots or spaces: you can type it with or without them. It is stored as 16 lowercase characters.	No
Serial	Yes	The serial number on the gateway label. Free text unless your organisation's order sets a serial format.	No
AK fingerprint	Yes	From the manufacturer, with the gateway: its batch list or its label. Only if you do not have it, read it from the gateway's TPM, see below. 64 lowercase hex characters.	Only for Options A and B
Name	No	Anything that helps you recognise the gateway.	No

Why the AK fingerprint and not the EK certificate. The platform recognises a TPM gateway by its AK fingerprint alone: the SHA-256 of the public part of the attestation key (AK) the Bootstrap-Agent derives in its TPM. A device entered without it could never be found when the gateway calls in. The EK certificate is not needed to register a device, and the Add device dialog does not ask for it. Which certificates a gateway carries and how the platform checks them: How device identity works.

Where the AK fingerprint comes from¶

The usual way: from the manufacturer¶

The manufacturer reads the AK fingerprint when it builds the gateway and hands it over with the gateway: in the batch list (one line per gateway with EUI, serial and AK fingerprint), or printed on the gateway's label. Take it from there. For many gateways at once, the batch list goes into Bulk import and claim as the ak_fingerprint column. Nothing runs on the gateway for this.

If you do not have it from the manufacturer¶

The two options below are fallbacks for a single gateway. A gateway TPM has very few slots for loaded keys: three on the reference hardware. The agent needs them for every check-in. A key left loaded takes a slot until the TPM is flushed, and the gateway stops checking in once all slots are taken. Every command below is marked with its slot use.

Option A: let the platform read it (no extra TPM command)¶

Prepare the gateway and install the gateway software as described in First steps, step 7.
The gateway calls the platform on its own. Because it is not registered yet, the platform refuses it ("device unknown"), and records the AK fingerprint of that attempt.
Ask support for the fingerprint, giving the time the gateway was started. Then add the device with it.
Restart the agent so it tries again at once: systemctl restart bootstrap-agent.service. Otherwise it waits an hour after being refused.

This runs nothing on the gateway beyond the agent's own normal start-up.

Option B: compute it on the gateway¶

Needs tpm2-tools 5.x on the gateway and a root shell.

Use /dev/tpmrm0, never /dev/tpm0

The commands below must go through the kernel's resource manager (/dev/tpmrm0), which unloads a command's keys when it exits. Run directly against /dev/tpm0, tpm2_createprimary and tpm2_readpublic each leave one key loaded, and those two slots stay taken until someone flushes the TPM.

If the agent is already installed, stop it first so it does not compete for slots:
```
systemctl stop bootstrap-agent.service
```
Then go to a writable directory for the files of the next steps, and point the tools at the resource manager:
```
cd /tmp
export TPM2TOOLS_TCTI=device:/dev/tpmrm0
```

Note the free slots. Uses no slot.

tpm2_getcap properties-variable | grep TPM2_PT_HR_TRANSIENT_AVAIL

Write the key template's unique value: a 2-byte length (256, little-endian) followed by 256 zero bytes. No TPM.
```
{ printf '\x00\x01'; head -c 256 /dev/zero; } > ak-unique.bin
```
With a plain 256-zero-byte file, or no -u at all, the TPM derives a different key and the fingerprint will not match.

Derive the agent's AK. Uses one slot while it runs; released when it exits.

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

Export its public part. Uses one slot while it runs; released when it exits.
```
tpm2_readpublic -c ak.ctx -f tss -o ak.pub
```
Compute the fingerprint: SHA-256 over the public area, without the 2-byte size prefix tpm2_readpublic writes. No TPM.
```
tail -c +3 ak.pub | sha256sum | cut -d' ' -f1
```

Check the free slots again. Uses no slot. The number must equal step 2. Then start the agent again:

tpm2_getcap properties-variable | grep TPM2_PT_HR_TRANSIENT_AVAIL

systemctl start bootstrap-agent.service

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

How this recipe was checked

On 2026-11-11 every command above was run as written on the lab gateway (armv7, hardware TPM, tpm2-tools 5.5, with the agent of cproto-v0.2.0-rc.2 installed): 3 free slots before and 3 after, and the fingerprint printed in step 6 was exactly the one stored for that device in the console. Earlier, on 2026-09-29, the same recipe matched the agent's own value on a software TPM (swtpm, tpm2-tools 5.4).

Expected result¶

The device appears in Devices with a Manually created badge and the status CLAIMED, as in Add device. The next time the gateway calls in, the platform recognises it by the AK fingerprint, and the status moves on to PROVISIONED (see First steps, step 8).

If something goes wrong¶

Symptom	What to do
`ak_fingerprint must be 64 hex characters…`	Copy only the 64-character hash from step 6, nothing else.
The gateway calls in but stays unrecognised	The fingerprint was computed with a different template. Redo steps 3–6 exactly, or use Option A.
Step 7 shows fewer free slots than step 2	A key stayed loaded, usually because the commands ran against `/dev/tpm0`. Do not start the agent; contact support.