Device certificates

Licensed devices log in with an X.509 client certificate instead of a password. Hermetry runs its own certificate authority (CA) for devices. This page explains what you see and do as a customer. The design of the CA is described in The device certificate authority.

How it works

• The device makes its own key pair. The private key never leaves the device.
• The device sends a certificate signing request (CSR) to Hermetry over v1/csr and receives its certificate on v1/cert.
• The certificate’s common name (CN) is the device serial.
• At every login, Hermetry checks that the certificate chains to its device CA, is not revoked, is not expired, and that CN = serial = client ID.

The root keys of the CA are kept offline. Online signing keys are sealed and held by one isolated process. Hermetry never shows or exports a CA private key.

Certificate lifetime

Item	Value
Lifetime	365 days by default (30 to 825, set on the device’s profile)
Renewal	Starts at the latest 30 days before expiry. The cloud can also ask a device to renew with the cert.renew command.
Key type	ECDSA P-256 for current licensed devices

A device whose certificate expired, was revoked or was lost goes through recovery: it provisions again and asks for a new certificate. A device that asks for a new certificate while its current one is still valid needs your approval: you get a notice “A device asks for a new certificate” and approve it on the device page if you reset or repaired the device.

Where you see certificates

You need the permission to view certificates (administrators by default).

• Devices > ⋯ > Certificates lists your organisation’s device certificates with their status: Active, Superseded, Revoked or Expired, and how many days are left.
• An MQTT device’s Certificate tab shows its certificate, how it was issued (First certificate (factory), Renewal, Recovery, Server-generated key, Uploaded, Enrolment) and its validity.
• Device Certificate Settings set Expiry warning (days) (30 to 180, 30 by default): administrators are told about certificates that expire within that many days and have not been renewed.

Use a certificate as a device’s credential

Licensed devices that you claim get their certificate credential automatically. To switch another device to its certificate, use the API: PUT …/api/iot/devices/{deviceId}/credentials with {"type": "X509_CERTIFICATE", "certificateId": "…"}. The certificate must be active, belong to your organisation, and have the device serial as CN. See Device credentials.

Revoke a certificate

1. Open the certificate.
2. Select Revoke certificate and give the reason: Key compromise, Superseded, Device retired or Unspecified.

“The device is disconnected at once and cannot connect with this certificate again. This cannot be undone.” It is refused at its next login (CONNACK 5). Revocations are published in the CA’s revocation list.

Certificates from other authorities

Uploading your own CA for third-party X.509 devices is not available. Third-party devices use access tokens or MQTT basic.