EST Enrollment Setup

EST (Enrollment over Secure Transport) provides a standardized protocol for automated certificate enrollment, allowing devices to securely obtain and renew certificates.

Overview

Lamassu implements EST (RFC 7030) through the DMS Manager service. EST endpoints enable devices to:

Retrieve CA certificates
Enroll for new certificates
Re-enroll to renew existing certificates
Request server-generated keys (optional)

EST URL Structure

All EST endpoints include the DMS ID as part of the path:

https://<HOST>/.well-known/est/<DMS_ID>/<operation>

For example:

https://est.example.com/.well-known/est/manufacturing-dms/simpleenroll

Prerequisites

Install required tools

Ensure OpenSSL and curl are installed:

# Verify OpenSSL
openssl version

# Verify curl
curl --version

Identify your DMS ID

Get your DMS identifier from the DMS Manager:

curl https://lamassu.example.com/api/dmsmanager/v1/dms \
  -H "Authorization: Bearer $TOKEN"

Prepare authentication credentials

Depending on DMS configuration, you’ll need:

mTLS: Client certificate and key (most common)
NoAuth: No credentials required (for initial enrollment scenarios)
Webhook: External authorization handled by the DMS

Retrieve CA Certificates

Fetch the trust anchor (CA certificate) before enrolling.

Request CA certificates

curl -s -k "https://est.example.com/.well-known/est/manufacturing-dms/cacerts" \
  -o cacerts.b64

The response is a Base64-encoded PKCS#7 file containing the CA certificate chain.

Convert to PEM format

# Decode Base64 to DER
base64 -d cacerts.b64 > cacerts.p7b

# Extract certificates from PKCS#7
openssl pkcs7 -inform DER -in cacerts.p7b -print_certs -out cacerts.pem

Inspect the CA certificate

openssl x509 -in cacerts.pem -text -noout

Enroll a Device

Devices submit a Certificate Signing Request (CSR) to obtain a certificate.

Generate Key and CSR

Generate device key

openssl genpkey -algorithm RSA -out device.key -pkeyopt rsa_keygen_bits:2048

Create CSR

openssl req -new -key device.key -out device.csr \
  -subj "/CN=device-001/O=Acme Corp"

Convert CSR to Base64 DER

Lamassu expects the CSR body as Base64-encoded DER (without PEM headers):

openssl req -in device.csr -outform DER | base64 -w 0 > device.b64

Submit Enrollment Request

mTLS Authentication
No Authentication

Use a bootstrap certificate for authentication:

curl -v -s -k \
  --cert bootstrap.crt --key bootstrap.key \
  -H "Content-Type: application/pkcs10" \
  --data-binary "@device.b64" \
  "https://est.example.com/.well-known/est/manufacturing-dms/simpleenroll" \
  -o enroll_resp.b64

The bootstrap certificate must be issued by a CA trusted by the DMS (configured in the DMS ValidationCAs).

If the DMS allows NoAuth enrollment:

curl -v -s -k \
  -H "Content-Type: application/pkcs10" \
  --data-binary "@device.b64" \
  "https://est.example.com/.well-known/est/manufacturing-dms/simpleenroll" \
  -o enroll_resp.b64

NoAuth enrollment should only be enabled in controlled manufacturing environments or for initial device provisioning.

Extract the Issued Certificate

Decode response

The response is a Base64-encoded PKCS#7 containing the issued certificate:

base64 -d enroll_resp.b64 > enroll_resp.p7b

Extract certificate

openssl pkcs7 -inform DER -in enroll_resp.p7b -print_certs -out device_cert.pem

Verify certificate

openssl verify -CAfile cacerts.pem device_cert.pem

Output should be:

device_cert.pem: OK

Re-enroll to Renew Certificate

Devices use their existing certificate to authenticate and obtain a renewed certificate.

Generate new CSR

openssl req -new -key device.key -out device_re.csr \
  -subj "/CN=device-001/O=Acme Corp"
openssl req -in device_re.csr -outform DER | base64 -w 0 > device_re.b64

Submit re-enrollment request

Use the current certificate to authenticate:

curl -v -s -k \
  --cert device_cert.pem --key device.key \
  -H "Content-Type: application/pkcs10" \
  --data-binary "@device_re.b64" \
  "https://est.example.com/.well-known/est/manufacturing-dms/simplereenroll" \
  -o reenroll_resp.b64

Extract renewed certificate

base64 -d reenroll_resp.b64 | openssl pkcs7 -inform DER -print_certs -out device_re_cert.pem

Re-enrollment is recommended before the current certificate expires. Configure the renewal window in the issuance profile.

Server-Side Key Generation

Request the server to generate the private key on behalf of the device.

Server-side key generation should only be used in constrained devices unable to generate keys locally. The private key is transmitted to the device over TLS.

curl -v -s -k \
  --cert device_cert.pem --key device.key \
  -H "Content-Type: application/pkcs10" \
  --data-binary "@device.b64" \
  "https://est.example.com/.well-known/est/manufacturing-dms/serverkeygen" \
  -o response.mime

The response is a multipart/mixed message with boundary --estServerLamassuBoundary containing:

Private Key (application/pkcs8) - Base64 encoded
Certificate (application/pkcs7-mime) - Base64 encoded

You’ll need to manually parse the MIME parts to extract the key and certificate.

Get CSR Attributes

Retrieve recommended CSR attributes from the DMS:

curl -s -k "https://est.example.com/.well-known/est/manufacturing-dms/csrattrs" \
  -o csrattrs.b64

This returns a Base64-encoded structure describing required or recommended CSR attributes.

Complete Enrollment Script

Here’s a complete one-shot script for EST enrollment with mTLS:

#!/usr/bin/env bash
set -euo pipefail

EST_HOST="https://est.example.com"
DMS_ID="manufacturing-dms"
AUTH_CERT="bootstrap.crt"
AUTH_KEY="bootstrap.key"

# Output files
KEY="device.key"
CSR_DER="device.csr.der"
CSR_B64="device.csr.b64"
CA_B64="cacerts.b64"
CA_PEM="cacerts.pem"
RESP_B64="resp.b64"
DEV_PEM="device_final.pem"

echo "1. Generating Key..."
openssl genpkey -algorithm RSA -out $KEY -pkeyopt rsa_keygen_bits:2048
openssl req -new -key $KEY -outform DER -out $CSR_DER -subj "/CN=device-XX/O=Lamassu"
base64 -w 0 $CSR_DER > $CSR_B64

echo "2. Fetching CA Certificates..."
curl -s -k "$EST_HOST/.well-known/est/$DMS_ID/cacerts" -o $CA_B64
base64 -d $CA_B64 | openssl pkcs7 -inform DER -print_certs -out $CA_PEM

echo "3. Enrolling..."
curl -s -k \
  --cert $AUTH_CERT --key $AUTH_KEY \
  -H "Content-Type: application/pkcs10" \
  --data-binary "@$CSR_B64" \
  "$EST_HOST/.well-known/est/$DMS_ID/simpleenroll" \
  -o $RESP_B64

echo "4. Processing Response..."
if [ -s "$RESP_B64" ]; then
    base64 -d $RESP_B64 | openssl pkcs7 -inform DER -print_certs -out $DEV_PEM
    openssl verify -CAfile $CA_PEM $DEV_PEM && echo "SUCCESS: Certificate Enrolled & Verified"
else
    echo "ERROR: Empty response"
    exit 1
fi

Troubleshooting

400 Bad Request

Cause: Malformed request bodySolution: Ensure you’re sending Base64-encoded DER, not PEM format:

# Correct
openssl req -in device.csr -outform DER | base64 -w 0 > device.b64

# Incorrect - DO NOT use PEM
cat device.csr > device.b64

401 Unauthorized / 403 Forbidden

Cause: Authentication failureSolutions:

Verify the client certificate is valid and trusted by the DMS
Check the DMS ValidationCAs configuration
Ensure the certificate hasn’t expired
Verify the DMS authentication mode (mTLS, NoAuth, Webhook)

404 Not Found

Cause: Incorrect DMS ID or endpointSolution: Verify the DMS ID and EST URL structure:

# Check DMS exists
curl https://lamassu.example.com/api/dmsmanager/v1/dms/manufacturing-dms \
  -H "Authorization: Bearer $TOKEN"

Empty Response

Cause: Server rejected the request but returned 200 OKSolution: Check server logs for details. Common causes:

CSR validation failed
Profile restrictions not met
DMS misconfiguration

Best Practices

Use mTLS

Always use mTLS authentication in production. NoAuth should only be used in isolated manufacturing environments.

Automate Renewal

Configure devices to automatically re-enroll before certificates expire using the simplereenroll endpoint.

Validate Responses

Always verify the issued certificate against the CA trust anchor before storing it.

Secure Bootstrap Certs

Protect bootstrap certificates with hardware security modules or secure element storage.

Getting Started

Deployment

Core Concepts

User Guides

Engines & Connectors

Security

Operations

Overview

EST URL Structure

Prerequisites

Retrieve CA Certificates

Enroll a Device

Generate Key and CSR

Submit Enrollment Request

Extract the Issued Certificate

Re-enroll to Renew Certificate

Server-Side Key Generation

Get CSR Attributes

Complete Enrollment Script

Troubleshooting

Best Practices

Use mTLS

Automate Renewal

Validate Responses

Secure Bootstrap Certs

Next Steps

Device Lifecycle

Issuance Profiles

Build docs developers (and LLMs) love

Getting Started

Deployment

Core Concepts

User Guides

Engines & Connectors

Security

Operations

​Overview

​EST URL Structure

​Prerequisites

​Retrieve CA Certificates

​Enroll a Device

​Generate Key and CSR

​Submit Enrollment Request

​Extract the Issued Certificate

​Re-enroll to Renew Certificate

​Server-Side Key Generation

​Get CSR Attributes

​Complete Enrollment Script

​Troubleshooting

​Best Practices

Use mTLS

Automate Renewal

Validate Responses

Secure Bootstrap Certs

​Next Steps

Device Lifecycle

Issuance Profiles

Build docs developers (and LLMs) love

Overview

EST URL Structure

Prerequisites

Retrieve CA Certificates

Enroll a Device

Generate Key and CSR

Submit Enrollment Request

Extract the Issued Certificate

Re-enroll to Renew Certificate

Server-Side Key Generation

Get CSR Attributes

Complete Enrollment Script

Troubleshooting

Best Practices

Next Steps