ACME and EST Protocols

ACME Protocol

The emCA provides certificate management using the Automated Certificate Management Environment (ACME) protocol, compliant with RFC 8555 (https://datatracker.ietf.org/doc/html/rfc8555). ACME allows a client to request certificate management actions using a set of JavaScript Object Notation (JSON) messages carried over HTTPS. Issuance using ACME resembles a traditional CA's issuance process, in which a user creates an account, requests a certificate, and proves control of the domain(s) in that certificate in order for the CA to issue the requested certificate.

The first phase of ACME is for the client to request an account with the ACME server. The client generates an asymmetric key pair and requests a new account, optionally providing contact information, agreeing to terms of service (ToS), and/or associating the account with an existing account in another system. The creation request is signed with the generated private key to prove that the client controls it.

Prerequisites

Create Certificate Template

Create the appropriate certificate template in emCA by following the steps outlined in Section– Manage Profiles of the emCA User Manual. Be sure to record important details such as the Profile Name or Certificate Profile ID, as these will be required during the certificate enrollment process.

Configure Properties

Configuration must be defined in the database. The required values must be updated in the `api_properties` table to enable ACME server functionality.

acme.ca.server.user.profile	Cert profile name /ID	Status
emca.acme.base.url	emCA API Base URL	Active

Please find the following script to update the necessary values in the database:

-- Certificate template profile ID
UPDATE api_properties
SET prop_value = 'xxxx', prop_status = 1
WHERE prop_key = 'acme.ca.server.user.profile';
-- emCA Services Base URL
UPDATE api_properties
SET prop_value = 'https://www.example.com/emCAServices/acme', prop_status = 1
WHERE prop_key = ‘emca.acme.base.url;

Note: To apply the configuration changes, it is necessary to restart the Tomcat services. Please follow the steps below to restart Tomcat

ACME Endpoint

Base URL: https://www.example.com/emCAServices/acme

Supported Endpoints

Endpoint	Type of Method	Description
/directory	GET	Returns a list of available ACME endpoints and metadata.
/new-nonce	HEAD	Used to get a fresh anti-replay nonce.
/new-account	POST	Creates a new ACME account.
/account/{accountId}	POST	Retrieves or updates an existing ACME account.
/new-order	POST	Creates a new order for a certificate.
/order/{orderId}	POST	Retrieves details of a specific order.
/order/{orderId}/finalize	POST	Submits the CSR to finalize the certificate order.
/new-authz	POST	Creates a new authorization object.
/authz/{authorizationId}	POST	Retrieves the status of a specific authorization.
/chall/{challengeId}	POST	Responds to a challenge for domain validation.
/revoke-cert	POST	Submits a certificate for revocation.
/key-change	POST	Requests a change of the account key pair.
/cert/{certId}	POST	Downloads the issued certificate.

Authentication

• ACME uses JSON Web Signature (JWS)-signed requests to authenticate clients.

• Clients are required to generate an account key pair and use the private key to sign all requests sent to the server.

• The emCA ACME server verifies the JWS signature of each request to ensure the authenticity and integrity of the client’s identity and actions.

HTTP Response Status Codes

HTTP Status Code	Meaning	Description
200	OK	The request was successful, and the response contains the requested data
201	Created	A new resource (e.g., account or order) was successfully created.
202	Accepted	The request has been accepted for processing, but the operation is not complete (e.g., pending validation).
204	No Content	The request was successful, but there is no content to return (e.g., successful revocation).
400	Bad Request	The request was malformed or invalid.
401	Unauthorized	The client failed to authenticate (e.g., missing or invalid JWS signature).
500	Internal Server Error	An unexpected server error occurred.

EST Protocol

Enrollment over Secure Transport (EST) is a certificate enrollment protocol that operates over HTTPS, offering strong client authentication and enhanced security features. This implementation of EST (Enrollment over Secure Transport), as defined in RFC 7030 (https://www.rfc-editor.org/rfc/rfc7030.html), supports basic certificate enrollment and retrieval of CA certificates. Communication is secured using HTTPS (HTTP over TLS) over TCP, and client authentication is performed using HTTP Basic Authentication.

Prerequisites

Registration

In emCA, EST (Enrollment over Secure Transport) requests are authenticated using Basic Authentication. Therefore, before utilizing the EST protocol, the client must first register through the emCA Portal.

Steps to be followed by the emCA Team:

1. Once the emCA team receives the client's username, password, and IP address,

2. The emCA Administrator should log in to the emCA portal using an Admin account,

3. And proceed to register the client details to authorize EST access.

emCA Administrator should login to the emCA portal as Admin/CA Admin and navigate to “Application Settings‟ -> “External Applications‟ as shown in the figure.

Figure 1

Click on “New‟ The following screen will be displayed.

Figure 2

Figure 3

Once the details are entered, click on “Proceed‟.

The “Verify and Confirm‟ page will be displayed where the Admin/CA Admin should verify and entered details and authenticate by entering the Username and Password

Figure 4

Click on “Sign and Save‟.

Figure 5

Figure 6

Create Certificate Template

Create the appropriate certificate template in emCA by following the steps outlined in Section – Manage Profiles of the emCA User Manual. Be sure to record important details such as the Profile Name or Certificate Profile ID, as these will be required during the certificate enrollment process.

Configure Properties

EST configuration must be defined in the database. The required values must be updated in the `api_properties` table to enable EST CA server functionality.

est.ca.server.user.profile	EST Cert Profile name/ID	Active
est.ca.server.group.id	Group Id	Active
est.ca.server.group.id	Group Id	Active

Please find the following script to update the necessary values in the database:

-- Certificate template profile ID
UPDATE api_properties
SET prop_value = 'xxxx', prop_status = 1
WHERE prop_key = 'est.ca.server.user.profile';
-- EST CA server group information
UPDATE api_properties
SET prop_value = '1', prop_status = 1
WHERE prop_key = ‘est.ca.server.group.id';

Note: To apply the configuration changes, it is necessary to restart the Tomcat services. Please follow the steps below to restart Tomcat:

EST Endpoint

Base URL: https://www.example.com/emCAServices/est

Supported Endpoints

Endpoint	Type of Method	Description
/cacerts	GET	Retrieves the CA certificates (trust anchors).
/simpleenroll	POST	Accepts CSR and returns a signed certificate (enrollment).

API Specifications

Get/est/cacerts

Purpose: Returns a response with the CA certificates (trust anchors)

Sample Request

GET /est/cacerts HTTP/1.1 Host: emca.example.com Authorization: Basic <Base64(username:password)> Accept: application/pkcs7-mime

Sample Response

Status: 200 OK Content-Type: application/pkcs7-mime Body: PKCS#7 SignedData containing the CA certificate chain.

POST/est/simpleenroll

Purpose: Submits a certificate signing request (CSR) and returns a signed certificate.

Sample Request

POST /emCAServices/est/simpleenroll HTTP/1.1

Host: emca.example.com

Authorization: Basic <Base64(username:password)>

Content-Type: application/pkcs10

Content-Transfer-Encoding: <Base64-encoded PKCS#10 CSR>

Sample Response

Status: 200 OK if successful,

Content-Type: application/pkcs7-mime

Body: PKCS#7 SignedData with the signed certificate

Authentication

• EST (Enrollment over Secure Transport) uses HTTP Basic Authentication to verify client identity before processing requests.

• Clients must provide valid username and password credentials in the Authorization header of each request.

• Only authenticated clients are permitted to access endpoints.

HTTP Response Status Codes

200	OK	Returned when a request (e.g., CSR Attributes, CA Certs, and enrollment) completes successfully.
400	Bad Request	Returned when a CSR is malformed, missing required fields, or improperly encoded.
401	Unauthorized	Returned when the client fails to provide correct authentication (HTTP auth, TLS cert).
500	Internal Server Error	Unexpected error on the EST server