Set up Luna 7 HSM for Ranger KMS, KTS, and KeyHSM

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

SSH to (active or passive) KTS node.

alternatives --install /usr/bin/java java /usr/java/jdk1.8.0_232-cloudera/bin/java 1

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.
Navigate to the Luna client folder.
```
cd LunaClient_7.3.0-x_Linux/64/
```
In the Luna clent folder, install Luna products and components.
note
Before the install begins, you must select network HSM and JSP as shown in the example.
```
<LunaHome>/64/install.sh 
```
Example:
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.
Register the HSM on this client.
1. Retrieve the HSM's public key:
```
$ scp admin@luna-2.atx.cloudera.com:server.pem .
```
2. Register the HSM on the client machine.
```
$ /usr/safenet/lunaclient/bin/vtl addServer -n luna-2.atx.cloudera.com -c server.pem
```
3. Confirm the HSM has been added.
```
$ /usr/safenet/lunaclient/bin/vtl list
```
you should see the following:
ls
new server <luna.server.name> successfully added to server list

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.

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 admin@luna-2.atx.cloudera.com.

SSH to the HSM.
```
$ ssh admin@luna-2.atx.cloudera.com
```

lunaclient> client register -client <friendly.name> -h <hostname.from.step 5.a>

[luna-2] lunash:> client register -client dsranktkmslunahsm-4.dsranktkmslunahsm.root.hwx.site -h dsranktkmslunahsm-4.dsranktkmslunahsm.root.hwx.site

Assign a partition to the client.

lunaclient> client assignpartition -client <friendly name> -partition par1

[luna-2] lunash:>client assignpartition -client dsranktkmslunahsm-4.dsranktkmslunahsm.root.hwx.site -partition par1

[luna-2] lunash:> client register -client dsranktkmslunahsm-4.dsranktkmslunahsm.root.hwx.site -h dsranktkmslunahsm-4.dsranktkmslunahsm.root.hwx.site
'client register successful.
Command result : 0 (Success)
luna-2] lunash:>client assignpartition -client dsranktkmslunahsm-4.dsranktkmslunahsm.root.hwx.site -partition par1
'client assignPartition successful.
Command result : 0 (Success)

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

SSH to active/passive KTS node.
Obtain Key HSM software.

Install Key HSM software.

# rpm -ivh keytrustee-keyhsm-*.rpm

Move the Key Trustee Server and Key HSM installation directory.
```
cd /usr/share/keytrustee-server-keyhsm/
```
note
For Luna 7, you must add the keyhsm user to the hsmgroup group to provide that user access to certificates used by the Luna client software.
```
usermod -G keytrustee,hsmusers keyhsm                
```

Configure Key HSM to use SafeNet Luna client.

Run # keyhsm setup luna
```
# keyhsm setup luna
```
Use the hostname and any port above 1024 )
The recommended port is 9090.
Provide data about the HSM slot.

# service keyhsm setup luna
-- Configuring keyHsm General Setup --
Please enter keyHsm SSL listener IP address: oks-hsm.vpc.cloudera.com
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: 'application.properties'. (Note: You can also use service keyHsm settings to quickly view your current configuration)
Configuration saved in 'application.properties' file

Validate the Key HSM service.

$ service keyhsm validate

Check Key HSM is stopped             :[Successful]
Configuration Available              :[Successful]
Port 127.0.0.1:9090 available        :[Successful]
Unlimited-Strength JCE               :[Successful]
Validate cipher list                 :[Successful]
HSM availability                     :[Successful]
All services available:              :[Successful]

Start the Key HSM service.
```
$ service keyhsm start 
```

Configure Key HSM to trust KTS.

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

Configure KTS to trust the Key HSM server.

$ ktadmin keyhsm --server http://$(hostname -f):<port configured in step 14.b> --trust

$ktadmin keyhsm --server http://127.0.0.1:9090 --trust

Restart Key HSM.
```
$ service keyhsm restart 
```
Restart the KTS from Cloudera Manager UI.

Test the HSM.

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

Validating Keys in Luna HSM

Login to Luna HSM machine.
```
ssh admin@luna-2.atx.cloudera.com
```
[luna-2] lunash:>partition showContents -par par1
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.

Stop the KeyHSM service.
Navigate to the KeyHSM root directory.
In the KeyHSM root dir, open the application.properties file.
Find the hsm.luna.encryption.algorithm property, with default value=RSA/ECB/PKCS1Padding.
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
- RSA_ECB_OAEPSHA_224ANDMGF1Padding
- AES_RSA_NONE_OAEPSHA_512ANDMGF1Padding
- AES_CBC_PKCS5Padding
- RSA_NONE_OAEP_WITH_SHA224AndMGF1Padding
- RSA_NONE_OAEP_WITH_SHA256AndMGF1Padding
- RSA_NONE_OAEP_WITH_SHA384AndMGF1Padding
- RSA_NONE_OAEP_WITH_SHA1AndMGF1Padding
Upgrade Scenario:
note
When upgrading KeyHSM from any version < 7.1.7.1 to 7.1.7.1, zone keys and hdfs encryption zone(s) will exist. Do not change the encryption algorithms without first creating new encryption keys, using the following steps:
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.