This page is for firmware authors and security reviewers. It explains which certificates a device must trust when it connects to Hermetry, which certificates Hermetry accepts from devices, and what changes over time. How the device certificate authority is built and run is in The device certificate authority.
Two directions of trust
| Direction | Who checks | Against what |
|---|---|---|
| The broker’s server certificate | Your device, when it opens TLS to the MQTT broker | Public root certificates (a normal CA bundle) and the host name |
| A device’s client certificate (X.509 login) | Hermetry, when a device presents a certificate | Hermetry’s own device certificate authority only |
A device that logs in with an access token or MQTT basic needs only the first row. A device with an X.509 certificate needs both.
What your devices must trust
The broker on port 8883 presents a public certificate for the broker host, the host shown on the device’s Connection details card.
- Verify the server certificate against public root certificates and check the host name. Connect by host name, never by IP address, so the host name check can pass.
- Do not pin the server certificate. It is replaced automatically before it expires, and a device that pins it stops connecting after the next renewal.
- Keep the CA bundle on the device, and make it replaceable through a firmware update.
- Set the clock (NTP) before you open TLS. A device with a wrong clock sees a valid certificate as expired or not yet valid.
When the certificate is renewed, the broker starts using the new one without closing connected devices. A device sees the new certificate at its next TLS handshake.
What Hermetry accepts from devices
A client certificate is accepted only when it was issued by one of Hermetry’s device issuing CAs. A certificate from a public CA, from your own CA, or signed directly by a root ends the TLS handshake. There is no fall-back to a password. Uploading your own CA is not available; see Device credentials.
At every X.509 login Hermetry also checks:
| Check | If it fails |
|---|---|
| The certificate is inside its validity period | Refused with CONNACK 5, so the device can start recovery |
It is a client certificate (not a CA, with client authentication) and its subject is exactly CN=<serial> | Refused with CONNACK 5 |
| It is not revoked | Refused with CONNACK 5 |
| It is the device’s active X.509 credential, and its CN is that device’s serial | Refused with CONNACK 5 |
| The list of revoked certificates is loaded | While it is not, X.509 logins get CONNACK 3 and the device retries |
Hermetry reloads the list of trusted issuing CAs at every change and every 10 minutes. Revocation is checked at every login and again on every live session about every 60 seconds.
The device certificate hierarchy
| Certificate | Valid for | Signs |
|---|---|---|
| Root G1 | 20 years | The issuing CAs in use |
| Root G2 | 25 years | Nothing today. A spare root, created in the same ceremony as G1 and kept offline. |
| Device issuing CA | 5 years; it issues new certificates for at most 24 months | Device certificates |
| Device certificate | 365 days by default (30 to 825, set on the device profile) | Nothing |
The roots and issuing CAs use ECDSA P-256 keys. With its certificate, a device receives the certificate of the issuing CA that signed it (chain in the v1/cert answer).
What changes, and what you do
| Change | When | What devices notice | Your action |
|---|---|---|---|
| Broker server certificate renewed | Automatically, before it expires | The new certificate at the next TLS handshake. Connected devices stay connected. | None, if devices trust public roots and pin nothing below them |
| Device certificate renewed | The device renews at the latest 30 days before expiry. Hermetry asks with cert.renew when 21 days or fewer are left. | A new certificate. The old one keeps working until 24 hours after the new one is first used, then it is revoked as superseded. | Keep devices online and on current firmware. Act on the renewal notices. |
| Issuing CA rotated | After at most 24 months of issuing | Nothing. The old CA stays trusted and keeps publishing its revocation list until its last certificate expires. Renewals get certificates from the new CA. | None |
| Root reaches the end of its life | G1 is valid for 20 years | Nothing on the device side: Hermetry, not the device, checks client certificates | None. Hermetry’s operators are alerted when a root has less than 3 years left. |
How a device certificate gets renewed
- The device renews by itself. It sends a new certificate signing request (CSR) on
v1/csrover its own TLS session, at the latest 30 days before its certificate expires. One renewal an hour is accepted per device. - Each day Hermetry looks for certificates with 21 days or fewer left. If the device has sent no CSR in the last 7 days, is online and has announced that it handles the method, it gets
cert.renewonce. An offline device is asked again the next day. - An administrator can select Renew certificate on the device page. It is offered when fewer than 30 days are left, or when the platform generated the certificate’s key.
- If nothing has happened 7 days after
cert.renew, the organisation’s owners and administrators get the notice “Devices did not renew their certificates”. - A certificate that expires is refused with CONNACK 5. The device then goes through recovery. See Device certificates.
Owners and administrators are also told every day about certificates that expire within the Expiry warning (days) (30 by default, 30 to 180) and have no newer certificate. See Device security alerts.
Revocation lists
Each issuing CA publishes a signed certificate revocation list (CRL) that is valid for 7 days and is signed again at least once a day. Your devices do not need to download it to log in to Hermetry: Hermetry checks revocation itself, at the login and during the session.
Checklist for firmware
- Connect over TLS by host name and verify the chain against public roots and the host name.
- Pin nothing below a root certificate. Ship the CA bundle so a firmware update can change it.
- Keep the clock right before the first TLS handshake.
- For X.509 devices: renew at the latest 30 days before expiry, answer
cert.renew, and keep the current certificate until the new one is in use.

