Upgrading Cloudera Navigator Key HSM

Although it is possible to upgrade Cloudera Navigator KeyHSM by using the KeyHSM RPM package directly, Cloudera recommends setting up a YUM package repository to perform the upgrade.

The steps given below assume that a repository containing the KeyHSM RPM package downloaded from the paywall has been created. For more information on creating such a repository, see https://wiki.centos.org/HowTos/CreateLocalRepos.

If you are upgrading from Key HSM 1.x (shipped with CDH 5.x and earlier) to Key HSM 7.x, use the instructions in Upgrading Key HSM (Major Version Upgrades); do not use the procedure documented in this section.

1. Install the KeyHSM Repository

   Add the internal repository that you created.

2. Stop the Key HSM Service
   Stop the Key HSM service before upgrading:

   sudo service keyhsm shutdown
   

3. Upgrade Navigator Key HSM
   Upgrade the Navigator Key HSM package using yum:

   sudo yum update keytrustee-keyhsm
   

   Cloudera Navigator Key HSM is installed to the /usr/share/keytrustee-server-keyhsm directory by default.

4. Start the Key HSM Service
   Start the Key HSM service:

   sudo service keyhsm start
   

1. Install the KeyHSM Repository

   Add the internal repository that you created.

2. Stop the Key HSM Service
   Stop the Key HSM service before upgrading:

   sudo service keyhsm shutdown
   

3. Upgrade Navigator Key HSM
   Upgrade the Navigator Key HSM package using yum:

   sudo yum update keytrustee-keyhsm
   

   Cloudera Navigator Key HSM is installed to the /usr/share/keytrustee-server-keyhsm directory by default.

4. Rename Configuration Files that were created earlier

   For Key HSM major version upgrades, previously-created configuration files do not authenticate with the HSM and Key Trustee Server, so you must recreate these files by re-executing the setup and trust commands. First, navigate to the Key HSM installation directory and rename the applications.properties, keystore, and truststore files:

   cd /usr/share/keytrustee-server-keyhsm/
   mv application.properties application.properties.bak
   mv keystore keystore.bak
   mv truststore truststore.bak
   

5. Initialize Key HSM
   Run the service keyhsm setup command in conjunction with the name of the target HSM distribution:

   sudo service keyhsm setup [keysecure|thales|luna]
   

   For more details, see Initializing Navigator Key HSM.

6. Establish Trust Between Key HSM and the Key Trustee Server
   The 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
   

   For more details, see Integrating Key HSM with Key Trustee Server.

7. Start the Key HSM Service
   Start the Key HSM service:

   sudo service keyhsm start
   

8. Establish Trust Between Key Trustee Server and Key HSM
   Establish trust between the Key Trustee Server and the Key HSM by specifying the path to the private key and certificate:

   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 (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
   

   For additional details, see Integrating Key HSM with Key Trustee Server.

9. Remove Configuration Files From Previous Installation
   After completing the upgrade, remove the saved configuration files from the previous installation:

   cd /usr/share/keytrustee-server-keyhsm/
   rm application.properties.bak
   rm keystore.bak
   rm truststore.bak
   

When Key HSM is upgraded to Cloudera version 7.1.4 or above, the SSL certificates of the Key Trustee Server (KTS) might need to be regenerated if the self-signed certificates that are created by the ktadmin command are being used.

Perform the following steps to regenerate the KTS SSL certificate:

1. Stop the KTS service from Cloudera Manager.

2. Navigate to the location /var/lib/keytrustee/.keytrustee/.ssl/ to take a backup of the certificate files ssl-cert-keytrustee-pk.pem and ssl-cert-keytrustee.pem:

   cd /var/lib/keytrustee/.keytrustee/.ssl/
   

3. Backup the certificate files:

   mv ssl-cert-keytrustee-pk.pem ssl-cert-keytrustee-pk_backup.pem
   mv ssl-cert-keytrustee.pem ssl-cert-keytrustee_backup.pem
   
   

4. Regenerate the certificate file:

   ktadmin init
   

5. Configure the Key HSM to trust the new certificate file:

   keyhsm trust /var/lib/keytrustee/.keytrustee/.ssl/ssl-cert-keytrustee.pem
   

6. Restart the Key HSM service.
7. Start the KTS service from Cloudera Manager.
8. Run the following command to test and validate certificate regeneration:

   curl -vk https://$(hostname -f):11371/test_hsm