# Enabling TLS/SSL for CMA

Learn more about how to enable and configure TLS/SSL for Cloudera Migration Assistant (CMA) when deploying the CMA server locally or with Docker.

> **Note:** In **parcel deployments**, TLS/SSL is configured through Cloudera Manager (Auto-TLS). The steps below apply only to **local** and **Docker** deployment modes. 

**Before you begin**
- Ensure that you have a PKCS12 keystore created with the cma key alias. JKS keystore is also supported.

**Steps**

1. Click **Settings** on the homepage of CMA.

![Enabling TLS/SSL](../images/cma-enabling-tls.png)

2. Enable TLS/SSL using the **checkbox** on the **TLS Settings** page.

![Configuring TLS/SSL](../images/cma-configuring-tls.png)

3. Provide the TLS/SSL **Certificate** in PEM format.
4. Provide the **Private Key** in PEM format.
5. Provide the Private Key **Password** if the Private Key is encrypted.
6. Provide the **Keystore File Location**.
7. Provide the **Keystore File Password**.
8. Select the **Keystore Type** from the drop-down menu.
9. Provide a **Key Alias**.
10. Provide the **Trust Store**.
11. Provide the **Trust Store Password**.
12. Provide the **Trust Store Type**.
13. Click **Save**.
14. Click **Restart** after saving the TLS/SSL configurations.

**After you finish**

After restarting, the CMA server listens on the default port 8090 (HTTP) and 8093 (HTTPS), and all HTTP requests are redirected to the HTTPS port.

## Enabling gRPC TLS for Master-Agent Communication

CMA supports TLS encryption on the gRPC channel between the CMA Master and CMA Agents. When enabled, all command dispatch, scan result streaming, and status updates are encrypted in transit. Plaintext mode remains the default so existing deployments are unaffected.

> **Note:** In **Docker deployments**, gRPC TLS is always enabled automatically. In **CSD (parcel) deployments**, the agent automatically downloads the master's certificate on first start when `CMA_MASTER_SSL_ENABLED=true`.

### Configuring gRPC TLS on the Master

Set the following environment variables on the CMA Master host:

| Variable | Default | Description |
|----------|---------|-------------|
| `CMA_GRPC_SSL_ENABLED` | `false` | Set to `true` to enable TLS on the gRPC server. Forced `true` when the `ssl` Spring profile is active or in Docker. |
| `CMA_KEYSTORE_LOCATION` | — | Path to the keystore file (PKCS12 or JKS) |
| `CMA_KEYSTORE_PASSWORD` | — | Keystore password |
| `CMA_KEYSTORE_TYPE` | `PKCS12` | Keystore type (`PKCS12` or `JKS`) |
| `CMA_GRPC_EXTRA_SANS` | — | Additional Subject Alternative Names for the gRPC certificate. Use for cross-host Docker deployments (e.g., `DNS:master.example.com`). |

In parcel deployments, the Master reuses the keystores and truststores already provisioned by Cloudera Manager (Auto-TLS).

### Configuring gRPC TLS on the Agent

Set the following environment variables on the CMA Agent host:

| Variable | Default | Description |
|----------|---------|-------------|
| `CMA_MASTER_SSL_ENABLED` | `false` | Set to `true` to enable TLS on the agent's gRPC client connection to the Master. |
| `CMA_MASTER_GRPC_NEGOTIATION_TYPE` | `plaintext` | Set to `tls` when gRPC TLS is enabled. Overridden automatically in the `ssl` Spring profile. |
| `CMA_TRUSTSTORE_LOCATION` | — | Path to the truststore containing the Master's certificate |
| `CMA_TRUSTSTORE_PASSWORD` | — | Truststore password |
| `CMA_TRUSTSTORE_TYPE` | `PKCS12` | Truststore type (`PKCS12` or `JKS`) |

### Bootstrapping the Agent Truststore

CMA provides a helper script to download the Master's TLS certificate and create a truststore on the Agent host:

```shell
download-ssl-cert.sh \
  --host <master-host> \
  --port 8091 \
  --truststore /path/to/agent-truststore.p12 \
  --password <truststore-password>
```

The script supports full certificate chains, JKS and PKCS12 formats, and handles alias conflicts automatically. Errors are reported on stderr.

**Automatic bootstrap:**

- **CSD (parcel) deployments**: When `CMA_MASTER_SSL_ENABLED=true` and no truststore exists, the CSD startup script calls `download-ssl-cert.sh` automatically on agent start. A guard prevents unnecessary re-download on every restart.
- **Docker deployments**: The agent container waits for the Master's gRPC port to become available, then downloads the certificate if no truststore is present.
