Enroll devices with EST
EST (RFC 7030) lets devices request and renew certificates over HTTPS. Compared to SCEP it adds two things that matter for a fleet: devices can renew using the certificate they already hold, and each device can bootstrap with an identity of its own instead of a secret shared across the fleet.
For the background on device enrollment, see Device certificate enrollment.
Enable EST on a CA
Create or update a TLS CA with an est section. Unlike SCEP, EST does
not require an RSA-keyed CA, so the platform default (ECDSA) is fine:
supctl create strongbox tls ca <<EOF
name: devices
est:
enabled: true
initial-enroll-secret: <a strong shared secret>
allowed-domains:
- example.com
allow-subdomains: true
ttl: 30d
EOF
EST shares its identity policy (allowed-domains, allow-subdomains,
allow-bare-domains, allow-ip-sans, ttl) with SCEP, so a
certificate carries the same guarantees whichever protocol a device
used. See Enroll devices with SCEP for what each
setting does.
EST is served on the enrollment port, 4665, which it shares with ACME.
The CA publishes the URLs:
supctl show strongbox tls ca devices --fields est
est:
enabled: true
allowed-domains:
- example.com
ttl: 30d
https-url:
- https://192.168.1.10:4665/.well-known/est/<tenant-uuid>.devices
- https://control-tower.example.com:4665/.well-known/est/<tenant-uuid>.devices
The URLs are base URLs in the RFC 7030 single-label form: everything
after /est/ is one label, <tenant-uuid>.<ca-name>, and the client
appends the operation. A client configured with a server URL plus a CA
label uses the server's address as the URL and <tenant-uuid>.<ca-name>
as the label.
Address-based URLs come first, for devices without DNS. The URLs are local to whichever API answered: read the CA through the Control Tower API and the URLs carry Control Tower addresses; read it through a site's API and they carry that site's own addresses and DNS name. Devices at a site should enroll against their local site's endpoint, so that enrollment and renewal keep working when the site's uplink is down.
Three endpoints live under the same base path:
| Endpoint | Purpose |
|---|---|
/cacerts | Fetch the CA certificate chain. Unauthenticated. |
/simpleenroll | First enrollment. |
/simplereenroll | Renewal, authenticated by the certificate the device already holds. |
Choose how devices authenticate their first enrollment
A device has no certificate from this CA yet when it first enrolls, so something else has to vouch for it. EST supports two methods, and you can configure either or both.
A shared secret
initial-enroll-secret is presented with HTTP Basic authentication over
TLS: the secret is the Basic password, and the username is ignored --
put anything there. It is simple, and it is the direct equivalent of the
SCEP challenge password, with the same caveat: every device shares it,
so the identity policy is what limits what a holder can obtain.
curl --cert-type PEM \
-u device:<the shared secret> \
-H "Content-Type: application/pkcs10" \
-H "Content-Transfer-Encoding: base64" \
--data-binary @request.b64 \
https://<host>:4665/.well-known/est/<tenant-uuid>.devices/simpleenroll
A per-device birth certificate
initial-enroll-trust-ca names another CA whose certificates are
accepted as TLS client authentication for first enrollment. A device
presenting a client certificate issued by that CA -- typically a factory
installed birth certificate -- may enroll with no shared secret at all.
Each device then authenticates as itself:
supctl merge strongbox tls ca devices <<EOF
est:
initial-enroll-trust-ca: device-birth
EOF
The device enrolls by presenting its birth credential:
curl --cert birth.pem --key birth.key \
-H "Content-Type: application/pkcs10" \
-H "Content-Transfer-Encoding: base64" \
--data-binary @request.b64 \
https://<host>:4665/.well-known/est/<tenant-uuid>.devices/simpleenroll
Prefer this for a fleet. A shared secret compromised on one device compromises enrollment for all of them; a birth certificate does not.
The enrollment port accepts client certificates from any CA, because a birth
certificate is by definition not issued by this system. Acceptance at
the TLS layer is not a trust decision: the certificate is then verified
against initial-enroll-trust-ca, and enrollment is refused with 401
if it does not chain to it. Only the EST endpoints are served on this
port.
Require proof that the device is what it claims
The methods above answer may this request enroll. Attestation answers a different question: is the key going into hardware you trust. It is an additional requirement, not an alternative -- a shared secret alone never satisfies it -- and it applies to first enrollment only. Renewal is tied to a certificate whose issuance already met the requirement.
A manufacturer identity (IDevID)
Most industrial equipment ships with a manufacturer-installed identity (IEEE 802.1AR IDevID). Point the CA at the vendor's anchors and require it:
supctl merge strongbox tls ca devices <<EOF
est:
require-attestation: idevid
idevid-roots: |
-----BEGIN CERTIFICATE-----
...the vendor CA...
-----END CERTIFICATE-----
EOF
The device presents its IDevID as the TLS client certificate. The
certificate must chain to idevid-roots, so an enrollment cannot come
from anything but hardware that vendor built. idevid-roots must
contain the CA that issued the device identity: intermediate
certificates sent by the device are not used.
Attestation comes on top of the authentication above, and a device
presents only one client certificate, so idevid is normally combined
with initial-enroll-secret. To keep a device from enrolling under
another device's name, set initial-enroll-identity to serial-number,
which requires the CN of the request to be the serial number in the
subject of the IDevID, or to same-subject.
Be precise about what this proves: the request came from a device holding a manufacturer-installed identity. Whether the enrolled key sits in hardware is a property of that device, not something this check establishes. For that, use TPM attestation.
A TPM-resident key
With require-attestation: tpm, the device must prove that the key
being enrolled lives inside a TPM whose endorsement certificate chains
to anchors you list:
supctl merge strongbox tls ca devices <<EOF
est:
require-attestation: tpm
ek-roots: |
-----BEGIN CERTIFICATE-----
...the TPM vendor's EK CA...
-----END CERTIFICATE-----
EOF
The proof takes two requests, which replace simpleenroll. Both carry
the same certificate request and are authenticated like simpleenroll,
with the shared secret or a birth certificate. simpleenroll itself is
refused on a CA that requires TPM attestation.
tpm-challenge. The certificate request carries evidence as an attribute: the output ofTPM2_Certifyover the key being enrolled, signed by an attestation key, the public areas of both keys, and the endorsement certificate chain. The reply body is a credential, base64-encoded, in the file formattpm2_activatecredential -ireads, and thetpm-ticketreply header carries a ticket.tpm-enroll. The same certificate request, with the ticket in thetpm-ticketrequest header and the secret recovered withtpm2_activatecredential, base64-encoded, in thetpm-secretheader. The reply is that ofsimpleenroll.
Both are POST requests next to simpleenroll, at
https://<host>:4665/.well-known/est/<tenant-uuid>.devices/tpm-challenge
and .../tpm-enroll. A ticket is valid for five minutes, and only for the
certificate request it was issued for.
On tpm-challenge the Control Tower checks that the attestation key is
a restricted signing key that cannot leave its TPM, that its signature
over the attestation verifies, that the attested name matches the key
being certified, that the key is marked fixedTPM and
sensitiveDataOrigin -- which is what "cannot be exported" rests on --
that it is the same key as in the request, and that the endorsement
chain reaches your anchors. The credential it replies with can only be
opened by a TPM that holds both the endorsement key and the attestation
key, so a device that returns the secret has shown that the evidence
comes from the TPM the endorsement certificate was issued for.
Endorsement keys of the TCG default templates are supported: RSA 2048 and NIST P-256.
ek-roots is also where the virtual-TPM decision is made. A vTPM's
endorsement root belongs to the hypervisor vendor, so listing one
weakens the claim from the key cannot leave the hardware to the key
cannot leave the hypervisor. List only roots whose custody you accept.
Reading what was proven
How each certificate was enrolled is recorded with its expiry reminder,
when the CA has expiry-reminders with enrolled: true: est for an
unattested enrollment, est-idevid, est-tpm, or est-reenroll for a
renewal.
SCEP has no attestation support and none is planned: its clients are the installed base that cannot produce evidence. Use EST for attested enrollment.
Renewal
With allow-reenroll-with-issued-cert (on by default), a device renews
by calling simplereenroll with its current certificate as the TLS
client certificate:
curl --cert device.pem --key device.key \
-H "Content-Type: application/pkcs10" \
-H "Content-Transfer-Encoding: base64" \
--data-binary @request.b64 \
https://<host>:4665/.well-known/est/<tenant-uuid>.devices/simplereenroll
No shared secret is involved, which is what makes short certificate lifetimes practical: renewal needs no operator and no distributed secret. Have devices renew well before expiry, so a device that has been unreachable for a while still has a valid certificate to renew with.
When the CA requires attestation, this is the only way to renew: the
shared secret alone is not accepted for simplereenroll.
Enroll a post-quantum credential
EST accepts ML-DSA (NIST FIPS 204) certificate requests, so a device can hold a fully post-quantum credential. Create a CA with an ML-DSA key and enable EST on it:
supctl create strongbox tls ca <<EOF
name: devices-pq
cert-key-type: ml-dsa-65
est:
enabled: true
initial-enroll-secret: <a strong shared secret>
allowed-domains:
- example.com
allow-subdomains: true
ttl: 30d
EOF
A device with OpenSSL 3.5 or later enrolls exactly as before, using an ML-DSA key:
openssl genpkey -algorithm ML-DSA-65 -out device.key
openssl req -new -key device.key -subj "/CN=sensor-7.example.com" \
-outform DER | openssl base64 -A > request.b64
Both the device's key and the CA's signature on the issued certificate are then ML-DSA:
openssl x509 -in device.crt -noout -text | grep -i ML-DSA
SCEP cannot do this: its enrollment envelope depends on RSA key transport, so an ML-DSA-keyed CA cannot serve it. EST is the path forward for post-quantum device credentials.
Troubleshooting
401 Unauthorized. The credential was not accepted:
- With a shared secret, check it matches
initial-enroll-secret. - With a birth certificate, check that it chains to the CA named in
initial-enroll-trust-ca, and that the CA still exists. - On renewal, check the client certificate was issued by this CA, is still valid, and has not been revoked.
- If neither method is configured on the CA, enrollment is refused with
403instead: there is nothing a device could present.
403 Forbidden. The request was authenticated but something about
it is not permitted. Either the requested identity -- check the CN and
DNS SANs against allowed-domains, allow-subdomains and
allow-bare-domains, and whether the request carries an IP SAN while
allow-ip-sans is off -- or attestation, when it is required:
- No TLS client certificate presented, with
require-attestation: idevid: the device must authenticate with its manufacturer identity. A shared secret does not satisfy attestation. - Does not chain to the configured IDevID roots: the identity is from
another hierarchy, or
idevid-rootsis missing the vendor's issuing intermediate. - TPM attestation requires credential activation, with
require-attestation: tpm: the device calledsimpleenroll. It must enroll throughtpm-challengeandtpm-enroll. - The CSR carries no evidence attribute, with
require-attestation: tpm: the device did not include TPM evidence. - TPM attestation rejected: ...: the evidence was present but did not
verify. The reason names the check that failed, for instance
ek_chain_unverified(the endorsement chain does not reachek-roots),key_not_tpm_resident(the certified key is not markedfixedTPMandsensitiveDataOrigin),key_mismatch(the evidence certifies a different key than the request), orunsupported_ek(the endorsement key is not RSA 2048 or NIST P-256). - TPM credential activation failed: ..., on
tpm-enroll:wrong_secret(the device did not recover the secret, so the attestation key and the endorsement key are not in the same TPM),ticket_expired(more than five minutes sincetpm-challenge),csr_mismatch(not the certificate request the ticket was issued for), orbad_ticket. - TPM attestation is not required for this CA:
tpm-challengeortpm-enrollwas called on a CA withoutrequire-attestation: tpm. - Required but no roots are configured: the CA demands attestation
while
idevid-rootsorek-rootsis empty. Enrollment is refused rather than allowed through.
400 Bad Request. The body was not a well-formed PKCS#10 request,
or its self-signature did not verify. Confirm the request is DER,
base64-encoded, and signed by the key being certified.
404 Not Found. EST is not enabled on that CA, or the tenant or CA
name in the URL is wrong. Use the URLs published under the CA's est
section.