Securing the Key Management Server (KMS)

Cloudera provides the following implementations of the Hadoop KMS:
  • Java KeyStore KMS - The default Hadoop KMS included in CDH that uses a file-based Java KeyStore (JKS) for its backing keystore. For parcel-based installations, no additional action is required to install or upgrade the KMS. For package-based installations, you must install additional packages. For more information, see Installing and Upgrading Java KeyStore KMS. Cloudera strongly recommends not using Java Keystore KMS in production environments.
  • Key Trustee KMS - A custom KMS that uses Cloudera Navigator Key Trustee Server for its backing keystore instead of the file-based Java KeyStore (JKS) used by the default Hadoop KMS. Cloudera strongly recommends using Key Trustee KMS in production environments to improve the security, durability, and scalability of your cryptographic key management. For more information about the architecture and components involved in encrypting data at rest for production environments, see Cloudera Navigator Data Encryption Overview and Data at Rest Encryption Reference Architecture. For instructions on installing and upgrading Key Trustee KMS, see: Also, integrating Key Trustee Server with Cloudera Navigator Key HSM provides an additional layer of protection.
  • Navigator KMS Services backed by Thales HSM - A custom KMS that uses a supported Thales Hardware Security Module (HSM) as its backing keystore. This KMS service provides the highest level of key isolation to customers who require it.

    For installation information about Navigator KMS Services backed by Thales HSM, see Installing Navigator HSM KMS Backed by Thales HSM.

  • Navigator KMS Services backed by Luna HSM - A custom KMS that uses a supported Luna Hardware Security Module (HSM) as its backing keystore. This KMS provides the highest level of key isolation to customers who require it.

    For installation information about Navigator KMS Services backed by Luna HSM, see Installing Navigator HSM KMS Backed by Luna HSM.

This topic contains information on securing the KMS using Kerberos, TLS/SSL communication, and access control lists (ACLs) for operations on encryption keys. Cloudera Manager instructions can be performed for both Key Trustee KMS and Java KeyStore KMS deployments. Command-line instructions apply only to Java KeyStore KMS deployments. Key Trustee KMS is not supported outside of Cloudera Manager. For more information, see Installing Key Trustee KMS.

Enabling Kerberos Authentication for the KMS

Enabling Kerberos Authentication for the KMS Using Cloudera Manager

Minimum Required Role: Full Administrator

To enable Kerberos for the KMS using Cloudera Manager:
  1. Open the Cloudera Manager Admin Console and go to the KMS service.
  2. Click Configuration.
  3. Set the Authentication Type property to kerberos.
  4. Click Save Changes.
  5. Because Cloudera Manager does not automatically create the principal and keytab file for the KMS, you must run the Generate Credentials command manually. On the top navigation bar, go to Administration > Security > Kerberos Credentialsand click Generate Missing Credentials.
  6. Return to the Home page by clicking the Cloudera Manager logo.
  7. Click the icon that is next to any stale services to invoke the cluster restart wizard.
  8. Click Restart Stale Services.
  9. Click Restart Now.
  10. Click Finish.

Enabling Kerberos Authentication for the Java KeyStore KMS Using the Command Line

Configure /etc/krb5.conf with information for your KDC server. Create an HTTP principal and keytab file for the KMS.

Configure /etc/hadoop-kms/conf/kms-site.xml with the following properties:
<property>
    <name>hadoop.kms.authentication.type</name>
    <value>kerberos</value>
</property>

<property>
    <name>hadoop.kms.authentication.kerberos.keytab</name>
    <value>${user.home}/kms.keytab</value>
</property>

<property>
    <name>hadoop.kms.authentication.kerberos.principal</name>
    <value>HTTP/localhost</value>
</property>

<property>
    <name>hadoop.kms.authentication.kerberos.name.rules</name>
    <value>DEFAULT</value>
</property>
Restart the KMS service for the configuration changes to take effect.

Configuring the Java KeyStore KMS Proxyuser Using the Command Line

Each proxyuser must be configured in /etc/hadoop-kms/conf/kms-site.xml using the following properties:
<property>
    <name>hadoop.kms.proxyuser.#USER#.users</name>
    <value>*</value>
</property>

<property>
    <name>hadoop.kms.proxyuser.#USER#.groups</name>
    <value>*</value>
</property>

<property>
    <name>hadoop.kms.proxyuser.#USER#.hosts</name>
    <value>*</value>
</property>

where #USER# is the username of the proxyuser to be configured.

The hadoop.kms.proxyuser.#USER#.users property indicates the users that can be impersonated. The hadoop.kms.proxyuser.#USER#.groups property indicates the groups to which the users being impersonated must belong. At least one of these properties must be defined. If both are defined, the configured proxyuser can impersonate any user in the users list and any user belonging to a group listed in the groups list.

The hadoop.kms.proxyuser.#USER#.hosts property indicates the host from which the proxyuser can make impersonation requests. "*" means there are no restrictions for the #USER# regarding users, groups, or hosts.

Configuring TLS/SSL for the KMS

Configuring TLS/SSL for the KMS Using Cloudera Manager

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

The steps for configuring and enabling Hadoop TLS/SSL for the KMS are as follows:
  1. Go to the KMS service.
  2. Click Configuration.
  3. In the Search field, type TLS/SSL to show the KMS TLS/SSL properties (in the Key Management Server Default Group > Security category).
  4. Edit the following TLS/SSL properties according to your cluster configuration.
    KMS TLS/SSL Properties
    Property Description
    Enable TLS/SSL for Key Management Server Encrypt communication between clients and Key Management Server using Transport Layer Security (TLS) (formerly known as Secure Socket Layer (TLS/SSL)).
    Key Management Server TLS/SSL Server JKS Keystore File Location The path to the TLS/SSL keystore file containing the server certificate and private key used for TLS/SSL. Used when Key Management Server is acting as a TLS/SSL server. The keystore must be in JKS format.
    Key Management Server TLS/SSL Server JKS Keystore File Password The password for the Key Management Server JKS keystore file.
    Key Management Server Proxy TLS/SSL Certificate Trust Store File The location on disk of the truststore, in .jks format, used to confirm the authenticity of TLS/SSL servers that Key Management Server Proxy might connect to. This is used when Key Management Server Proxy is the client in a TLS/SSL connection. This truststore must contain the certificates used to sign the services connected to. If this parameter is not provided, the default list of well-known certificate authorities is used instead.
    Key Management Server Proxy TLS/SSL Certificate Trust Store Password The password for the Key Management Server Proxy TLS/SSL Certificate Trust Store File. This password is not required to access the truststore; this field can be left blank. This password provides optional integrity checking of the file. The contents of truststores are certificates, and certificates are public information.
  5. Click Save Changes.
  6. Return to the Home page by clicking the Cloudera Manager logo.
  7. Click the icon that is next to any stale services to invoke the cluster restart wizard.
  8. Click Restart Stale Services.
  9. Click Restart Now.
  10. Click Finish.

For help troubleshooting TLS/SSL for KMS configuration issues, see Troubleshooting TLS/SSL Issues in Cloudera Manager.

Configuring TLS/SSL for the Java KeyStore KMS Using the Command Line

To configure KMS to work over HTTPS, set the following properties in the /etc/hadoop-kms/conf/kms_env.sh script:

  • KMS_SSL_KEYSTORE_FILE
  • KMS_SSL_KEYSTORE_PASS
  • KMS_SSL_TRUSTSTORE_FILE
  • KMS_SSL_TRUSTSTORE_PASS

In the /etc/hadoop-kms/tomcat-conf/conf/ directory, replace the server.xml file with the provided ssl-server.xml file.

Create a TLS/SSL certificate for the KMS. As the kms user, use the Java keytool command to create the TLS/SSL certificate:
$ keytool -genkey -alias tomcat -keyalg RSA

You are asked a series of questions in an interactive prompt. It creates the keystore file, which is named .keystore and located in the kms user home directory. The password you enter for the keystore must match the value of the KMS_SSL_KEYSTORE_PASS environment variable set in the kms-env.sh script in the configuration directory.

The answer to "What is your first and last name?" (CN) must be the hostname of the machine where the KMS will be running.