# ACME Protocol

emCA implements ACME per RFC 8555 (<https://datatracker.ietf.org/doc/html/rfc8555>). Requests are JWS-signed JSON over HTTPS. Directory, nonce, and error semantics follow the spec. Policy and audit controls apply to all ACME operations.

The client generates an asymmetric key pair. It retrieves the directory and a nonce. It submits a new Account request signed with the private key. Optional fields include contact URIs and ToS agreement. External Account Binding (EAB) is supported if required by policy. On success, the server issues an account with a stable kid (account URL).

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

![Figure 1](https://2804668976-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOwstGDJbR4yGRTr2aEFp%2Fuploads%2FLW0fPYm8kRovKO4NBrXf%2F0.png?alt=media)

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

<figure><img src="https://2804668976-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOwstGDJbR4yGRTr2aEFp%2Fuploads%2FDJzAs4NutxkSxdY3OkLL%2Fimage.png?alt=media&#x26;token=79cf39d2-9504-4e74-af39-2230e40d6e8f" alt=""><figcaption><p>Figure 2</p></figcaption></figure>

<figure><img src="https://2804668976-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOwstGDJbR4yGRTr2aEFp%2Fuploads%2Fw3fcRn4rr8iErnjzUsLJ%2Fimage.png?alt=media&#x26;token=76147129-1ba0-43a1-b937-2a2b99105e59" alt=""><figcaption><p>Figure 3</p></figcaption></figure>

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

<figure><img src="https://2804668976-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOwstGDJbR4yGRTr2aEFp%2Fuploads%2FJySdCeixvlUeFMZqQbbl%2Fimage.png?alt=media&#x26;token=4441de31-4bf8-4f8d-9f9a-bceeeca3516a" alt=""><figcaption><p>Figure 3</p></figcaption></figure>

Click on “Sign and Save‟.

<figure><img src="https://2804668976-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOwstGDJbR4yGRTr2aEFp%2Fuploads%2FllfYYxPBCTbZOlGiIrnE%2Fimage.png?alt=media&#x26;token=f2f14b87-0ce4-4f8e-a5ad-e49d75a7766e" alt=""><figcaption><p>Figue 4</p></figcaption></figure>

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 –** [Configuring Certificate Profile](https://emca.emudhra.com/getting-started/configuring-certificate-profiles) -> *User Profile Creation*. 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 | Active |
| --------------------------------------- | --------------------- | ------ |
| emca.acme.base.url                      | emCA API Base URL     | Active |
| emca.acme.extenal.application.username  | ACME Client           | Active |
| emca.acme.extenal.application.password  | Password              | Active |
| emca.acme.extenal.application.client-id | Client 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 = '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';
```

{% hint style="info" %}
**Note**: To apply the configuration changes, it is necessary to restart the Tomcat services. Please follow the steps below to restart Tomcat
{% endhint %}

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