Skip to main content

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:

EndpointPurpose
/cacertsFetch the CA certificate chain. Unauthenticated.
/simpleenrollFirst enrollment.
/simplereenrollRenewal, 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.

note

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.

  1. tpm-challenge. The certificate request carries evidence as an attribute: the output of TPM2_Certify over 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 format tpm2_activatecredential -i reads, and the tpm-ticket reply header carries a ticket.
  2. tpm-enroll. The same certificate request, with the ticket in the tpm-ticket request header and the secret recovered with tpm2_activatecredential, base64-encoded, in the tpm-secret header. The reply is that of simpleenroll.

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.

note

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.

note

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 403 instead: 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-roots is missing the vendor's issuing intermediate.
  • TPM attestation requires credential activation, with require-attestation: tpm: the device called simpleenroll. It must enroll through tpm-challenge and tpm-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 reach ek-roots), key_not_tpm_resident (the certified key is not marked fixedTPM and sensitiveDataOrigin), key_mismatch (the evidence certifies a different key than the request), or unsupported_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 since tpm-challenge), csr_mismatch (not the certificate request the ticket was issued for), or bad_ticket.
  • TPM attestation is not required for this CA: tpm-challenge or tpm-enroll was called on a CA without require-attestation: tpm.
  • Required but no roots are configured: the CA demands attestation while idevid-roots or ek-roots is 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.