EST enrollment workflow
Before you begin
Make sure you understand the following:
A Device Trust Manager certificate management policy with the following:
EST certificate enrollment method enabled on the profile or policy.
Either a passcode or an authentication certificate assigned to the profile or policy.
Notice
If using a passcode, make sure you have the passcode and, if applicable, username available.
The EST API endpoint URL associated with the profile or policy being used. This can be found in the EST section on the enrollment profile or certificate management policy details page.
Certificate-based authentication:
If you are using a certificate-based authentication, your EST endpoint URL will resemble the example below:
Enroll: https://clientauth.demo.one.digicert.com/.well-known/est/devicetrustmanager/IOT_b0c9be31-6160-4fc5-9041-84b71a4c02fe/device-group/{device-group-id}/simpleenroll Reenroll: https://clientauth.demo.one.digicert.com/.well-known/est/devicetrustmanager/IOT_b0c9be31-6160-4fc5-9041-84b71a4c02fe/device-group/{device-group-id}/simplereenroll
If you are using a certificate-based authentication, your EST endpoint URL must have the
clientauth
prefix and will resemble the example below:Enroll: https://clientauth.demo.one.digicert.com/.well-known/est/devicetrustmanager/IOT_b0c9be31-6160-4fc5-9041-84b71a4c02fe/device-group/{device-group-id}/simpleenroll Reenroll: https://clientauth.demo.one.digicert.com/.well-known/est/devicetrustmanager/IOT_b0c9be31-6160-4fc5-9041-84b71a4c02fe/device-group/{device-group-id}/simplereenroll
Passcode-based authentication:
If you are using a passcode-based authentication, your EST endpoint URL will resemble the example below:
Enroll: https://demo.one.digicert.com/.well-known/est/devicetrustmanager/IOT_b0c9be31-6160-4fc5-9041-84b71a4c02fe/device-group/{device-group-id}/simpleenroll Reenroll: https://demo.one.digicert.com/.well-known/est/devicetrustmanager/IOT_b0c9be31-6160-4fc5-9041-84b71a4c02fe/device-group/{device-group-id}/simplereenroll
If you are using a passcode-based authentication, your EST endpoint URL will resemble the example below:
Enroll: https://demo.one.digicert.com/.well-known/est/devicetrustmanager/IOT_b0c9be31-6160-4fc5-9041-84b71a4c02fe/device-group/{device-group-id}/simpleenroll Reenroll: https://demo.one.digicert.com/.well-known/est/devicetrustmanager/IOT_b0c9be31-6160-4fc5-9041-84b71a4c02fe/device-group/{device-group-id}/simplereenroll
Note
Note that if you are using a Device Group with the Certificate Management Policy, then the Device Group ID is added to the end of the URL.
EST policy linked to a device group:
If you have linked the EST certificate management policy to a Device group, so you can use EST to register devices in the device group and issue bootstrap certificates to devices per the Advanced plan, update your EST endpoint to include
device-group/{device-group-id}
.
Step 1: Set up the device
Before starting the EST enrollment process, you need to set up your device with the necessary environment variables and files.
Set the
EST_PASS
variable. Replace<est_passcode>
with the actual passcode you obtained from the Device Trust Manager.export EST_PASS="<est_passcode>"
Optionally, set the
EST_USERNAME
variable. Replace<est_username>
with the username assigned to the passcode.export EST_USERNAME="<est_username>"
Run the following command to set the
EST_URI
variable:export EST_URI="<est_uri>"
Replace the
est_uri
with the EST endpoint URL you obtained from Device Trust Manager. See ???.Note
Note that if you are using a Device group with the Certificate Management Policy, then the Device group ID is added to the end of the URL, and you must replace it with your Device group ID.
The
export EST_URI
command with the Device group ID will resemble the example below:export EST_URI=https://clientauth.demo.one.digicert.com/.well-known/est/devicetrustmanager/IOT_4on9ypzu/device-group/
33318f48-1177-4233-ad1f-f69ea541d703
/simpleenrollRun the following command to create a certificate signing request (CSR) configuration file in the
/etc/digicert/keystore/conf
directory.For example,
sample_est_csr.conf
nano /etc/digicert/keystore/conf/sample_est_csr.conf
Insert the following CSR configuration content.
# Subject countryName=US commonName=test-iot-device-001-docs stateOrProvinceName=CA localityName=MV organizationName=DigiCert organizationalUnitName=Engineering # Requested Extensions isCA=false # certPathLen=-1 keyUsage=digitalSignature keyEncipherment ##subjectAltNames=numSANs; value1, type1; valueN, typeN ##subjectAltNames=2; *.mydomain.com, 2; *.mydomain.net, 2
Press Ctrl+O → Enter to save.
Press Ctrl+X to exit.
Run the following command to verify the conf file.
cat /etc/digicert/keystore/conf/sample_est_csr.conf
Download the TLS Root CA certificate
Before you can request a certificate using EST, you first need to download a copy of the Certificate Authority (CA) certificate for the EST endpoint. Without this certificate, the TrustEdge EST client will not trust this endpoint.
When connecting the TrustEdge client to the Device Trust Manager EST service, the appropriate CA certificate depends on the DigiCert ONE region and URL in use. Each DigiCert ONE instance is associated with a different root CA certificate.
The table below lists the appropriate Certificate Authority (CA) certificate URLs that you must download based on the DigiCert ONE region and the endpoint URL. This helps in ensuring that TrustEdge trusts the correct EST service for each geographical deployment.
Region | Endpoint URL | CA certificate to download |
---|---|---|
US | https://cacerts.digicert.com/DigiCertHighAssuranceEVRootCAcrthttps://cacerts.digicert.com/DigiCertHighAssuranceEVRootCAcrt | |
US | ||
NL | ||
JP | ||
CH |
For example, when connecting to the US region (one.digicert.com), download the following CA certificate:
wget https://cacerts.digicert.com/DigiCertGlobalRootCA.crt --directory-prefix=/etc/digicert/keystore/ca/
Where DigiCertGlobalRootCA.crt
is your certificate for Demo account of the US region.
Run the following command to verify that the file has been downloaded successfully:
ls /etc/digicert/keystore/ca/
(Optional) Download the EST CA certificates
Download the EST CA certificates to validate the issued certificates.
Perform the following steps:
Run the following command to verify your
EST_URI
points to the/cacerts
endpoint:echo $EST_URI
If your endpoint is not pointing to the
cacerts
URI, run the following command to export the URI.export EST_URI=https://clientauth.demo.one.digicert.com/.well-known/est/devicetrustmanager/IOT_63e17ec0-2ed9-4731-ab59-6debcc0ba7b9/device-group/{device-group-id}/cacerts
(Optional) If you want to validate the issued certificates, run the following command:
trustedge certificate est --uri ${EST_URI}
To verify, run the following command:
ls /etc/digicert/keystore/ca
Enroll a software key
Before running the enrollment command, verify that your
EST_URI
points to the/simpleenroll
endpoint.echo $EST_URI
Run the following command if your
EST URI
endpoint is not pointing to/simpleenroll
.export EST_URI=https://clientauth.demo.one.digicert.com/.well-known/est/devicetrustmanager/IOT_4on9ypzu/device-group/33318f48-1177-4233-ad1f-f69ea541d703/simpleenroll
Run the following command to enroll a software key using EST.
trustedge certificate est --algorithm ECC --curve P256 --uri ${EST_URI} --csr-conf sample_est_csr.conf --key-alias eccTestKey --log-level INFO
Run the following command to verify the output:
ls /etc/digicert/keystore/certs/
Renew a software key (optional)
Before running the enrollment command, check that your
EST_URI
points to the/simplereenroll
endpoint:echo $EST_URI
If your endpoint is not pointing to the
simplereenroll
URI, run the following command to export the URI.export EST_URI=https://clientauth.demo.one.digicert.com/.well-known/est/devicetrustmanager/IOT_4on9ypzu/device-group/33318f48-1177-4233-ad1f-f69ea541d703/simplereenroll
Run the following command to renew a previously enrolled software key using EST:
trustedge certificate est --algorithm ECC --curve P256 --uri ${EST_URI} --csr-conf sample_est_csr.conf --key-alias eccTestKey --log-level INFO
Troubleshoot common errors
The table below details some common errors and how to troubleshoot them:
Error | Fix |
---|---|
[TRUSTEDGE-CERTIFICATE] ERROR: Unable to connect to the server. Status: -7629 (ERR_CERT_CHAIN_NO_TRUST_ANCHOR) | Ensure you have downloaded the TLS root CA certificate. |
ERROR: Issued certificate is not validated with its CA Certs: Status: -7629 (ERR_CERT_CHAIN_NO_TRUST_ANCHOR) | Ensure you downloaded the EST CA certificate. |
[TRUSTEDGE-CERTIFICATE] ERROR: Unable to create CSR from CSR config file. Status: -7201 (ERR_FILE_OPEN_FAILED) [TRUSTEDGE-CERTIFICATE] ERROR: HTTP request/response failure. Status: -7201 (ERR_FILE_OPEN_FAILED) | Ensure you created the CSR |
Step 2: Download CA certificate
Before you can request a certificate using EST, you first need to download a copy of the Certificate Authority (CA) certificate for the EST endpoint. Without this certificate, the TrustEdge EST client will not trust this endpoint.
When connecting the TrustEdge client to the DigiCert® ONE Device Trust Manager EST service, the appropriate CA certificate depends on the DigiCert ONE region and URL in use. Each DigiCert ONE instance is associated with a different root CA certificate.
The table below lists the appropriate Certificate Authority (CA) certificate URLs that you must download based on the DigiCert ONE region and the endpoint URL. This helps in ensuring that TrustEdge trusts the correct EST service for each geographical deployment.
Region | Endpoint URL | CA certificate to download |
---|---|---|
US | https://cacerts.digicert.com/DigiCertHighAssuranceEVRootCA.crt | |
US | ||
NL | ||
JP | ||
CH |
For example, when connecting to the US region (one.digicert.com), download the following CA certificate:
wget https://cacerts.digicert.com/DigiCertHighAssuranceEVRootCA.crt --directory-prefix=/etc/digicert/keystore/ca/
Note
Ensure to download the appropriate CA certificate for your use case.
For a list of all DigiCert ONE regions and associated URLs, see Platform IP addresses and URLs.
To download CA certificates not listed in the above table, see Download DigiCert root and intermediate certificates.
Step 3: Enroll a software key
Run the following command to enroll a software key using EST.
trustedge certificate est --algorithm ECC --curve P256 --estc-server-dn ${EST_HOST} --estc-server-url ${EST_ENDPOINT}/simpleenroll --estc-user ${EST_USERNAME} --estc-pass ${EST_PASS} --csr-conf sample_est_csr.conf --key-alias eccTestKey --log-level INFO
Notice
What happens during an EST request? When the above command is run, TrustEdge:
Connects to the EST server without credentials. The server responds with a
401 Unauthorized
, including aWWW-Authenticate
header. This header specifies the required authentication method.Retries the request, this time providing the necessary credentials as specified in the returned
WWW-Authenticate
header. For example, passcode or authentication certificate.If the credentials are valid, the server processes the request successfully.
See RFC 7030 - Enrollment over Secure Transport HTTP-Based Client Authentication for more details.
Command breakdown:
--algorithm ECC
: Specifies the algorithm used for key generation. In this case,ECC
is selected. You can also specifyRSA
.--curve P256
: Defines the curve type of the ECC key to be generated. In this case,P256
. When using RSA as the algorithm, the--size
option is required to define the key size.--estc-server-dn ${EST_HOST}
: Specifies the host (distinguished name) of the EST server where the CSR will be sent for processing.--estc-server-url ${EST_ENDPOINT}/simpleenroll
: Specifies the EST endpoint URL that will handle the request. In this case, the/simpleenroll
endpoint.--estc-user ${EST_USERNAME}
: If needed, provides the username for the passcode to authenticate the EST operation.--estc-pass ${EST_PASS}
: Provides the challenge password for to authenticate the EST operation.--csr-conf sample_est_csr.cnf
: Points to the name of the CSR configuration file. This file must reside in the/etc/digicert/keystore/conf/
directory. The configuration file contains details about the CSR, including subject information and key usage.--key-alias eccTestKey
: Provides a custom name for the file name stub used for storing keys and certificates. Files will be placed in the/etc/digicert/keystore/keys
directory. If this option is excluded, the default stub nameGenKey
is used.--log-level INFO
: Defines the log level of the request. If excluded, the defaultERROR
is used.
(Optional) Renew a software key
Run the following command to renew a previously enrolled software key using EST.
trustedge certificate est --algorithm ECC --curve P256 --estc-server-dn ${EST_HOST} --estc-server-url ${EST_ENDPOINT}/simplereenroll --csr-conf sample_est_csr.conf --key-alias eccTestKey --log-level INFO