NGINX

Configure Luna HSM

Set up NGINX

Ensure that the HSM is set up, initialized, provisioned, and ready for deployment. For more information, refer to Luna HSM documentation.

Create a partition that will be later on used by NGINX.

Create and exchange certificate between the Luna Network HSM and client system. Register client and assign partition to create an NTLS connection.

Initialize Crypto Officer and Crypto User roles for the registered partition.

Run the following command to verify that the partition has been successfully registered and configured:

/usr/safenet/lunaclient/bin/lunacm 

Upon successful execution, you should observe an output similar to the example provided below:

lunacm (64-bit) v10.5.1-174. Copyright (c) 2022 Thales Group. All rights reserved. 
Available HSMs:
Slot Id ->                           0
Label ->                             TPA01
Serial Number ->                     1312109862206
Model ->                             LunaSA 7.7.1
Firmware Version ->                  7.7.1
Bootloader Version  ->               1.1.2
Configuration ->                     Luna User Partition With SO (PW) Key Export With Cloning Mode
Slot Description ->                  Net Token Slot
FM HW Status ->                      Non-FM
Current Slot Id:                     0

Refer to Luna HSM documentation for detailed steps on creating NTLS connection, initializing the partitions, and assigning various user roles.

For proper configuration of a PED-based Luna HSM, it is recommended to activate partition policies 22 and 23, allowing for both activation and auto-activation.

Open the configuration file for your Luna HSM.

Look for the [Misc] section within the configuration file.

Add or modify the following setting within the [Misc] section:

RSAKeyGenMechRemap=1

This setting instructs the Luna HSM to redirect older key generation mechanisms to the newly approved mechanism when the HSM is operating in FIPS mode.

Ensure that you possess sudo privileges on the client workstation.

Add a user to the hsmusers group using the command:

sudo gpasswd --add <username> hsmusers

Replace username with the actual username you want to include in the hsmusers group.

Confirm that you hold sudo privileges on the client workstation.

Eliminate a user from the hsmusers group using the command:

sudo gpasswd --add <username> hsmusers

Replace username with the specific username you want to exclude from the hsmusers group. To observe the changes, you will need to log in again.

Any user you remove will retain access to the HSM device until the client workstation is rebooted.

Transfer the downloaded .zip file to your client workstation using pscp, scp, or other secure means

This integration has been certified on the RHEL platform.

Extract the .zip file into a directory on your client workstation.

Extract or untar the appropriate client package for your operating system. Do not extract to a new subdirectory; place the files in the client install directory.

tar -xvf cvclient-min.tar

Run the setenv script to create a new configuration file containing information required by the Luna Cloud HSM service.

source ./setenv

To add the configuration to an already installed UC client, use the –addcloudhsm option when running the setenv script.

Run the LunaCM utility and verify that the Cloud HSM service is listed.

If your organization requires non-FIPS algorithms for your operations, ensure that the Allow non-FIPS approved algorithms check box is checked. For more information, refer to Supported Mechanisms.

Log on to the NGINX server as a root user or another user with administrative privileges.

Download and extract the OpenSSL toolkit from the Thales support portal. Navigate to the directory where Gem Engine is extracted to locate the gembuild utility. For example:

cd /home/gemengine-x.x

Here, x.x represents the Gem Engine version.

NGINX relies on OpenSSL for SSL/TLS support. OpenSSL includes a component called ENGINE for storing keys on hardware devices. Thales provides the Gem Engine toolkit with ENGINE support to communicate with the Luna HSM. The toolkit can be downloaded from the Thales Support Portal. It is recommended to familiarize yourself with OpenSSL by referring to its documentation at OpenSSL Documentation.

Locate the OpenSSL Engines Directory using the gembuild command:

./gembuild locate-engines

Copy the libgem.so or gem.so to the engines directory displayed in the previous command, depending on your OpenSSL version. For example:

cp builds/linux/rhel/64/x.x.x/gem.so <OpenSSL engines directory path>

Here, x.x.x represents your OpenSSL version.

You can also build and install Gem Engine, SAUTIL, and OpenSSL using the Gem Engine Toolkit downloaded from the Thales Portal. Refer to the README files provided with the Toolkit for detailed instructions.

Verify that Gem Engine is present and supported by OpenSSL:

openssl engine gem -v

Create a file with the partition CO password. This file is needed by Gem Engine to log on to the Luna partition:

echo CO_Password > /tmp/passfile

Update the /etc/Chrystoki.conf file with the following configuration:

GemEngine = {
   LibPath = /usr/safenet/lunaclient/lib/libCryptoki2.so;
   LibPath64 = /usr/safenet/lunaclient/lib/libCryptoki2_64.so;
   EnableDsaGenKeyPair = 1;
   EnableRsaGenKeyPair = 1;
   DisablePublicCrypto = 1;
   EnableRsaSignVerify = 1;
   EnableLoadPubKey = 1;
   EnableLoadPrivKey = 1;
   DisableCheckFinalize = 0;
   DisableEcdsa = 1;
   DisableDsa = 0;
   DisableRand = 0;
   EngineInit = "<myTokenLabel>":0:0:passfile=</path/to/my/passfile>;
   EnableLoginInit = 1;
}

Replace <myTokenLabel> with the partition label and </path/to/my/passfile> with the path to the file containing the partition CO password.

If you prefer not to save the partition's CO password in a file, other methods are available to enable login via Gem Engine. Refer to the README files provided with the Gem Engine Toolkit for detailed instructions.

Ensure that OpenSSL is configured correctly to use Luna HSM with Gem Engine:

openssl engine gem -t

Generate Certificates with OpenSSL

Update NGINX Configuration for SSL

Execute the following command to generate the keys on the Luna HSM and save the certificate request and key reference:

openssl req -engine gem -new -newkey rsa:2048 -nodes -sha256 -keyout server.key -out server.csr

This command generates the public and private keys on the HSM, with the private key reference saved in the server.key file. You'll need this later. The Certificate Signing Request (CSR) is saved in the server.csr file, which needs to be submitted to the CA to obtain a CA-signed certificate.

Run the command cmu list to verify the generated key pair on the Luna HSM:

/usr/safenet/lunaclient/bin/cmu list

Submit the server.csr file to a trusted CA like VeriSign or Entrust. The CA will authenticate the request and provide a signed certificate or a certificate chain. Save the CA-signed certificate in the system directory.

Ensure that you have the key reference (server.key) and the CA-signed certificate (server.pem) ready for NGINX configuration.

Execute the following command to generate keys on the Luna HSM and save the key reference:

openssl genrsa -engine gem -out server.key 2048

The server.key file contains the key reference to the Private Key Generated on the HSM, which you'll need later.

To generate a self-signed certificate for testing purposes, execute the following command:

openssl req -new -engine gem -x509 -key server.key -sha256 -out server.pem

Here, server.pem is the self-signed certificate in PEM format.

Open the NGINX configuration file <NGINX installation directory>/nginx.conf and make the following changes at the end of the http section:

server {
    listen       443 ssl;
    server_name  <Server Hostname or IP Address>;

    ssl_certificate      <Path to the certificate.pem file>;
    ssl_certificate_key  <Path to the private key file >;

    ssl_session_cache    shared:SSL:1m;
    ssl_session_timeout  5m;

    ssl_protocols   TLSv1.3 TLSv1.2;
    ssl_ciphers  HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers  on;

    location / {
        root   html;
        index  index.html index.htm;
    }
}

(a) Replace <Server Hostname or IP Address>, <Path to the certificate.pem file>, and <Path to the private key file> with the actual values in your environment.
(b) ssl_certificate points to the SSL certificate, which can be either self-signed or signed by a CA.
(c) ssl_certificate_key indicates the location of the private key generated on the HSM, formatted in PEM.
(d) To utilize TLSv1.3, ensure you have OpenSSL v1.1.1 or newer installed.

Open the NGINX configuration file <NGINX installation directory>/nginx.conf and add the following line before the beginning of the http section:

ssl_engine gem;

Run the following command under the <NGINX installation directory>/bin/ to ensure there are no errors due to the configuration changes in the nginx.conf file:

./nginx -t

Restart the NGINX server to apply the configuration changes.

Open any web browser and access the NGINX server. Verify the SSL certificate to ensure it's functioning correctly.

Follow the steps outlined in the Configure OpenSSL to enable GemEngine section.

Identify the directory where your current SSL private key and certificate are stored.

Use the following command to extract the public key from your existing private key:

openssl rsa -in server.key -pubout -out pubkey.pem

Execute the following command to convert your private key to PKCS#8 format:

openssl pkcs8 -in server.key -topk8 -nocrypt -out privatekey.pem

Use the CMU utility provided with the Luna Client to import the public and private keys into the Luna HSM.

For the public key:

/usr/safenet/lunaclient/bin/cmu import -inputFile pubkey.pem -label nginx_public_key -pubkey=rsa

For the private key:

/usr/safenet/lunaclient/bin/cmu importkey -PKCS8 -in privatekey.pem -keyalg RSA

Ensure that the keys are generated on the Luna HSM partition and note the private key handle by running:

/usr/safenet/lunaclient/bin/cmu list

You should see output similar to:

   Certificate Management Utility (64-bit) v10.1.0-32. Copyright (c) 2019 SafeNet. All rights reserved.
   Please enter password for token in slot 0 : ********
   handle=37       label=CMU Unwrapped RSA Private Key
   handle=36       label=nginx_public_key

Use the following command to set a label for the private key:

/usr/safenet/lunaclient/bin/cmu setattribute -handle=37 -label=nginx_private_key

Confirm that the private key label is set correctly and matches the public key label by running:

/usr/safenet/lunaclient/bin/cmu list

The output should look like:

   Certificate Management Utility (64-bit) v10.3.0-140. Copyright (c) 2020 SafeNet. All rights reserved.
   Please enter password for token in slot 0 : ********
   handle=37       label=nginx_private_key
   handle=36       label=nginx_public_key

Copy the SAUTIL utility provided with the OpenSSL toolkit to create the private key reference:

cp /home/gemengine-1.2/builds/linux/rhel/64/1.0.2/sautil /usr/bin/

Run the SAUTIL utility to create a private key reference for the key imported to the Luna HSM:

sautil -v -s 0 -i 0:0 -a 0:RSA -f HSMKey_ref.pem -o -q -c

Provide the HSM partition CO password and key handle when prompted. After successful execution, HSMKey_ref.pem will be generated. This file needs to be specified in the SSL configuration in the nginx.conf file.

Remove the private key generated by OpenSSL and the PKCS#8 format key:

rm -rf /usr/local/nginx/server.key /usr/local/nginx/privatekey.pem

Edit the nginx.conf file to update the ssl_certificate_key location with the HSM key reference generated in step 10. The updated server block should look like this:

    server {
        listen       443 ssl;
        server_name  <Server Hostname or IP Address>;

        ssl_certificate      /usr/local/nginx/server.pem;
        ssl_certificate_key  /usr/local/nginx/HSMKey_ref.pem;

        ssl_session_cache    shared:SSL:1m;
        ssl_session_timeout  5m;

        ssl_protocols   TLSv1.2 TLSv1.3;
        ssl_ciphers  HIGH:!aNULL:!MD5;
        ssl_prefer_server_ciphers  on;

        location / {
            root   html;
            index  index.html index.htm;
        }
    }

TLSv1.3 support is available in OpenSSL v1.1.1 onwards. Older OpenSSL versions do not support TLSv1.3.

Replace the server_name, ssl_certificate, and ssl_certificate_key values with the actual values for your environment:

(a)ssl_certificate is the self-signed or CA-signed certificate in PEM format.
(b) ssl_certificate_key is the location of the reference key pointing to the private key imported on Luna HSM.

Open the NGINX configuration file <NGINX installation directory>/nginx.conf and add the following line before the beginning of the http section:

ssl_engine gem;

Restart the NGINX server to apply the configuration changes.

Open any browser and access the NGINX server. Verify that the server is accessible and is using the private key migrated to the HSM.