Skip to main content

EST enrollment workflow

Before you begin

Make sure you understand the following requirements before attempting EST enrollment operations.

  • A DigiCert​​®​​ IoT Trust Manager enrollment profile or DigiCert® 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.

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.

  1. Set the EST_PASS variable. Replace <est_passcode> with the actual passcode you obtained from IoT 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>"

  3. Set the EST_HOST variable. Replace <est_host> with the actual URL (distinguished name) you obtained from your IoT Trust Manager enrollment profile.

    export EST_HOST="<est_host>"

  4. Set the EST_ENDPOINT variable. Replace <est_endpoint_url> with only the base endpoint URL you obtained from your IoT Trust Manager enrollment profile. For example, /.well-known/est/IOT-enrollment-profile-ID. Make sure you exclude any specific endpoints in this variable, such as /simpleenroll or /simplereenroll.

    export EST_ENDPOINT="<est_endpoint_url>"

    Notice

    Why two variables? TrustEdge EST enrollment command-line tool divides server information into two components with the following command options:

    • --estc-server-dn This option specifies the server's distinguished name. For example, --estc-server-dn one.digicert.com.

    • --estc-server-url This option specifies the endpoint URL. For example, --estc-server-url /.well-known/est/<enrollment_profile_id>/simpleenroll.

  5. Create a sample_est_csr.cnf Certificate Signing Request (CSR) configuration file in the /etc/digicert/keystore/conf directory.

    touch /etc/digicert/keystore/conf/sample_est_csr.cnf

  6. Add the following sample CSR content to the sample_est_csr.cnf file.

    # Subject
countryName=US
commonName=test-iot-device-001-docs
stateOrProvinceName=CA
localityName=MV
organizationName=DigiCert
organizationalUnitName=Engineering
commonName=qa-testing-rsa
# Requested Extensions
isCA=false
# certPathLen=-1
keyUsage=digitalSignature keyEncipherment
##subjectAltNames=numSANs; value1, type1; valueN, typeN
##subjectAltNames=2; *.mydomain.com, 2; *.mydomain.net, 2

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.

  • Download the CA certificate.

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

    Important

    Make sure to download the appropriate CA certificate for your use case.

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

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.

  • --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 name GenKey is used.

  • --log-level INFO: Defines the log level of the request. If excluded, the default ERROR 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 est_sample_csr.conf --key-alias eccTestKey --log-level INFO
In this section: