Cloudera Enterprise 5.15.x | Other versions

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. Check Existing Key Names (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

Check Existing Key Names

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

  Warning: Migration fails if any existing keys do not adhere to the constraints.
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.
  Important: Keys are not available during migration, so you should perform these tasks during a maintenance window.

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
  Note: The system requires TLS and Kerberos authentication throughout the system for security reasons. Connections attempted over SSL (1 through 3) and connections from untrusted clients are immediately terminated to prevent POODLE (Padding Oracle On Downgraded Legacy Encyryption) exploits. See the Cloudera Security Bulletin for more information.

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
      Note: The preceding commands also create a certificate file for the Key HSM that is used by the Key Trustee Server. This certificate file is stored in /var/lib/keytrustee/.keytrustee/.ssl/ssl-cert-keyhsm.pem.
  3. Restart 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
  4. Verify connectivity between the Key HSM service and the HSM: 
    $ curl -k https://keytrustee01.example.com:11371/test_hsm
      Important: You must perform the connection verification between Key HSM and the HSM for all Key Trustee Server hosts.
    Successful connection and test of operations returns output like the following: 
    "Sample Key TEST_HELLO_DEPOSIT2016-06-03-072718 has been created"
      Note: If you are using the test_hsm script to verify that the Key Hardware Security Module (Key HSM) has successfully integrated with the Key Trustee Server, or to verify that the Key HSM is connected to HSM, and the Key Trustee Server private key file is password-protected, then the verification may fail. This can occur even if the integration is successful or connected.

    If this occurs, then create a key through Hadoop for the test.

    See Verifying Key HSM Connectivity to HSM for more information about the validation process.
Page generated May 18, 2018.