Cloudera Docs

Installing a Java Keystore KMS

The tasks and steps for installing a Java KeyStore Ranger Key Management System (KMS) service to the cluster for your HDFS data-at-rest encryption.

Describes how to install a file-based password-protected Java KeyStore KMS service to your cluster. The Java KeyStore KMS service uses a password-protected Java KeyStore for cryptographic key management. This option does not include HA.

The following image shows the Set up HDFS Data At Rest Encryption page. When you select your encryption keys root of trust option, a list of tasks that you must do to enable encryption to-and-from HDFS is displayed.

You complete each task independently from the other tasks. Where, the task’s Status column indicates whether the step has been completed and the Notes column provides additional context for the task. If your Cloudera Manager user account does not have sufficient privileges to complete a task, the Notes column indicates the privileges that are required.

When selected, each task contains links to wizards or documentation that help you complete the task. If a task is unavailable, due to insufficient privileges or an incomplete prerequisite step, no links are present and the Notes column displays the reason.


The Wizard steps are as follows and must be completed in the order listed:
  1. Enable Kerberos
  2. Enable TLS/SSL
  3. Add the Java KeyStore KMS Service
  4. Restart the stale services and redeploy the client configuration
  5. Validate the Data Encryption
Verify the following:
  • The cluster in which Cloudera Manager and the Cloudera Ranger service is installed, is up and running.
  • Communication through secure connections is enabled with the Transport Layer Security (TLS) protocol and your network authentication is enabled with the Kerberos protocol.
  1. In a supported web browser on the cluster in which the Ranger service is installed, log in to Cloudera Manager as a user with full administrative privileges.
  2. From the Cloudera Manager navigation side-bar, select Administration > Security.
  3. On the Security Status page, click Set up HDFS Data At Rest Encryption.
  4. In the Set up HDFS Data At Rest Encryption page, select the A file-based password-protected Java KeyStore option.
    A list of tasks are displayed at the bottom of the page. To successfully set up HDFS Data at Rest encryption, these tasks must be completed.
  5. To set up HDFS Encryption, follow the instructions as described below for each of the Set up HDFS Data At Rest Encryption Wizard's steps.

Adding the Java KeyStore KMS Service

The Set up HDFS Data At Rest Encryption wizard's installation step that installs the Java KeyStore KMS service on your cluster.

Describes the steps that add the Java KeyStore KMS service to the cluster.

  1. From the Step column in the Set up HDFS Data at Rest Encryption for Cluster page, click Add a Java KeyStore KMS Service.
    The Add Java KeyStore KMS Service to Cluster Wizard opens.
  2. In the Assign Roles page, verify that the hostname is the required server on which to add the Java KeyStore KMS service by clicking inside the Key Management Server field. By default, this field is populated by the Wizard.
    The Hosts Selected page opens.
  3. In the Hosts Selected page, scroll down and from the Hostname column, locate the hostname that was selected by the Wizard. Notice in the Added Roles column the Java KeyStore KMS Key Management Server (KMS) role icon. This role is added during the installation.
  4. Do one of the following:
    • If the pre-selected host is correct, confirm the Wizard's choice by clicking OK.
    • If the pre-selected host is incorrect, deselect the check box of the Wizard's choice, select the hostname check box of the required server, and then click OK.
  5. Back in the Assign Roles page, click Continue.
    The Setup Access Control List (ACL) page opens, which enables you to create a key admin user and group that can perform special functions. By default, non-admin users cannot access encrypted data.
  6. Depending on your requirements do one of the following:
    • To use your own kms-acls.xml file, select the Use Your Own kms-acls.xml File option and in the kms-acls.xml text box, enter the contents of your kms-acls.xml file and then click Continue.
    • To have the wizard create a kms-acls.xml file and appropriate ACLs do the following:
      1. Select the Use Recommendation.
      2. In the Key Admin User field, enter the name of the user with administrative privileges.
      3. In the Key Admin Group field, enter the name of the Group in which the user's can perform special functions.
      4. Click Generate ACLs, which populates the text field with a list of appropriate ACLs.
      5. Click Continue.
    The Setup TLS for Java KeyStore KMS page opens, which provides high-level instructions for configuring TLS communication between your cluster and the Java KeyStore KMS.
  7. Click Continue.
    The Review Changes page opens.
  8. Review the settings and make any required changes before clicking Continue.
  9. In the Command Details page, monitor the installation of the Java KeyStore KMS service. When the Status displays Finished the Java KeyStore KMS is installed and tested.
  10. Click Continue.
    The Setup HDFS Dependency page opens.
  11. Click Continue, which enables the HDFS service and opens the Summary page.
  12. Click Finish, which returns you to the Set up HDFS Data at Rest Encryption for Cluster page.
  13. (Optional) Verify that the Java KeyStore KMS service appears in the Cloudera Manager Clusters components list.
    If the Java KeyStore KMS service was not started by the installation wizard, do the following:
    1. Go to Cloudera Manager's Home page by clicking the Cloudera Manager icon.
    2. In the Cloudera Manager Clusters components list, locate and click Java KeyStore KMS.
    3. From the Actions menu, click Start.
Restart the stale services and redeploy the client configuration.

Restarting the Stale Services and Redeploying the Client Configuration

The Set up HDFS Data At Rest Encryption wizard's step for restarting stale services and redeploying the client configuration.

Describes the steps that restart stale services after installing the Data-at-Rest HDFS Ranger KMS service option on your cluster.

  1. From the Step column in the Set up HDFS Data at Rest Encryption for Cluster page, click Restart stale services and redeploy client configuration..
    The Stale Configurations page opens.
  2. Click Restart Stale Services.
    The restart Stale Services page opens.
  3. Verify that the Re-deploy client configuration check box is selected and click Restart Now.
  4. In the Command Details page, monitor the restart process. When the Status displays Finished, click Continue, which returns you to the Set up HDFS Data at Rest Encryption for Cluster page.
Validate that the Data-at-Rest HDFS Ranger KMS service option can successfully encrypt your data to-and-from HDFS.

Validating Data Encryption to-and-from HDFS

The Set up HDFS Data At Rest Encryption wizard's step for validating the data encryption to-and-from HDFS.

Describes the steps which verify that the Data-at-Rest HDFS Ranger KMS service option can successfully encrypt your data to-and-from HDFS.

  1. From the Step column in the Set up HDFS Data at Rest Encryption for Cluster page, click Validate Data Encryption.
    The Validate Data Encryption page opens, which displays a list of commands and instructions for creating an encryption zone and adding data.
  2. In a terminal, log in to one of the hosts in your cluster and run each of the following commands:
    1. Create a key and directory by entering the following: 
      kinit KEY_ADMIN_USER 
hadoop key create mykey1 
hadoop fs -mkdir /tmp/zonel
      Where, KEY_ADMIN_USER is the key administrator whose role can perform the following actions:
      • Configure HDFS encryption, administer Key Trustee Server, and manage encryption keys
      • Start, stop, and restart Ranger KMS
      • Configure Ranger KMS Policies
      • View configuration and monitoring information in Cloudera Manager
      • View service and monitoring information
      • View events and logs
      • View Replication jobs and snapshot policies
      • View YARN applications and Impala queries
    2. Create a zone and link to the key, by entering the following: 
      kinit hdfs hdfs 
crypto -createZone -keyName mykey1 -path /tmp/zone1
    3. Create a file, put it in your zone, and verify that the file can be decrypted, by entering the following: 
      kinit KEY ADMIN_USER
echo "Hello World" > /tmp/helloWorld.txt
hadoop fs -put /tmp/helloWorld.txt /tmp/zone1
hadoop fs -cat /tmp/zonel/helloWorld.txt
rm /tmp/helloWorld.txt
    4. Verify that the stored file is encrypted, by entering the following: 
      kinit hdfs
hadoop fs -cat /.reserved/raw/tmp/zonel/helloWorld.txt
hadoop fs -rm -R / tmp/zone1
  3. When completed, click Close, which returns you to the Set up HDFS Data at Rest Encryption for Cluster page.