Cloudera Director Database Encryption

The Cloudera Director server stores sensitive data in its database, including SSH credentials and cloud provider keys. You can configure Cloudera Director to encrypt the data stored in the Cloudera Director database.

Cipher Configuration

Database encryption is configured by setting the two server configuration properties described in the following table.

Server Configuration Properties
Property Description
lp.encryption.twoWayCipher Cipher used to encrypt data. Possible values:
  • desede - Triple DES (default)
  • passthrough - No encryption
  • transitional - Changing encryption
lp.encryption.twoWayCipherConfig The configuration string for the chosen cipher.

The format of the configuration string varies with the choice of cipher, as described in the table below:

Ciphers and Configuration Strings
Cipher Configuration String Format
desede 24-byte symmetric encryption key, encoded as a string using Base64
passthrough ignored
transitional combination of old cipher and new cipher (see below)
The default value for the configuration string is a fixed 24-byte key for the default triple DES encryption: 
ZGVmYXVsdGRpcmVjdG9yZGVzZWRla2V5

Starting with Encryption

Cloudera Director’s default configuration for database encryption encrypts new data stored in the Cloudera Director database. This default configuration uses triple DES encryption, with a default key, to protect data. In a new installation of Cloudera Director, all data needing protection will be encrypted under the default encryption scheme. In an installation that was previously not configured for encryption, including older releases of Cloudera Director, new data needing protection will be encrypted, but old data needing protection will remain unencrypted until it is updated in the database over time.

If this level of protection is sufficient for your needs, it is not necessary to make any changes to Cloudera Director configuration. While Cloudera Director will function correctly, keep in mind that there are drawbacks: some data needing protection in the database may remain unencrypted indefinitely, and data that is encrypted is effectively only obscured, since the default key is not secret.

Establishing More Secure Encryption for New Installations

For a new installation of Cloudera Director, Cloudera recommends that you generate and configure your own secret encryption key, different from the default key. Create a new key by generating 24 bytes of random data from a cryptographically secure random generator, and encode the bytes using the Base64 encoding algorithm.

Here is an example of generating a new key using Python. 
python -c 'import base64, os; print base64.b64encode(os.urandom(24))'
Set the Cloudera Director configuration property lp.encryption.twoWayCipherConfig to the Base64-encoded key string before starting Cloudera Director for the first time. All data needing protection in the database will be encrypted with this key. It is good practice to change the encryption key periodically to protect against unintentional disclosure. See Changing Encryption below for more.

Establishing More Secure Encryption for Existing Installations

For an existing installation of Cloudera Director that uses either no encryption at all (including older releases of Cloudera Director) or uses only the default encryption, Cloudera recommends that you use a transitional cipher to change encryption to a more secure state. Not only will changing encryption introduce the use of a non-default and secret key, but it will also forcibly encrypt all data needing protection in the database, whether it was already encrypted or not.

See Changing Encryption below for details on how to configure a transitional cipher to change encryption. When configuring the transitional cipher, you will need to know information about the old cipher that was in effect.
  • If the default cipher and key was in use previously, then use "desede" and the default key for the old cipher configuration.
  • If no encryption was in place previously, including older releases of Cloudera Director which did not support database encryption, then use "passthrough" (with no configuration string) for the old cipher configuration.

The new cipher should be triple DES ("desede") with a secret key that you generate. See Establishing More Secure Encryption for New Installations above for details on how to generate a good key.

After establishing more secure encryption, it is good practice to change the encryption key periodically to protect against unintentional disclosure. Use the transitional cipher again to change encryption to use a new key.

Changing Encryption

To change the key used for database encryption, or change to a different cipher, you must configure the Cloudera Director server to use a transitional cipher.

If a transitional cipher is configured, Cloudera Director encrypts all data that needs protection, changing from an old encryption scheme to a new encryption scheme. A transitional cipher can change the encryption in effect, or introduce it when it has not been used before, including under older Cloudera Director releases. It also ensures that all data needing protection becomes encrypted.

To configure a transitional cipher:
  1. Stop the server.
  2. Configure lp.encryption.twoWayCipher with the value transitional.
  3. Configure lp.encryption.twoWayCipherConfig with a configuration string describing both the old cipher and the new cipher.
  4. Start the server.
The configuration string for a transitional cipher has the following format: 
old-cipher;old-configuration-string|new-cipher;new-configuration-string
For example, to change the triple DES key, use a configuration string like this: 
desede;old-key-in-base64|desede;new-key-in-base64
To transition from the default triple DES encryption key to a new key, use a configuration string like this: 
desede;ZGVmYXVsdGRpcmVjdG9yZGVzZWRla2V5|desede;new-key-in-base64
To transition from no encryption to triple DES encryption with a new key, use a configuration string like this: 
passthrough;|desede;new-key-in-base64

A transitional cipher cannot be used as the old or new cipher in another transitional cipher.

When the server restarts, it detects that a transitional cipher is configured and updates all relevant data, unencrypted and encrypted, to the new cipher. After this process is complete, the server continues startup as usual. Configuring a transitional cipher ensures that all data needing protection in the database is encrypted.

Wait for the Server to Complete Ongoing Work

Do not try to change encryption while the server is performer ongoing work. If any work is waiting to be resumed by the server on startup (for example, bootstrapping a new cluster), then the server will refuse to change encryption and will stop. If this happens, you must configure the server for its old cipher, start it, and wait for that work to resume and be completed.

Changing from a Transitional Cipher to a Normal Cipher

After encryption has been changed using a transitional cipher, you can configure the server to use the new cipher normally.

Example: Assume the configuration string for the transitional cipher was as follows: 
desede;old-key-in-base64|desede;new-key-in-base64
One restart of the server will suffice to pick up this change, and then the following configuration string for a normal cipher can be used: 
desede;new-key-in-base64
Cloudera recommends that the server be left to run with a transitional cipher only until its next restart or upgrade, and then be reconfigured to use a normal cipher. There are two reasons for doing this:
  • While configured with a transitional cipher, the server will not restart if work is waiting to be resumed.
  • If the server is left configured with a transitional cipher, each time it is restarted the database contents will be re-encrypted using the same key.