Luna HSM Keys

CORE supports the following crypto elements of Luna version 7.4

• Key types - RSA, EC, AES.
• Algorithms - GCM, PSSprobabilistic signature scheme. Abbreviation of RSASSA-PSS, OAEPOptimal Asymmetric Encryption Padding - A padding scheme often used together with RSA encryption of symmetric keys., PKCS1, ECB, CBC.
• Digest - SHA1, SHA256, SHA384, SHA512.
• Operations - DECRYPT, SIGN.

Key lifecycle:

• Generate, Enable, Disable, Delete.

Note
CORE uses a unique GUID to set the id attribute of the generated Luna key.
For example,
External ID value of a key in CORE is GUID a85c9214-54f9-4f63-9588-d8b002201af0.
In Luna's key attributes, it appears as an ASCII string of hex values of the GUID:
id=61383563393231342d353466392d346636332d393538382d643862303032323031616630


• Link, relink, and unlink.
• Rotation.

HSM-Connect Quickstart

Preparation of Luna Client

Before installing the Luna client, you must first have an account with Thales and then create a new HSM on Demand service.

Warning
When creating the service, you must check Remove FIPSFederal Information Processing Standards - standards developed by the United States federal government for use in computer systems by non-military government agencies and government contractors restrictions in the Configure Service step. This cannot be changed after creating the service and is needed for CORE to interact correctly with Luna.

Prepare the Luna client on a server that will host the HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing Connect service:

1. Follow the procedure in Install Service Client to generate and obtain an installation package for the Luna client.
2. Install the client:
   1. Prepare the installation directory:

   sudo mkdir -p --mode 507 /usr/local/keystore/luna

   2. Upload the obtained file to /usr/local/keystore/luna and untar it.
   3. In the folder, select cvclient-min.tar and untar it.

   The folder will show the following structure:

   

   4. Run commands in setenv to update the Chrystoki.conf file:

   source ./setenv
   

   5. Create environmental variables that are required by the luna-hsm-connect:

   export PATH=$PATH:/usr/local/keystore/luna/bin/64
   export CONFIG_PATH=/usr/local/keystore/luna
   export CONFIG_FILE=Chrystoki.conf
   export ChrystokiConfigurationPath=/usr/local/keystore/luna
   

3. Prepare a partition on HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing and obtain credentials of the HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing partition's Crypto Officer.
   Enter the lunacm utility and perform the following commands:
1. Initialize the partition (we will name it unbound) and credentials of the partition's officer (PO):

lunacm:> partition init -label unbound -password Unbound1! -force

2. Log in as the partition officer, create the partition's crypto officer (CO) with a temporary password, and log out:

lunacm:> role login -name po -p Unbound1!
lunacm:> role init -name crypto officer -p TempPassword1!
lunacm:> role logout


3. Log in as CO and change the temporary password

lunacm:> role login -name co -p TempPassword1!
lunacm:> role changepw -name crypto officer -old TempPassword1! -new Password1!

Note
The assigned password will be used in the CORE's configuration of the HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing keystore.

This server is now ready for installation of the HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing-Connect. But before that, in the CORE, we will generate mTLS artifacts that the HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing-Connect will use to authenticate the CORE and be authenticated by the CORE.

Preparations on CORE

Registration of an luna-hsm-connect service on CORE resembles the registration of a FULL client.

In the selected partition, using UI:

1. Create external keystore:

UI  ˃ Partition SOSecurity officer - UKC partition administrator role. ˃ Keystores ˃ Create
→ The New Keystore dialog appears.

1. Name - <keystore name>
2. Description - optional.
3. Deploy as an external service - YES.
4. Sync Policy - NONE (default).
5. Credentials:
   • Secret key - mandatory. Use the Luna CO user's permanent password (Password1!) specified in step 3.c of Preparation of Luna Client
6. Click Save.
2. Register the server that will host the HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing Connect by following the steps in Register HSM Connect Agent.

Note
In this Quickstart, we assume that the registration specified port 8888 to be used by the luna-hsm-connect service to receive the CORE requests.

By the completion of these steps, we produced the following:

• mTLS artifacts for the secure connection to CORE :
1. The P12 file with the private key and certificate to be used by the HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing Connect.
   For example, <keystore name>_ks_client.p12 and its password (Password1!).
2. JKSA Java KeyStore (JKS) is a repository of security certificates – either authorization certificates or public key certificates – plus corresponding private keys, used for instance in SSL encryption. file that contains CORE CA Certificate to authenticate the CORE.
   For example, root_ca.jks and its password 123456.
• The TCP/IP port 8888 that the HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing Connect should be receiving the CORE request.

HSM Connect Installation

On the server where we installed and tested the Luna client:

1. Upload the certificates created in Preparations on CORE to /usr/local/keystore:

<keystore name>_ks_client.p12 ------->  /usr/local/keystore/luna/keystore.p12
root_ca.jks ------------------------->  /usr/local/keystore/root_ca.ks

2. Install HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing Connect:
   1. Create folder that will host the installation:

   sudo mkdir /opt/ekm

   2. Obtain hsm-connect-<version>.tar.gz and untar it in this folder:

   tar xvf hsm-connect-<version>.tar.gz

3. Prepare the service
   
   1. Edit and modify the /usr/local/keystore/luna/luna-hsm-connect.conf as follows: 

   SERVER_PORT=<8888>
   PATH_OF_SETENV=/usr/local/keystore/luna/setenv
   PATH_OF_HSM_CONNECT_JAR=/opt/ekm/hsm-connect.jar
   SSL_PATH_OF_KEYSTORE_P12=/usr/local/keystore/luna/keystore.p12
   SSL_KEYSTORE_PASSWORD=<keystore password>
   SSL_PATH_OF_ROOT_CA_KS=/usr/local/keystore/root_ca.ks
   SSL_TRUST_STORE_PASSWORD=<123456>
   SSL_CLIENT_AUTH=need
   PATH_OF_LOG4J2_XML=/opt/ekm/log4j2.xml
   HSM_VENDOR_NAME=LUNA
   PATH_OF_HSM_VENDOR_SO=/usr/local/keystore/luna/libs/64/libCryptoki2.so
   HSM_PROTECTION_MODE=module

   2. Copy luna-hsm-connect.service to /etc/systemd/system/luna-hsm-connect.service.
   3. Add luna-hsm-connect to services that are started on boot.

   sudo systemctl -q enable luna-hsm-connect

   4. Reload the services and start luna-hsm-connect.

   sudo systemctl daemon-reload
   sudo systemctl start luna-hsm-connect
   

Maintenance

Use systemctl commands to check status, stop, start and restart the luna-hsm-connect service

systemctl <status | stop | start | kill> luna-hsm-connect

Notes
1. luna-hsm-connect is configured to restart once it is killed in the active state. Therefore, instead of restart, use kill.
2. The stop command hangs for about two minutes. To expedite it, use Ctrl-C followed by kill. Use the status command to make sure that the service has stopped.

The hsm-connect logs are managed in the /var/log/unbound directory. To check the last hour's logs, use

less /var/log/unbound/hsm-connect.log

Troubleshooting

The luna-hsm-connect service has two troubleshooting points:

• output - test Luna client interface.
• input - test processing of requests coming from CORE. This test assumes that the Luna client is operational.

Test HSM Connect output

Use the Luna client commands and utilities to validate this interface. See examples in Preparation of Luna Client.

Note
If you changed the CO password, you must also change it in the CORE keystore configuration for the secret key. See Preparations on CORE.

Test HSM Connect input

1. Make sure the service is running and listening on the expected port:
   1. Make sure the status is active (running), and get the process id (PID)

   sudo systemctl status luna-hsm-connect

   luna-hsm-connect.service - Unbound Security HSM Connect Spring Boot application
   Loaded: loaded ...............
   Active: active (running) since...............
   Main PID: 689 (java)

   2. Use the PID (in this case, 689) to validate that luna-hsm-connect is listening to the expected port (in our configuration, it is port 8888)

   sudo netstat -tulpn | grep 689

   tcp6 0 0 :::8888 :::* LISTEN 689/java

2. Use cURL commands to send requests to the HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing Connect server's end-points. This test validates that HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing Connect is operational and it correctly mediates between the RESTRepresentational State Transfer (REST) - an architectural style that defines a set of constraints and properties based on HTTP. Web Services that conform to the REST architectural style, or RESTful web services, provide interoperability between computer systems on the Internet. API and the HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing Client.

curl -k 'https://<HSM Connect URI>/general/health' \
--header 'Authorization: Basic < base64 value of :<CO password>'

For example:

curl -k 'https://192.168.0.15:8888/general/health' \
--header 'Authorization: Basic MTpQYXNzd29yZDEh'

1. To use cURL, we must change the luna-hsm-connect mTLS specification from mandatory to optional:

   Edit the /usr/local/keystore/luna/luna-hsm-connect.conf file and change the SSL_CLIENT_AUTH setting from "need" to "want":

   SSL_CLIENT_AUTH=want

   Restart the service to apply the modified configuration. Since the service is configured to restart once it is killed while being active, use this option to restart it

   sudo systemctl kill luna-hsm-connect
   

2. To use cURL, provide the authorization that is expected by the luna-hsm-connect:

--header 'Authorization: Basic < base64 value of :<CO password>>'

Note
The ":" prefix is added to the CO password.

To convert :<CO password> to base64, use:

echo -n ':<CO password>' | base64

For example,

echo -n ':Password1!' | base64

MTpQYXNzd29yZDEh

We use this value in the following examples.

3. Check the health

Using any device that has access to the HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing Connect server (for example, EP), run:

curl -k 'https://<HSM Connect IP>:8888/general/health' \
--header 'Authorization: Basic MTpQYXNzd29yZDEh'

This API, in the case of success, returns Code 200 without any additional info. Therefore, in the case of success, you will only get the shell prompt for the next command.

In the case of error (for example, password issues), the cURL will show:

• "Cannot establish HSMHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing Connection. CKR_PIN_INCORRECT" - the password is incorrect.
• "Internal Server Error" - the ":" prefix was missing from a string provided to the base 64 encoder.
4. Similarly, you can check API that provides an output (in JSON format)

curl -k 'https://192.168.0.15:8888/general/capabilities' \
--header 'Authorization: Basic MTpQYXNzd29yZDEh' \
| jq '.'

3. After this test, return the SSLSecure Sockets Layer - a cryptographic protocol that provides communications security over a computer network._CLIENT_AUTH setting to SSLSecure Sockets Layer - a cryptographic protocol that provides communications security over a computer network._CLIENT_AUTH=need.
   1. Follow the steps in #2.a.
   2. To confirm that the mandatory mTLS requirement has been restored, run the cURL health command. Make sure it returns an error, as shown below.

   curl -k 'https://<HSM Connect IP>:8888/general/health' \
   --header 'Authorization: Basic MTpQYXNzd29yZDEh'

   curl: (58) NSS: client certificate not found (nickname not specified)