Setting up Luna 7 HSM for KTS and Key HSM

How to integrate Ranger KMS, KTS, and KeyHSM with with the Luna 7 HSM appliance supplied by SafeNet.

The task described in this procdural section guides you through setting up the Luna 7 hardware security moudule (HSM) supplied by SafeNet, for use with Ranger components supplied by Cloudera. The process inlcudes setting up Luna 7 HSM on a client (host), intalling KeyHSM and using Luna 7 HSM to validate keys.

You must:
  • Acquire the Luna 7 HSM from SafeNet.
  • Have both Ranger Key Management System and Key Trustee Server installed in your environment.
  • Get KeyHSM software.

See related topics for more information about installing Ranger KMS and KTS to store keys.

Set Up the Luna 7 Client
  1. SSH to (active or passive) KTS node.
    alternatives --install /usr/bin/java java /usr/java/jdk1.8.0_232-cloudera/bin/java 1
  2. Untar the Luna 7 client.
    tar -xvf safenet-linux-64bit-client-7.3.2.tar
    the LunaClient_7.3.0-x_Linux/ folder gets created.
  3. Navigate to the Luna client folder.
    cd LunaClient_7.3.0-x_Linux/64/
  4. In the Luna clent folder, install Luna products and components.
    1. At the (y/n) prompt, choose y.

      If you select no or n, this product will not be installed.

    2. At the Products prompt, choose Luna products to be installed:
      • [1]: Luna Network HSM
      • [2]: Luna PCIe HSM
      • [3]: Luna USB HSM
      • [4]: Luna Backup HSM
      • [N|n]: Next
      • [Q|q]: Quit
      Enter selection: 1, then enter selection n.
    3. At the Components prompt, choose Luna Components to be installed
      • [1]: Luna SDK
      • [2]: Luna JSP (Java)
      • [3]: Luna JCProv (Java)
      • [B|b]: Back to Products selection
      • [I|i]: Install
      • [Q|q]: Quit
      Enter selection: i, then enter selection Q.
      Enter selection: 1,2,and 3 then type i.
  5. Register the HSM on this client.
    1. Retrieve the HSM's public key:
      $ scp .
    2. Register the HSM on the client machine.
      $ /usr/safenet/lunaclient/bin/vtl addServer -n -c server.pem
    3. Confirm the HSM has been added.
      $ /usr/safenet/lunaclient/bin/vtl list
    you should see the following:


    new server <> successfully added to server list

  6. Create client certificate.
    $ /usr/safenet/lunaclient/bin/vtl createCert -n $(hostname -f)
    where  $(hostname -f) is the ip address if running on a virtual machine.
  7. Send the client's public key created in the previous step to the HSM.
    $ scp /usr/safenet/lunaclient/cert/client/$(hostname -f).pem
    $ scp /usr/safenet/lunaclient/cert/client/$(hostname -f).pem
  8. Register the client on the HSM.
    1. SSH to the HSM.
      $ ssh
    2. Register the client with a friendly name on the HSM.
      lunaclient> client register -client <> -h <hostname.from.step 5.a>
      [luna-2] lunash:> client register -client -h
    3. Assign a partition to the client.
      lunaclient> client assignpartition -client <friendly name> -partition par1
      [luna-2] lunash:>client assignpartition -client -partition par1
    [luna-2] lunash:> client register -client -h
    'client register successful.
    Command result : 0 (Success)
    luna-2] lunash:>client assignpartition -client -partition par1
    'client assignPartition successful.
    Command result : 0 (Success)
  9. Verify registration on the client.
    $ /usr/safenet/lunaclient/bin/vtl verify
    root@dsranktkmslunahsm-4 /usr/safenet/lunaclient/bin/vtl verify                 
    The following Luna SA Slots/Partitions were found:
    Slot        Serial #         Label
    ====        =============    ===========
      0             462309014          par1
Install and Configure HSM
  1. SSH to active/passive KTS node.
  2. Obtain Key HSM software.
  3. Install Key HSM software.
    # rpm -ivh keytrustee-keyhsm-*.rpm           
  4. Move the Key Trustee Server and Key HSM installation directory.
    cd /usr/share/keytrustee-server-keyhsm/
    usermod -G keytrustee,hsmusers keyhsm                
  5. Configure Key HSM to use SafeNet Luna client.
    1. Run # keyhsm setup luna
      # keyhsm setup luna
    2. Use the hostname and any port above 1024 )
      The recommended port is 9090.
    3. Provide data about the HSM slot.
    # service keyhsm setup luna
    -- Configuring keyHsm General Setup --
    Please enter keyHsm SSL listener IP address:
    Please enter keyHsm SSL listener PORT number: 9090
    validate Port:                                	:[ Successful ]
    -- Configuring SafeNet Luna HSM --
    Please enter SafeNetHSM Slot Number: 0
    Please enter SafeNet HSM password (input suppressed):
    Configuration stored in: ''. (Note: You can also use service keyHsm settings to quickly view your current configuration)
    Configuration saved in '' file                    
  6. Validate the Key HSM service.
    $ service keyhsm validate
    Check Key HSM is stopped             :[Successful]
    Configuration Available              :[Successful]
    Port available        :[Successful]
    Unlimited-Strength JCE               :[Successful]
    Validate cipher list                 :[Successful]
    HSM availability                     :[Successful]
    All services available:              :[Successful]                         
  7. Start the Key HSM service.
    $ service keyhsm start 
  8. Configure Key HSM to trust KTS.
    $ keyhsm trust /var/lib/keytrustee/.keytrustee/.ssl/ssl-cert-keytrustee.pem
  9. Configure KTS to trust the Key HSM server.
    $ ktadmin keyhsm --server http://$(hostname -f):<port configured in step 14.b> --trust
    $ktadmin keyhsm --server --trust
  10. Restart Key HSM.
    $ service keyhsm restart 
  11. Restart the KTS from Cloudera Manager UI.
  12. Test the HSM.
    curl -k https://$(hostname -f):11371/test_hsm                
  13. Login Ranger UI using keyadmin user role for creating an encryption zone key.

Validating Keys in Luna HSM

  1. Login to Luna HSM machine.
  2. [luna-2] lunash:>partition showContents -par par1
  3. Enter the password for the partition and the Keys will be visible as partition objects.

Ranger KMS is successfully started.

You can now create Encryption zone keys using hadoop command or from Ranger UI using credentials of keyadmin user. Optionally, you can change the default encryption algoritm for KeyHSM and Luna 7.

Configuring encryption algorithms for Luna 7

How to change the default encryption algorithm for KeyHSM and Luna 7.7.

KeyHSM supports configuring the specific encryption algorithm used by the Luna 7.7 HSM. This section describes how to configure which specific encryption algorithm Luna 7 uses, by replacing the KeyHSM default algorithm with one of the optional supported algorithms.

  1. Stop the KeyHSM service.
  2. Navigate to the KeyHSM root directory.
  3. In the KeyHSM root dir, open the file.
  4. Find the hsm.luna.encryption.algorithm property, with default value=RSA/ECB/PKCS1Padding.
  5. Edit the application properties file to replace the default value with one of the following ones:

    Encryption algorithms supported by KeyHSM/Luna 7.7 HSM:

    • RSA/ECB/PKCS1Padding (default)
    • RSA
    • AES_CBC_PKCS5Padding
    Upgrade Scenario:
    1. Unlock the encryption zones with existing keys.
    2. Backup the zone data.
    3. Stop the KeyHSM.
    4. Change the algorithm value as described previously.
    5. Start the KeyHSM.
    6. Create new keys using the new algorithm value.
    7. Lock the encryption zone with new keys.