Skip to main content

EST client

The Enrollment over Secure Transport (EST) client provides an alternative certificate enrollment protocol that enhances security and flexibility compared to SCEP. EST is defined in RFC 7030 and offers a more modern approach to certificate enrollment with stronger authentication mechanisms and support for advanced features.

EST client architecture

EST client is built on a modular architecture that interfaces with the core NanoCert libraries. The EST client implementation consists of several key components:

  1. EST Protocol Layer: Handles EST-specific message formatting and protocol operations

  2. HTTP Client Layer: Manages HTTPS communications with the EST server

  3. Certificate Processing: Works with the core NanoCert libraries for certificate operations

  4. Authentication Module: Handles various authentication methods supported by EST

The EST client operates synchronously, establishing a connection context and then performing certificate enrollment and management operations through that context. It uses standard TLS for securing communications and can work with various certificate stores for key and certificate management.

Key differences from SCEP

While both SCEP and EST provide certificate enrollment capabilities, EST offers several advantages:

  • Enhanced Security: EST requires TLS for all communications, providing stronger transport security

  • Flexible Authentication: Supports HTTP Basic Authentication, TLS client certificate authentication, and other methods

  • Standardization: EST is a fully standardized protocol (RFC 7030) with clearer specifications

  • Modern Features: Supports additional operations like server-side key generation and attribute requests

For many modern deployments, EST is the preferred enrollment protocol due to these enhanced capabilities, though SCEP remains widely supported for backward compatibility.

Communication flow

The EST client follows a structured communication flow:

  1. Connection Establishment: Opens a secure TLS connection to the EST server

  2. Authentication: Authenticates using configured credentials (HTTP Basic Auth or client certificate)

  3. Operation Request: Sends the specific EST request (e.g., certificate enrollment)

  4. Response Processing: Receives and processes the server’s response

  5. Certificate Handling: Extracts and stores any certificates received from the server

  6. Connection Termination: Closes the connection and releases resources

This communication pattern ensures secure and reliable certificate enrollment and management operations with minimal application complexity.

Supported operations

NanoCert EST client supports the core operations defined in the EST specification:

  • CA Certificate Retrieval (/cacerts): Obtains the current CA certificates

  • CSR Attributes (/csrattrs): Discovers required CSR attributes from the server

  • Certificate Enrollment (/simpleenroll): Enrolls a new certificate

  • Certificate Re-enrollment (/simplereenroll): Renews an existing certificate

  • Server-Side Key Generation (/serverkeygen): Requests key generation by the server

  • Full CMC (/fullcmc): Provides access to the full Certificate Management over CMS protocol

Sample code

To help you integrate NanoCert EST client into your devices, DigiCert​​®​​ provides sample code in the source distribution. You can find the sample code here:

  • src/examples/est_example_client.c

This sample code demonstrates NanoCert features and serves as a reference for your own implementation.

Tip

Use the sample code build script. See EST client sample code build instructions below.

Build instructions

./scripts/est/build_est_client_sw_tap_debug.sh

The above command generates all the required libraries, the est_client binary, and the configuration file tpconf.json inside ./bin directory.

Example tpconf.json

{
        "http_proxy": null,
        "root_dir": "/etc/digicert",
        "keystore_dir": "/etc/digicert/keystore",
        "conf_dir": "/etc/digicert/keystore/conf",
        "truststore_dir": "/etc/digicert/keystore/ca"
}

EST command line usage

Important

Make sure you you have completed NanoCert EST sample code build instructions before using the EST command-line interface.

NanoCert EST client includes a command-line interface that demonstrates the functionality and serves as a reference implementation. Understanding the command-line options provides insight into the capabilities and configuration parameters of the EST client.

Sample CSR attributes file

Certificate signing requests (CSRs) contain information about the entity requesting the certificate. NanoCert allows this information to be specified in a configuration file.

Here’s an example CSR attributes file (sample_est_csr.cnf):

#Subject
countryName=US
commonName=scepclient
stateOrProvinceName=California
localityName=San Francisco
organizationName=Mocana Corporation
organizationalUnitName=Engineering

#Attributes

#Requested Extensions
hasBasicContraints=true
isCA=false
certPathLen=-1
keyUsage=digitalSignature, keyEncipherment

This file defines the subject information and requested extensions for the certificate. You can customize these values according to your requirements.

Command line options

Use the following command to view available command-line options:

./bin/est_client --help

Usage example

Download EST CA certificates:

sudo ./bin/est_client -est_servername clientauth.demo.one.digicert.com -est_url /.well-known/est/IOT_c75d6gui/cacerts

Enroll a certificate with SW ECDSA key:

sudo ./bin/est_client -est_user estuser -est_pass estpass -est_servername clientauth.demo.one.digicert.com -est_keytype ECDSA -est_keysize 256 -est_url /.well-known/est/IOT_c75d6gui/simpleenroll -est_keyalias devecc101

Enroll a certificate with SW RSA key:

sudo ./bin/est_client -est_user estuser -est_pass estpass -est_servername clientauth.demo.one.digicert.com -est_keytype RSA -est_keysize 2048 -est_url /.well-known/est/IOT_c75d6gui/simpleenroll -est_keyalias devrsa101

Renew certificate with same SW ECDSA key:

sudo ./bin/est_client -est_servername clientauth.demo.one.digicert.com -est_keytype ECDSA -est_keysize 256 -est_url /.well-known/est/IOT_c75d6gui/simplereenroll -est_keyalias devecc101

Important

Using the TPM2 key via TAP will only work if you have taken ownership. See Take ownership of a TPM2 device.

Enroll a certificate with TAP ECDSA key:

sudo ./bin/est_client -est_user estuser -est_pass estpass -est_servername clientauth.demo.one.digicert.com -est_keytype ECDSA -est_keysize 256 -est_url /.well-known/est/IOT_c75d6gui/simpleenroll -est_keyalias devecctap101 -est_keysource TPM2

Enroll a certificate with TAP RSA key:

sudo ./bin/est_client -est_user estuser -est_pass estpass -est_servername clientauth.demo.one.digicert.com -est_keytype RSA -est_keysize 2048 -est_url /.well-known/est/IOT_c75d6gui/simpleenroll -est_keyalias devrsatap101 -est_keysource TPM2

Renew certificate with same TAP RSA key:

sudo ./bin/est_client -est_servername clientauth.demo.one.digicert.com -est_keytype RSA -est_keysize 2048 -est_url /.well-known/est/IOT_c75d6gui/simplereenroll -est_keyalias devrsatap101 -est_keysource TPM2

EST client API reference

NanoCert EST client provides a comprehensive set of API functions for implementing certificate enrollment and management using the EST protocol. These functions handle connection management, request generation, response processing, and certificate operations.

Connection management functions

These functions establish and terminate secure connections to EST servers:

  • EST_openConnection - Creates a synchronous client connection context for EST operations

    sbyte4 EST_openConnection(
    struct certStore *pCertStore,
    ubyte *pServerIpAddr,
    ubyte4 serverAddrLen,
    ubyte4 port,
    ubyte *pServerIdentity,
    ubyte4 serverIdentityLen,
    sbyte4 *pConnectionSSLInstance,
    httpContext **ppHttpContext,
    sbyte *pTLSCertAlias,
    ubyte4 tlsCertAliasLen,
    intBoolean ocspRequired);

  • EST_closeConnection - Closes the connection and releases associated resources

    sbyte4 EST_closeConnection(
    httpContext *pHttpContext,
    ubyte4 connectionSSLInstance);

These functions handle the establishment of secure TLS connections to EST servers and ensure proper resource management by releasing connections when operations are complete.

EST request functions

These functions generate and send various types of EST requests:

  • EST_sendCaCertsRequest - Sends a cacerts request to retrieve CA certificates

    sbyte4 EST_sendCaCertsRequest(
    httpContext *pHttpContext,
    ubyte4 connectionSSLInstance,
    ubyte *pRequestUrl,
    ubyte4 requestUrlLen,
    ubyte *pServerIdentity,
    ubyte4 serverIdentityLen,
    sbyte *pUserAgent);

  • EST_sendCsrAttrsRequest - Sends a csrattrs request to discover required attributes

    sbyte4 EST_sendCsrAttrsRequest(
    httpContext *pHttpContext,
    ubyte4 connectionSSLInstance,
    ubyte *pRequestUrl,
    ubyte4 requestUrlLen,
    ubyte *pServerIdentity,
    ubyte4 serverIdentityLen,
    sbyte *pUserAgent);

  • EST_sendSimpleEnrollRequest - Sends a simpleenroll request for certificate enrollment

    sbyte4 EST_sendSimpleEnrollRequest(
    httpContext *pHttpContext,
    ubyte4 connectionSSLInstance,
    ubyte *pRequestUrl,
    ubyte4 requestUrlLen,
    ubyte4 csrReqLen,
    ubyte *pServerIdentity,
    ubyte4 serverIdentityLen,
    sbyte *pUserAgent);

  • EST_sendSimpleReEnrollRequest - Sends a simplereenroll request for certificate renewal

    sbyte4 EST_sendSimpleReEnrollRequest(
    httpContext *pHttpContext,
    ubyte4 connectionSSLInstance,
    ubyte *pRequestUrl,
    ubyte4 requestUrlLen,
    ubyte4 csrReqLen,
    ubyte *pServerIdentity,
    ubyte4 serverIdentityLen,
    sbyte *pUserAgent);

These functions implement the core EST operations, enabling applications to perform various certificate management tasks through the EST protocol.

CSR and response handling functions

These functions handle Certificate Signing Request (CSR) generation and response processing:

  • EST_generateCSRRequestFromConfig - Generates a CSR from a configuration file

    sbyte4 EST_generateCSRRequestFromConfig(
    MOC_HW(hwAccelDescr hwAccelCtx)
    struct certStore *pCertStore,
    sbyte4 connectionSSLInstance,
    ubyte *pConfigFile,
    ubyte *pExtendedAttrsFile,
    ubyte4 config_type,
    ubyte *pKeyAlias,
    ubyte4 keyAliasLen,
    AsymmetricKey *pKey,
    ubyte4 keyType,
    ubyte *pHashType,
    ubyte4 hashTypeLen,
    ubyte **pPCsr,
    ubyte4 *pCsrLen);

  • EST_receiveResponse - Parses PKCS7 response and extracts certificates

    sbyte4 EST_receiveResponse(
    ubyte *pContentType,
    ubyte4 contentTypeLen,
    ubyte *pHttpResp,
    ubyte4 httpRespLen,
    struct SizedBuffer **pPCertificates,
    ubyte4 *pNumCerts);

  • EST_responseBodyCallbackHandle - Handles response data received from the server

    sbyte4 EST_responseBodyCallbackHandle(
    httpContext *pHttpContext,
    ubyte *pDataReceived,
    ubyte4 dataLength,
    sbyte4 isContinueFromBlock);

  • EST_requestBodyCallback - Copies request body data for transmission

    sbyte4 EST_requestBodyCallback(
    httpContext *pHttpContext,
    ubyte **pPDataToSend,
    ubyte4 *pDataLength,
    void *pRequestBodyCookie);

  • EST_validateReceivedCertificate - Validates that a received certificate was issued by the expected CA

    sbyte4 EST_validateReceivedCertificate(
    MOC_HW(hwAccelDescr hwAccelCtx) 
    struct certStore *pCertStore,
    ubyte *pReceivedCert,
    ubyte4 receivedCertLen,
    TimeDate *pTime);

Function usage pattern

The typical pattern for using the EST client API follows this sequence:

  1. Open a connection to the EST server with EST_openConnection

  2. Send an appropriate request using one of the EST request functions

  3. Process the response using EST_receiveResponse and related functions

  4. Validate received certificates with EST_validateReceivedCertificate

  5. Close the connection with EST_closeConnection

Important

Always check return values from all API functions to ensure proper error handling. Functions typically return zero on success and negative values on failure.

In this section: