New: the AI firewall watches the whole platform and explains each incident in plain words. See how it works

Root certificates and certificate changes

Which certificates your devices must trust, which certificates Hermetry accepts from devices, and what happens when a server, issuing or device certificate changes.

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

DirectionWho checksAgainst what
The broker’s server certificateYour device, when it opens TLS to the MQTT brokerPublic root certificates (a normal CA bundle) and the host name
A device’s client certificate (X.509 login)Hermetry, when a device presents a certificateHermetry’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:

CheckIf it fails
The certificate is inside its validity periodRefused 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 revokedRefused with CONNACK 5
It is the device’s active X.509 credential, and its CN is that device’s serialRefused with CONNACK 5
The list of revoked certificates is loadedWhile 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

CertificateValid forSigns
Root G120 yearsThe issuing CAs in use
Root G225 yearsNothing today. A spare root, created in the same ceremony as G1 and kept offline.
Device issuing CA5 years; it issues new certificates for at most 24 monthsDevice certificates
Device certificate365 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

ChangeWhenWhat devices noticeYour action
Broker server certificate renewedAutomatically, before it expiresThe new certificate at the next TLS handshake. Connected devices stay connected.None, if devices trust public roots and pin nothing below them
Device certificate renewedThe 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 rotatedAfter at most 24 months of issuingNothing. 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 lifeG1 is valid for 20 yearsNothing on the device side: Hermetry, not the device, checks client certificatesNone. Hermetry’s operators are alerted when a root has less than 3 years left.

How a device certificate gets renewed

  1. The device renews by itself. It sends a new certificate signing request (CSR) on v1/csr over its own TLS session, at the latest 30 days before its certificate expires. One renewal an hour is accepted per device.
  2. 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.renew once. An offline device is asked again the next day.
  3. 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.
  4. If nothing has happened 7 days after cert.renew, the organisation’s owners and administrators get the notice “Devices did not renew their certificates”.
  5. 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.