EST enrollment

Before you begin

Make sure you understand the following:

<pre><code>If using a passcode, make sure you have the passcode and, if applicable, username available.

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

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

<ul>

Set up the device

Before starting the EST enrollment process, you need to set up your device with the necessary environment variables and files.

1. Set the EST_PASS variable. Replace <est_passcode> with the actual passcode you obtained from the Device Trust Manager.

   export EST_PASS="<est_passcode>"
   

2. Optionally, set the EST_USERNAME variable. Replace <est_username> with the username assigned to the passcode.

   export EST_USERNAME="<est_username>"
   

   Note

   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.
3. Run 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
   

4. 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
   

5. Press Ctrl+O → Enter to save.
6. Press Ctrl+X to exit.
7. Run the following command to verify the conf file.

   cat /etc/digicert/keystore/conf/sample_est_csr.conf
   

Download the TLS Root CA

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.

1. Run the following command to download the TLS Root CA certificate:

   wget https://cacerts.digicert.com/DigiCertGlobalRootCA.crt --directory-prefix=/etc/digicert/keystore/ca/
   

   Where DigiCertGlobalRootCA.crt is your certificate for the demo.one.digicert.com Demo account of the US region.

   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.
2. Run the following command to verify that the file has been downloaded successfully:

   ls /etc/digicert/keystore/ca/
   

(Optional) Download the EST CA

Download the EST CA certificates to validate the issued certificates.

Perform the following steps:

1. Run the following command to set the EST_URI  to cacerts endpoint.

   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
   

2. Run the following command to verify your EST_URI points to the /cacerts endpoint:

   echo $EST_URI
   

3. Run the following command:

   trustedge certificate est --uri $EST_URI
   

4. To verify, run the following command:

   ls /etc/digicert/keystore/ca
   

Enroll a software key

Perform the following steps to enroll a software key:

1. Run the following command to set the EST_URI to simpleenroll endpoint

   export EST_URI=https://clientauth.demo.one.digicert.com/.well-known/est/devicetrustmanager/IOT_4on9ypzu/device-group/33318f48-1177-4233-ad1f-f69ea541d703/simpleenroll
   

2. Run the following command to verify that your EST_URI points to the /simpleenroll endpoint.

   echo $EST_URI
   

3. 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
   

   Command breakdown
   • --algorithm ECC: Specifies the algorithm used for key generation. In this case, ECC is selected. You can also specify RSA.
   • --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.
   • --uri: Specifies the EST API endpoint URL.
   • --csr-conf sample_est_csr.conf: 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 name GenKey is used.
   • --log-level INFO: Defines the log level of the request. If excluded, the default ERROR is used.
4. Run the following command to verify the output:

   ls /etc/digicert/keystore/certs/
   

   • Ensure <key_alias>.pem and <key_alias>.der are present. It should be eccTestKey.pem and eccTestKey.der.
   • If --key-alias option is excluded, GenKey.pem and GenKey.der default names are used.

     Note

     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 a WWW-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.

(Optional) Renew a software key

Perform the following steps:

1. Run the following command to set the EST_URI to simplereenroll endpoint.

   export EST_URI=https://clientauth.demo.one.digicert.com/.well-known/est/devicetrustmanager/IOT_4on9ypzu/device-group/33318f48-1177-4233-ad1f-f69ea541d703/simplereenroll
   

2. Run the following command to verify that your EST_URI is pointing to the /simplereenroll endpoint:

   echo $EST_URI
   

3. 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: