Licensed devices sign in with X.509 client certificates issued by Hermetry’s own certificate authority (CA). This page describes how the CA is built and run, for security reviews. What you see and do as a customer (the certificate list, renewing, revoking) is in Device certificates.
The hierarchy
| Level | Lifetime | Where its private key lives |
|---|---|---|
| Root CA (G1), with a pinned spare root (G2) | 20 years (G1), 25 years (G2) | Offline only, on removable media, wrapped under a key split between two custodians. Never in any database or online system. |
| Device issuing CA | 5 years, issuing for at most 24 months | Sealed in the database under a wrap key that only the signer process holds. |
| Server issuing CA | 5 years | Same as above. Issues the device host’s own TLS certificate. |
| Device certificates | 365 days by default (30 to 825, set on the device profile) | On the device only. |
All keys are ECDSA P-256 for current licensed devices.
The root key ceremony
Root keys are created in a recorded ceremony on a dedicated machine that is never networked, with two custodians and a witness. The key that wraps the root keys is split in two halves; each custodian holds one half, sealed in envelopes kept in safes at two sites. No single person and no single safe ever holds both halves. Only public material (certificates and revocation lists) is imported online. The root’s revocation list is re-signed yearly in the same way.
The signer
One isolated process, the signer, is the only holder of the wrap key for the issuing CAs. It signs device certificates and revocation lists and nothing else. The device gateway checks client certificates against the CA chain and the revocation set without ever seeing a CA key.
Issuing a certificate
- The device creates its own key pair. The private key never leaves the device.
- The device sends a certificate signing request (CSR) over its provisioning session.
- The provisioning worker checks who is asking and hands the request to the signer.
- The signer issues a certificate whose common name (CN) is the device serial, and records it in the certificate ledger.
The ledger records how each certificate was issued: First certificate (factory), Renewal, Recovery, Server-generated key, Uploaded or Enrolment. For a server-generated key the key is handed over once and never stored: “The platform generated this certificate’s key and handed it over once. Renew it so the device makes a key of its own.”
Checks at every connection
At every MQTT connection with a certificate, the gateway checks that:
- the certificate chains to a device issuing CA of Hermetry,
- it is not revoked (the gateway refuses every certificate while its revocation set is not loaded),
- it is not expired,
- its fingerprint matches the device’s active X.509 credential, and CN = serial = client ID.
A presented certificate always decides: there is no fallback to a password. An untrusted certificate ends the TLS handshake.
Renewal
Devices renew their certificate themselves before it expires, at the latest 30 days before. You can also ask a device to renew with Renew certificate (the cert.renew command); it keeps the current certificate until the new one is in use.
Administrators are told about certificates that expire within the Expiry warning (days) (30 to 180, default 30) and have not been renewed, and about devices that were asked to renew and did not.
Recovery
A device that asks for a new certificate while its current one is still valid could be a clone. Hermetry does not issue it automatically:
- You get the notice “A device asks for a new certificate”.
- On the device page, Approve revokes the current certificate at once and lets the device obtain a new one for the key shown, within 7 days. Reject keeps the current certificate and issues nothing.
- If the device tried with other keys while the request was open, the page warns: “Only the key shown here can be approved.”
Approve only if you reset or repaired the device.
Revocation
Revoking a certificate (Revoke certificate, with the reason Key compromise, Superseded, Device retired or Unspecified):
- marks it revoked in the ledger,
- adds its fingerprint to the gateway’s revocation set and disconnects the device at once, on every gateway node,
- lists it in the next revocation list.
“The device is disconnected at once and cannot connect with this certificate again. This cannot be undone.” To confirm, you type the device serial.
Each issuing CA publishes a signed certificate revocation list (CRL), renewed regularly and valid for 7 days. Hermetry is alerted if a list is not renewed in time.
Rotation of issuing CAs
An issuing CA issues for at most 24 months, then a new one takes over. The old CA keeps publishing revocation lists until its last certificate has expired. Devices trust the root, so a rotation needs no change on the devices.
Certificates from other authorities
Uploading your own CA for third-party devices is not available. Third-party devices use access tokens or MQTT username and password. See Device credentials.
Audit
Revocations, renewal requests, recovery requests and approvals, and certificate transfers are written to the audit log (iot_pki.certificate.revoked, iot_pki.certificate.renewal_requested, iot_pki.recovery.requested, iot_pki.recovery.approved). See What is audited.