Understanding Java Keystores and Truststores
Configuring Cloudera Manager Server and cluster components to use TLS/SSL requires obtaining keys, certificates, and other security artifacts, as detailed later in this guide (see Level 0: Basic TLS/SSL Configuration). Before getting into the details, here is some general background about the security artifacts used by Cloudera Manager cluster for TLS/SSL communications.
The standard Oracle Java JDK distribution includes a default truststore (cacerts) that contains root certificates for many well-known CAs, including Symantec. Rather than using this default truststore, Cloudera recommends using the alternative truststore (jssecacerts), which is created by simply copying cacerts to a file of that name. This file is loaded by Hadoop daemons at startup. All clients in a Cloudera Manager cluster configured for TLS/SSL need access to the truststore, to ascertain the validity of any certificates presented during TLS/SSL session negotiation, for example. The certificates assure the client or server process as to the validity of the host's public key. The private keys are maintained in the keystore.
Although the keystore and truststore in some environments may comprise the same file, as configured for Cloudera Manager Server and CDH clusters, the keystore and truststore are distinct files. For Cloudera Manager Server clusters, each host should have its own keystore, while several hosts can share the same truststore. This table summarizes these and other relevant details specific to keystores and truststores as used in Cloudera Manager Server clusters:
| Keystore | Truststore |
|---|---|
| Contains the host's private key. | Contains no keys. |
| Contains the certificate for the private key. A self-signed certificate is added automatically when the private key is initially created. A certificate signed by a CA is added to the keystore, supplanting the self-signed certificate with a signed certificate that attests to the host's identity. | Contains root certificates for well-known public certificate authorities. |
| Password protected. Use the same password for the key and its keystore. | Password-protection not needed. However, if password has been used for the truststore, never use the same password as used for a key and keystore. |
| Password stored in a plaintext file read permissions granted to a specific group only (OS filesystem permissions set to 0440, hadoop:hadoop). | Password (if there is one for the truststore) stored in a plaintext file readable by all (OS filesystem permissions set to 0440). |
| Contains 1 private key (typically) for the host system. | Contains 0 private keys. |
| No default. Provide a keystore name and password when you create the private key and CSR for any host system. | For Java JDK, cacerts is the default unless the alternative default jssecacerts is available. |
| Must be owned by hadoop user and group so that HDFS, MapReduce, YARN can access it. | HDFS, MapReduce, and YARN need client access to truststore. |
The content of the truststore for the Cloudera Manager Server cluster can be modified (certificates added, for example) without restarting the server: Changes to the truststore are adopted by the system within 10 seconds.
Creating and Using the Truststore
- Create a separate keystore for each host. Each keystore should have a name that helps identify it as to the type of host (server or agent, for example). Each keystore and the private key each contains should be password-protected.
- Create a single truststore that can be used by the entire cluster. This truststore contains the root CA and intermediate CAs used to authenticate certificates presented during TLS/SSL handshake. The truststore need not be password protected.
The steps included in Obtain and Deploy Server Certificate follow this approach.