# 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](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 2](https://2804668976-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOwstGDJbR4yGRTr2aEFp%2Fuploads%2Fan10f8A6fsl5GkJYU6Kk%2F1.png?alt=media)

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

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](https://2804668976-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOwstGDJbR4yGRTr2aEFp%2Fuploads%2Fo9RNegTSJvVFb82hq5Au%2F4.png?alt=media)

Click on “Sign and Save‟.

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

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

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

<table data-header-hidden><thead><tr><th>HTTP Status Code Me</th><th valign="top">Meaning </th><th>Description</th></tr></thead><tbody><tr><td>200</td><td valign="top">OK</td><td>Returned when a request (e.g., CSR Attributes, CA Certs, and enrollment) completes successfully.</td></tr><tr><td>400</td><td valign="top">Bad Request</td><td>Returned when a CSR is malformed, missing required fields, or improperly encoded.</td></tr><tr><td>401</td><td valign="top">Unauthorized</td><td>Returned when the client fails to provide correct authentication (HTTP auth, TLS cert).</td></tr><tr><td>500</td><td valign="top">Internal Server Error</td><td>Unexpected error on the EST server</td></tr></tbody></table>