Integrating Key HSM with Key Trustee Server

Using a hardware security module with Navigator Key Trustee Server requires Key HSM. This service functions as a driver to support interactions between Navigator Key Trustee Server and the hardware security module, and it must be installed on the same host system as Key Trustee Server. The steps below assume that both Key HSM and Key Trustee Server are set up and running. See Installing Cloudera Navigator Key HSM for details. Integrating Key HSM and Key Trustee Server involves the following steps:
  1. Prepare Existing Keys for Migration (for existing Key Trustee Server users only)
  2. Establish Trust from Key HSM to Key Trustee Server
  3. Integrate Key HSM and Key Trustee Server

Prepare Existing Keys for Migration

During the process detailed below, you are prompted to migrate any existing keys from the Key Trustee Server to the HSM.

Successful migration depends on the existing keys conforming to the following constraints:
  • Key names can begin with alpha-numeric characters only
  • Key names can include only these special characters:
    • Hyphen -
    • Period .
    • Underscore _
If any existing key names in Key Trustee Server do not meet the requirements listed above, the migration fails. To prepare for migration, check your key names and do the following if any of them are non-conforming:
  • Decrypt any data using the non-conforming key
  • Create a new key, named per the requirements
  • Re-encrypt the data using the new key
After this, the migration from Key Trustee Server to the HSM will succeed during the process below.

Establish Trust from Key HSM to Key Trustee Server

This step assumes that Key Trustee Server has a certificate for TLS (wire) encryption as detailed in Managing Key Trustee Server Certificates. Before you can run the commands in the steps below, Key HSM service must explicitly trust the Key Trustee Server certificate (presented during TLS handshake). To establish this trust, run the following command: 
$ sudo keyhsm trust /path/to/key_trustee_server/cert
The /path/to/key_trustee_server/cert in this command (and in the commands below) depends on whether the Key Trustee Server uses the default certificate (created by default during install), or uses a custom certificate (obtained from a commercial or internal CA). The two alternate paths are shown in the table below. The custom path is a common example but may differ from that shown.
Default Custom
/var/lib/keytrustee/.keytrustee/.ssl/ssl-cert-keytrustee.pem /etc/pki/cloudera/certs/cert-file.crt
/var/lib/keytrustee/.keytrustee/.ssl/ssl-cert-keytrustee-pk.pem /etc/pki/cloudera/private/private-key.key

Integrate Key HSM and Key Trustee Server

The steps below assume that both Key HSM and the Key Trustee Server are on the same host system, as detailed in Installing Cloudera Navigator Key HSM. These steps invoke commands on the Key HSM service and the Key Trustee Server, and they must be run on the host—they cannot be run remotely from another host.

  1. Ensure the Key HSM service is running: 
    $ sudo service keyhsm start
  2. Establish trust from Key Trustee Server to Key HSM specifying the path to the private key and certificate (Key Trustee Server is a client to Key HSM). This example shows how to use the --client-certfile and --client-keyfile options to specify the path to non-default certificate and key: 
    $ sudo ktadmin keyhsm --server https://keyhsm01.example.com:9090 \
--client-certfile  /etc/pki/cloudera/certs/mycert.crt \
--client-keyfile /etc/pki/cloudera/certs/mykey.key --trust
    For a password-protected Key Trustee Server private key, add the --passphrase argument to the command and enter the password when prompted: 
    $ sudo ktadmin keyhsm --passphrase \
--server https://keyhsm01.example.com:9090 \
--client-certfile  /etc/pki/cloudera/certs/mycert.crt \
--client-keyfile /etc/pki/cloudera/certs/mykey.key --trust
  3. Any keys that exist on the Key Trustee Server are automatically migrated when you run the ktadmin keyhsm command. To complete the migration, enter y or yes at the command prompt: 
    Some deposits were found that will need to be moved to the HSM.

        Note that although this operation can be interrupted, once complete,
        items stored in the HSM must remain there!

Do you want to perform this migration now? [y/N]: y
Migrating hsm deposits...

Migration Complete!
  4. Restart the Key Trustee Server:
    • Using Cloudera Manager: Restart the Key Trustee Server service (Key Trustee Server service > Actions > Restart).
    • Using the Command Line: Restart the Key Trustee Server daemon:
      • RHEL 6-compatible: $ sudo service keytrusteed restart
      • RHEL 7-compatible: $ sudo systemctl restart keytrusteed
  5. Verify connectivity between the Key HSM service and the HSM: 
    $ curl -k https://keytrustee01.example.com:11371/test_hsm
    Successful connection and test of operations returns output like the following: 
    "Sample Key TEST_HELLO_DEPOSIT2016-06-03-072718 has been created"
    See Verifying Key HSM Connectivity to HSM for more information about the validation process.