Understanding Keystores and Truststores

Configuring Cloudera Manager Server and cluster components to use TLS/SSL requires obtaining keys, certificates, and other security artifacts discussed in this guide (see Level 0: Basic TLS/SSL Configuration). This section provides a brief overview of these security artifacts and how they are used by Cloudera clusters configured for TLS/SSL.

Java Keystore and Truststore

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 the default truststore, Cloudera recommends using the alternative truststore, jssecacerts. The alternative truststore is created by copying cacerts to that filename (jssecacerts). Certificates can be added to this truststore when needed for additional roles or services. This alternative truststore is loaded by Hadoop daemons at startup.

All clients in a Cloudera Manager cluster configured for TLS/SSL need access to the truststore to validate certificates presented during TLS/SSL session negotiation. The certificates assure the client or server process that the issuing authority for the certificate is part of a legitimate chain of trust. 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 the general differences between keystore and the truststore in Cloudera Manager Server clusters.

Keystore Truststore
Used by the server side of a TLS/SSL client-server connection. Used by the client side of a TLS/SSL client-server connection.
Typically contains 1 private key for the host system. Contains no keys of any kind.
Contains the certificate for the host's private key. Contains root certificates for well-known public certificate authorities. May contain certificates for intermediary 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).
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 the private key. HDFS, MapReduce, and YARN need client access to truststore.

The details in the table above are specific to the Java KeyStore (JKS) format, which is used by Java-based cluster services such as Cloudera Manager Server, Cloudera Management Service, and many (but not all) CDH components and services. See PEM Certificates for information about certificate and key file type used by Cloudera Manager Agent and several other processes.

PEM Certificates

Python and C++ based services use PEM formatted certificates and keystores rather than Java. Specifically, Cloudera Manager Agent, Hue, Key Trustee Server, and Impala PEM certificates and keys are used for TLS/SSL for PKCS #8PEM has separate files for certificate and a password-protected private key file. is the specific file type that handles certificates and keys as individual Base64-encoded text files, and it is the specific format used by Cloudera Manager cluster components.

OpenSSL

See How to Convert Certificate Encodings (DER, JKS, PEM) for TLS/SSL for more information about converting files between formats.

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.

Hadoop Services as TLS/SSL Servers and Clients

Hadoop services function as either TLS/SSL servers, clients, or both, as shown in the table below.

Component Client Server
HBase
HDFS
Hive
Hue (Hue is a TLS/SSL client of HDFS, MapReduce, YARN, HBase, and Oozie.)
MapReduce
Oozie
YARN

Daemons that function as TLS/SSL servers load the keystores when starting up. When a client connects to an TLS/SSL server daemon, the server transmits the certificate loaded at startup time to the client, and the client then uses its truststore to validate the certificate presented by the server.

Certificate Formats and Hadoop Components

The specific format required for PEM keys and certificates is PKCS #8.

Component JKS PEM
HBase
HDFS
Hive (Hive clients and HiveServer 2)
Hue
Impala
MapReduce
Oozie
Solr
YARN

Recommended Keystore and Truststore Configuration

Cloudera recommends the following for keystores and truststores for Cloudera Manager clusters:
  • 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. The keystore contains the private key and 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 does not need to be password protected. (See How To Add Root and Intermediary CAs to Truststore for more information about the truststore for TLS/SSL and Cloudera clusters.)

The steps included in Generate TLS Certificates follow this approach.