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

Registration

In emCA, ACME clients 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.

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

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

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

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

Click on “Sign and Save‟.

Click on the “copy icon‟ button to save the client ID.

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.

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;

-- External application details
UPDATE api_properties 
SET prop_value = 'xxxx', prop_status = 1 
WHERE prop_key = 'emca.acme.extenal.application.username';

UPDATE api_properties 
SET prop_value = 'xxxx', prop_status = 1 
WHERE prop_key = 'emca.acme.extenal.application.password';

UPDATE api_properties 
SET prop_value = 'xxxx', prop_status = 1 
WHERE prop_key = 'emca.acme.extenal.application.client-id';

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

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