Upgrading Cloudera Navigator Key HSM

Setting Up an Internal Repository

You must create an internal repository to install or upgrade Cloudera Navigator Key HSM. For instructions on creating internal repositories (including Cloudera Manager, CDH, and Cloudera Navigator encryption components), see Configuring a Local Package Repository.

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 6.x, use the instructions in Upgrading Key HSM (Major Version Upgrades); do not use the procedure documented in this section.

  1. Install the Cloudera Repository

    Add the internal repository you created. See Configuring Hosts to Use the Internal Repository for more information.

    Import the GPG key by running the following command: 
    sudo rpm --import http://repo.example.com/path/to/RPM-GPG-KEY-cloudera
  2. Install the CDH Repository

    Key Trustee Server and Key HSM depend on the bigtop-utils package, which is included in the CDH repository. For instructions on adding the CDH repository, see Configuring a Local Package Repository.

  3. Stop the Key HSM Service
    Stop the Key HSM service before upgrading: 
    sudo service keyhsm shutdown
  4. 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.

  5. Start the Key HSM Service
    Start the Key HSM service: 
    sudo service keyhsm start

Upgrading Key HSM (Major Version Upgrades)

  1. Install the Cloudera Repository

    Add the internal repository you created. See Configuring Hosts to Use the Internal Repository for more information.

    Import the GPG key by running the following command: 
    sudo rpm --import http://repo.example.com/path/to/RPM-GPG-KEY-cloudera
  2. Install the CDH Repository

    Key Trustee Server and Key HSM depend on the bigtop-utils package, which is included in the CDH repository. For instructions on adding the CDH repository, see Configuring a Local Package Repository.

  3. Stop the Key HSM Service
    Stop the Key HSM service before upgrading: 
    sudo service keyhsm shutdown
  4. 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.

  5. Rename Previously-Created Configuration Files

    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
  6. 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.

  7. 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 Establish Trust from Key HSM to Key Trustee Server.

  8. Start the Key HSM Service
    Start the Key HSM service: 
    sudo service keyhsm start
  9. 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 Integrate Key HSM and Key Trustee Server.

  10. 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