Register a device's identity¶

Purpose¶

Every TPM gateway is registered with exactly one identity, so the platform knows which gateway may connect as this device. You choose one of two methods:

AK fingerprint: the fingerprint of the gateway's TPM attestation key, as before. See Add device.
Identity certificate: the gateway's own X.509 certificate, the one it presents when it connects. The platform accepts the gateway only with exactly this certificate, byte for byte, together with its TPM proof.

Use the certificate method when your gateways already carry an individual certificate and you know each one before the gateway first connects, for example from your production line.

Prerequisites¶

Signed in, see Sign in.
The role Org Admin or Editor to add devices, Org Admin to change an identity later.
For the certificate method: the gateway's certificate as a PEM file (-----BEGIN CERTIFICATE-----) or as base64 DER on one line. Public certificate only, never its private key.

When an identity is required¶

Where the device is added	Identity
Add device, any order	Required: AK fingerprint or identity certificate.
CSV import into an order with the trust anchor Allowlist or Vendor chain (TPM modes)	Required per `tpm` row: `ak_fingerprint` or `identity_cert`.
CSV import into an order with a device CA	Optional: the device's certificate from that CA is what proves it.
`soft` rows	No identity column applies.

A row or a device gets one method, never both.

Certificate rules¶

The certificate is checked when you register it, not only when the gateway connects:

exactly one certificate; a chain or a private key is refused;
a key of type EC P-256, EC P-384 or RSA with at least 2048 bits;
not expired;
if the device joins an order that has a device CA, the certificate must be issued directly by that CA;
each certificate belongs to one device only.

When the gateway connects, the platform compares the certificate it presents with the registered one. Any other certificate is refused, also one from the same CA for the same EUI. The TPM proof is always required on top. Once the gateway has connected successfully, its TPM key is recorded: if it later presents no certificate or an expired one, it is still accepted on its TPM proof alone, never with a different certificate.

Steps¶

Add a single device¶

Go to Devices, click Add device, fill in EUI and serial, see Add device.
Under Identity, choose Identity certificate.
Paste the certificate into Device certificate (PEM or base64 DER), or upload a .pem, .crt or .der file. The dialog shows the subject, a short fingerprint and the expiry date. The server checks the certificate again when you save.
Optional: under Order, pick one of your organisation's orders. The device joins that order and, if the order has a device CA, its certificate is checked against that CA. Leave Manual entry (this organisation) to add it as before.
Click Create device.

Import many devices¶

In Orders, click Import devices from CSV, then Download the template. It has the columns eui, serial_number, attestation_level, ak_fingerprint and identity_cert.
Per row, fill in either ak_fingerprint or identity_cert. A PEM certificate spans several lines, so put it in double quotes; a base64 DER certificate fits on one line without quotes. Both forms are recognised automatically.
Upload the file. The preview blocks rows that give both methods, neither, or a cell that is not a certificate.
Click Commit N valid rows. Every rejected row is listed with its row number and reason; the other rows are imported.

Update identities with a new import¶

To replace the identity of devices that are already in this order, for example after new certificates were issued, import a CSV with those devices and tick Update the identity of devices already in this order (EUI, serial and order stay unchanged).

A row whose EUI is already in this order updates that device's identity only. Its EUI, serial, order and template stay as they are.
A row with a new EUI is imported as usual.
The result counts imported and updated devices separately.
Without the tick, a row with an EUI that already exists is an error, as before.

Change one device's identity¶

In the device page, click Edit device. Under Identity you can paste a new certificate to replace the registered one, or switch to AK fingerprint. Switching to the AK fingerprint removes the registered certificate.

Expected result¶

The device page shows a Registered identity card with the method, the certificate fingerprint (with a copy button), the subject and Valid until. A badge shows the certificate's state:

Badge	Meaning
Valid	More than 30 days until it expires.
Expires soon	Expires within 30 days. Register the gateway's new certificate in time.
Expired	A gateway that has never connected is refused. One that connected before is still accepted on its TPM proof alone. Register its new certificate.

Each registration and change of an identity is recorded in the audit log with the certificate's fingerprint. The certificate itself is not shown in logs.

Common errors¶

Exact message	What to do
"This contains a private key. Paste the device's certificate only."	Export the certificate without its key.
"Paste exactly one certificate (PEM or base64 DER)."	Paste the device's own certificate, not its chain.
`identity_cert has expired`	Register the gateway's current certificate.
`identity_cert does not chain to this order's CA`	The certificate was not issued by the order's device CA. Pick the right order, or register the CA, see Register your device CA.
`identity_cert key must be EC P-256/P-384 or RSA >= 2048`	The key type or size is not accepted. Issue a certificate with a supported key.
`a device with this identity_cert already exists` / `identity_cert already registered to another device`	This certificate is registered for another device. Check the file; each gateway needs its own.
`Give either ak_fingerprint or identity_cert, not both`	Leave one of the two cells empty.
`Missing ak_fingerprint or identity_cert`	The order requires an identity for `tpm` rows. Fill one in.
`an identity is required for this order: ak_fingerprint or identity_cert`	The same check, made by the server.