This is the documentation for Cloudera Enterprise 5.8.x. Documentation for other versions is available at Cloudera Documentation.

Integrating Key HSM with Key Trustee Server

Warning:

When configuring Key Trustee Server to use Key HSM, if there are existing keys stored in Key Trustee Server, you are prompted to migrate the keys to your Hardware Security Module (HSM). Cloudera recommends scheduling a maintenance window for this operation, as the keys are unavailable until the migration is complete.

If any existing key names use special characters other than hyphen (-), period (.), or underscore (_), or begin with non-alphanumeric characters, the migration fails. To avoid this, decrypt any data using the affected key names, and re-encrypt it using a new key name without special characters.

Before proceeding, configure Key HSM to trust the Key Trustee Server certificate. On the Key HSM host (which should also be the Key Trustee Server host, as described in Installing Cloudera Navigator Key HSM), run the following command:

$ sudo keyhsm trust /path/to/key_trustee_server/cert

To configure Key Trustee Server to integrate with Key HSM:

Make sure that the Key HSM service is running. Run the following command on the Key HSM host:
```
$ sudo service keyhsm start
```
On the Key Trustee Server, run the following command:
```
$ sudo ktadmin keyhsm --server https://keyhsm01.example.com:9090 --trust
```
If the Key Trustee Server private key is password-protected, add the --passphrase argument. This prompts you to enter the password for the private key.
Restart the Key Trustee Server service:
- Using Cloudera Manager: Key Trustee Server service > Actions > Restart
- Using the command line:
```
$ sudo service keytrusteed restart      ## RHEL 6-compatible
$ sudo systemctl restart keytrusteed    ## RHEL 7-compatible
```
Verify connectivity between Key HSM and the HSM. Run the following command on the Key Trustee Server host:
```
$ curl -k https://keytrustee01.example.com:11371/test_hsm
```
If Key HSM operations to the HSM are successful, the command returns output similar to the following:
```
"Sample Key TEST_HELLO_DEPOSIT2016-06-03-072718 has been created"
```
See Verifying Key HSM Connectivity to HSM for more information.

Note: Connections using SSL versions 1 through 3 and connections from untrusted clients are immediately terminated to prevent POODLE vulnerability exploits.

If you replace the Key Trustee Server certificate, you must update the Key Trustee Server and Key HSM configuration as follows:

Run the keyhsm trust command, using the path to the new certificate:
```
$ sudo keyhsm trust /path/to/new/key_trustee_server/cert
```

Run the ktadmin keyhsm command, using the --client-certfile and --client-keyfile options to specify the location of the new certificate file and private key:

$ sudo ktadmin keyhsm --server https://keyhsm01.example.com:9090 --client-certfile /path/to/new/key_trustee_server/cert --client-keyfile /path/to/new/key_trustee_server/private_key

Page generated July 8, 2016.