Device Cert Lifecycle

Every SCADABLE device authenticates to the broker with a per-device X.509 cert + private key. This page is what that cert looks like, where it lives on the chip, how long it's valid, and what happens when it expires.

Mint: at flash time, by SCADABLE

When you flash through the dashboard (Direct or Provisioning):

Browser generates a CSR locally; web flasher sends namespace ID + chip MAC + CSR to service-edge.
service-edge issues the cert against the namespace's intermediate CA. Subject CN=<namespace-id>:<mac>, 7-day validity, SAN includes the broker hostname.
Web flasher writes cert + key + CA chain into NVS namespace scadable_certs over WebSerial.

Round-trip under 5 seconds. The private key never leaves the browser → chip path.

Storage: NVS namespace `scadable_certs`

Three keys: cert (PEM device cert), key (PEM private key), ca (PEM SCADABLE CA chain). All blobs.

The library reads them on scadable_init(NULL). Missing or malformed → SCADABLE_ERR_NO_CERT. Fix is to re-flash; see Troubleshooting.

On chips with eFuse encryption keys (ESP32-S3 with flash encryption enabled), the NVS partition is encrypted at rest. Stock ESP32 without flash encryption → plaintext on flash. If physical-attacker is in your threat model, enable flash encryption in sdkconfig before flashing.

Validity: 7 days

7 days from mint. Short enough that a leaked key has bounded blast radius; long enough that a device offline for a weekend recovers cleanly.

Devices that stay online auto-rotate at hour 18 of each 24-hour window, mirroring gateway-linux's EST simplereenroll flow. On ESP32 the auto-rotate path is a stub today — the library logs the attempt; the actual rotate happens via re-flash.

Renewal: re-flash today, on-device EST in Phase 2

Until on-device EST lands on ESP32:

Online devices. Nothing to do in the first 7 days. After that, the cert has expired and the chip can't reconnect on its next disconnect. Hit Re-flash in the dashboard to mint a fresh cert and push it over WebSerial.
Offline devices. Unplugged for 7+ days → cert expired → can't reach the broker on power-on. Same fix. Chip isn't bricked: provisioner in factory still boots; it just can't mTLS in.

Phase 2 brings on-device EST simplereenroll to ESP32 (already working on gateway-linux). The library will rotate in place, using the current cert as the auth.

Revocation

If a device is lost or compromised:

Dashboard → device → Revoke.
service-edge adds the cert serial to the per-namespace CRL.
Broker checks the CRL on every TLS handshake; existing sessions are cut on a configurable cadence (default 60s).

Revocation is permanent. Re-flash to bring the device back.

What an expired cert looks like

E (5012) scadable: TLS handshake failed: cert expired (notAfter 2026-04-29)
I (5113) scadable: state: ERROR -> CONNECTING (retriable)

Then CONNECTING indefinitely. The library doesn't ship a "cert expired" event — from the device's side it's indistinguishable from a network error. Operator-side fix: re-flash.

Why 7 days

Trade-off between blast radius and operational pain. 24h means re-flashing fleets every long weekend; 30d gives a leaked key a month. 7d lines up with weekly maintenance windows. When on-device EST lands, validity will likely shrink (24h) because renewal becomes a non-event.