Managing Encryption Keys and Zones

Interacting with the KMS and creating encryption zones requires the use of two new CLI commands: hadoop key and hdfs crypto. The following sections will help you get started with creating encryption keys and setting up encryption zones.

Before continuing, make sure that your KMS ACLs have been set up according to best practices. For more information, see Configuring KMS Access Control Lists.

Validating Hadoop Key Operations

Use hadoop key create to create a test key, and then use hadoop key list to retrieve the key list: 
$ sudo -u <key_admin> hadoop key create keytrustee_test
$ hadoop key list

Creating Encryption Zones

Once a KMS has been set up and the NameNode and HDFS clients have been correctly configured, use the hadoop key and hdfs crypto command-line tools to create encryption keys and set up new encryption zones.

  • Create an encryption key for your zone as the keyadmin for the user/group (regardless of the application that will be using the encryption zone): 
    $ sudo -u hdfs hadoop key create <key_name>
  • Create a new empty directory and make it an encryption zone using the key created above. 
    $ sudo -u hdfs hadoop fs -mkdir /encryption_zone
$ sudo -u hdfs hdfs crypto -createZone -keyName <key_name> -path /encryption_zone
    You can verify creation of the new encryption zone by running the -listZones command. You should see the encryption zone along with its key listed as follows: 
    $ sudo -u hdfs hdfs crypto -listZones
/encryption_zone    <key_name>

For more information and recommendations on creating encryption zones for each CDH component, see Configuring CDH Services for HDFS Encryption.

Adding Files to an Encryption Zone

Existing data can be encrypted by coping it copied into the new encryption zones using tools like DistCp. See DistCp Considerations for information on using DistCp with encrypted data files.

You can add files to an encryption zone by copying them to the encryption zone using distcp. For example: 
sudo -u hdfs hadoop distcp /user/dir /encryption_zone
Additional Information:

Deleting Encryption Zones

To remove an encryption zone, delete the encrypted directory: 
$ sudo -u hdfs hadoop fs -rm -r -skipTrash /encryption_zone

Backing Up Encryption Keys

If you are using the Java KeyStore KMS, make sure you regularly back up the Java KeyStore that stores the encryption keys. If you are using the Key Trustee KMS and Key Trustee Server, see Backing Up and Restoring Key Trustee Server for instructions on backing up Key Trustee Server and Key Trustee KMS.