--- title: "EST client" source_url: https://dev.digicert.com/trustcore-sdk/nanocert/est-client.html --- 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](#N1743716546589)* below. ### Build instructions ```bash ./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** ```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 *[EST sample code build instructions](#N1743716546589)* 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: ```bash ./bin/est_client --help ``` #### Usage example Download EST CA certificates: ```bash 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: ```bash 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: ```bash 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: ```bash 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](https://dev.digicert.com/md/trustedge/tutorials/take-ownership-of-a-tpm.md). Enroll a certificate with TAP ECDSA key: ```bash 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: ```bash 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: ```bash 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c sbyte4 EST_responseBodyCallbackHandle( httpContext *pHttpContext, ubyte *pDataReceived, ubyte4 dataLength, sbyte4 isContinueFromBlock); ``` - `EST_requestBodyCallback` - Copies request body data for transmission ```c sbyte4 EST_requestBodyCallback( httpContext *pHttpContext, ubyte **pPDataToSend, ubyte4 *pDataLength, void *pRequestBodyCookie); ``` - `EST_validateReceivedCertificate` - Validates that a received certificate was issued by the expected CA ```c 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.