Upgrading Cloudera Navigator Key HSM

Learn how to upgrade Navigator Key HSM.

Setting Up an Internal Repository

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.

Upgrading Key HSM (Minor and Patch Version Upgrades)

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

Upgrading Key HSM (Major Version Upgrades)

  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

Key Trustee Server SSL Certificate Regeneration

When Key HSM is upgraded to CDP 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