Configuring TLS Encryption Only for Cloudera Manager

Minimum Required Role: Cluster Administrator (also provided by Full Administrator)

Before enabling TLS security for Cloudera Manager, you must create a keystore, submit a certificate-signing request, and install the issued certificate for the Server. You do this using the Oracle JDK keytool command-line tool. If you are using a Private CA, append its certificate (and any required intermediary certificates) to the alternate default truststore provided with the JDK for inherent trust. This process is described in detail in Creating Truststores.

The table below shows the paths for managing certificates in the following examples . These paths persist during any upgrades and should be removed manually if the host is removed from a CDH cluster. Note that the folders and filepaths listed here can reside anywhere on the system and must be created on every host, especially as later sections move on to creating certificates for each host.

Set permissions on the paths such that scm-user, hue, Hadoop service users (or groups), and root users can read the private key, certificate, and keystore and truststore files.

Example Property Values	Description
`cmhost.sec.cloudera.com`	FQDN for Cloudera Manager Server host.
`/opt/cloudera/security`	Base location for security-related files.
`/opt/cloudera/security/x509`	Location for `openssl key/, cert/` and `cacerts/` files to be used by the Cloudera Manager Agent and Hue.
`/opt/cloudera/security/jks`	Location for the Java-based `keystore/` and `truststore/` files for use by Cloudera Manager and Java-based cluster services.
`/opt/cloudera/security/CAcerts`	Location for CA certificates (root and intermediary/subordinate CAs). One PEM file per CA in the chain is required.

Step 1: Create the Cloudera Manager Server Keystore, Generate a Certificate Request, and Install the Certificate

The following procedure assumes that a private Certificate Authority is used, and therefore trust must be established for that private CA. If a known public CA such as Verisign or GeoTrust is used, you may not need to explicitly establish trust for the issued certificates. Newer public CAs might not be present yet in the JDK default cacerts file. If you have problems with the import process (such as keytool error: java.lang.Exception: Failed to establish chain from reply), follow the steps for trusting private CAs below.

Assuming the paths documented in the table above have been created, use keytool to generate a Java keystore and Certificate Signing Request (CSR) for the Cloudera Manager Server. Replace cmhost and cmhost.sec.cloudera.com in the commands below with your hostname and FQDN. For example:
```
$ keytool -genkeypair -alias cmhost -keyalg RSA -keystore \
/opt/cloudera/security/jks/cmhost-keystore.jks -keysize 2048 -dname \
"CN=cmhost.sec.cloudera.com,OU=Support,O=Cloudera,L=Denver,ST=Colorado,C=US" \
-storepass password -keypass password
```
- -alias is a label used only in the keystore. In this example, the hostname is used for easy tracking and management of the key and certificate. Ensure that -alias is consistent across all your commands.
- -keyalg is the algorithm used to generate the key. Cloudera recommends you use RSA, which allows key lengths greater than 1024 bits for certificate requests. Other algorithms such as the DSA may not be supported by certain browsers, resulting in the javax.net.ssl.SSLHandshakeException: no cipher suites in common error.
- -dname allows you to provide the certificate subject as a single line. If not specified, you will be prompted for the values of the certificate subject information. In that case, use the host FQDN that agents and browsers will use to connect to in the subject First and Last name (CN) question prompt.
  Note: The CN entry must match the hostname of the Cloudera Manager server, or you will get the java.io.IOException: HTTPS hostname wrong exception.
- /opt/cloudera/security/jks/cmhost-keystore.jks is an example path to the keystore where you store the keystore file and where the Cloudera Manager Server host can access it.
- Set -keypass to the same value as -storepass. Cloudera Manager assumes that the same password is used to access both the key and the keystore, and therefore, does not support separate values for -keypass and -storepass.

Generate a certificate signing request for the host (in this example, cmhost).

$ keytool -certreq -alias cmhost \
-keystore /opt/cloudera/security/jks/cmhost-keystore.jks \
-file /opt/cloudera/security/x509/cmhost.csr -storepass password \
-keypass password

Submit the .csr file created by the -certreq command to your Certificate Authority to obtain a server certificate. When possible, work with certificates in the default Base64 (ASCII) format. You can easily modify Base64-encoded files from .CER or .CRT to .PEM. The file is in ASCII format if you see the opening and closing lines as follows:
```
-----BEGIN CERTIFICATE----- 
( the encoded certificate is represented by multiple lines of exactly 64 characters, except 
for the last line which can contain 64 characters or less.) 
-----END CERTIFICATE-----
```
If your issued certificate is in binary (DER) format, adjust the commands according to the keytool documentation.
Copy the root CA certificate and any intermediary or subordinate CA certificates to /opt/cloudera/security/CAcerts/.
Important: For a private CA, you must import the private CA and intermediary or subordinate CA certificates into an alternative default JDK truststore jssecacerts, before importing them to your Java keystore.
1. Import the root CA certificate first, followed by any intermediary or subordinate CA certificates. Substitute $JAVA_HOME in the command below with the path for your Oracle JDK.
```
$ sudo cp $JAVA_HOME/jre/lib/security/cacerts $JAVA_HOME/jre/lib/security/jssecacerts

$ sudo keytool -importcert -alias RootCA -keystore $JAVA_HOME/jre/lib/security/jssecacerts \
-file /opt/cloudera/security/CAcerts/RootCA.cer -storepass changeit

$ sudo keytool -importcert -alias SubordinateCA -keystore \
$JAVA_HOME/jre/lib/security/jssecacerts \
-file /opt/cloudera/security/CAcerts/SubordinateCA.cer -storepass changeit
```
  Repeat for as many subordinate or intermediary CA certificates as needed. The default -storepass for the cacerts file is changeit. After completing this step, copy the jssecacerts file created to the same path on all cluster hosts.
2. Import the Private CA certificates into your Java keystore file. Import the root CA certificate first.
```
$ keytool -importcert -trustcacerts -alias RootCA -keystore \
/opt/cloudera/security/jks/<cmhost-keystore>.jks -file \
/opt/cloudera/security/CAcerts/RootCA.cer -storepass password

$ keytool -importcert -trustcacerts -alias SubordinateCA -keystore \ 
/opt/cloudera/security/jks/<cmhost-keystore>.jks -file \ 
/opt/cloudera/security/CAcerts/SubordinateCA.cer -storepass password
```
  Repeat for as many subordinate/intermediary CA certificates as needed.
Copy the signed certificate file provided to a location where it can be used by the Cloudera Manager Agents (and Hue if necessary).
```
$ cp certificate-file.cer  /opt/cloudera/security/x509/cmhost.pem
```
Install it with the following keytool command:
```
$ keytool -importcert -trustcacerts -alias cmhost \ 
-file /opt/cloudera/security/x509/cmhost.pem \ 
-keystore /opt/cloudera/security/jks/cmhost-keystore.jks -storepass password
```
You must see the following response verifying that the certificate has been properly imported against its private key.
```
Certificate reply was installed in keystore
```
Because the issued certificate has been imported by the Java keystore, the original certificate-signing request (.CSR) and certificate files are no longer needed by Java services on that host, and the certificate and private key are now accessed through the keystore.
However, you still must export the private key from the Java keystore to make the certificate usable by Hue and the Cloudera Manager Agent. For instructions on reusing certificates, see Private Key and Certificate Reuse Across Java Keystores and OpenSSL.

Step 2: Enable HTTPS for the Cloudera Manager Admin Console and Specify Server Keystore Properties

Log into the Cloudera Manager Admin Console.
Select Administration > Settings.
Click the Security category.

Configure the following TLS settings:

Property	Description
Path to TLS Keystore File	The complete path to the keystore file. In the example, this path would be: `/opt/cloudera/security/jks/cmhost-keystore.jks`
Keystore Password	The password for keystore: `password`
Use TLS Encryption for Admin Console	Check this box to enable TLS encryption for Cloudera Manager.

Click Save Changes to save the settings.

Step 3: Specify SSL Truststore Properties for Cloudera Management Services

When enabling TLS for the Cloudera Manager UI, you must set the Java truststore location and password in the Cloudera Management Services configuration. If this is not done, roles such as the Host Monitor and Service Monitor will be unable to connect to Cloudera Manager and will not start.

Open the Cloudera Manager Administration Console and go to the Cloudera Management Service.
Click the Configuration tab.
Select Scope > Cloudera Management Service (Service-Wide).
Select Category > Security.

Edit the following TLS/SSL properties according to your cluster configuration.

Property	Description
TLS/SSL Client Truststore File Location	Path to the client truststore file used in HTTPS communication. The contents of this truststore can be modified without restarting the Cloudera Management Service roles. By default, changes to its contents are picked up within ten seconds.
TLS/SSL Client Truststore File Password	Password for the client truststore file.

Click Save Changes to commit the changes.
Restart the Cloudera Management Service. For more information, see HTTPS Communication in Cloudera Manager.

Step 4: Restart the Cloudera Manager Server

Restart the Cloudera Manager Server by running service cloudera-scm-server restart from the Cloudera Manager host command prompt.

You should now be able to connect to the Cloudera Manager Admin Console using an HTTPS browser connection. If a private CA certificate or self-signed certificate is used, you must establish trust in the browser for your certificate. This should be done for all browsers that will be used to access Cloudera Manager. By default, certificates issued by public commercial CAs should be trusted by the browsers accessing Cloudera Manager and other Java or OpenSSL-based services.

For more information on establishing trust for certificates, see TLS/SSL Certificates Overview or the relevant JDK documentation.

Configuring TLS Security for Cloudera Manager

Level 1: Configuring TLS Encryption for Cloudera Manager Agents