Skip to main content
Version: 2.202308.x.x RR

SafeNet Luna SA hardware security module

The nevisAppliance supports the SafeNet Luna SA network's hardware security module (HSM) for key storage. Perform the following steps to register an appliance to an HSM.

This example uses the following variables/host names:

  • $appliance: the host name of the nevisAppliance, same as: hostname –s.
  • $lunahsm: the host name of the HSM server.
  • $slot: the name of the partition to use.
  1. Import the server key to the appliance:

    # scp admin@${lunahsm}:server.pem /usr/lunasa/cert/server/
    # /usr/lunasa/bin/vtl5 addServer -n $lunahsm -c /usr/lunasa/cert/server/server.pem
  2. Create a client certificate for secure communication to the HSM server (use the appropriate state (-s), localization (-l) and organization (-o) name of your company):

    # /usr/safenet/lunaclient/bin/vtl createCert -n "$(hostname -s)" -c CH -s Zurich \
    -l Zurich -o SIVEN -P "/usr/lunasa/cert/client/$(hostname -s)Key.pem" \
    -C "/usr/lunasa/cert/client/$(hostname -s).pem"

    The configuration is written to /etc/Chrystoki.conf and the key material is stored in the /usr/lunasa/cert/ directory.

  3. Copy the client certificate to the HSM:

    # scp "/usr/lunasa/cert/client/$(hostname -s).pem" admin@$lunahsm:
  4. Log in to the HSM, register the client and assign the partition:

    # ssh -l admin $lunahsm
    :> client register -client $appliance -hostname $appliance
    :> client assignPartition -client $appliance -partition $slot
    :> exit
  5. Check the configuration:

    # /usr/lunasa/bin/vtl5 verify

    The HSM is now ready to be used by the nevisAppliance.

Example key generation

You can create new RSA keys on the HSM by using the openssl binary.

Example
# /opt/nevisproxy/bin/openssl pkcs11 genkey -bits 2048 -label ${appliance} -library \
/usr/lib/libCryptoki2_5_64.so -login -tokenlabel $slot -type 3

Example certificate request generation

You can create a certificate request by using the private key, which has been generated as described in the chapter Example key generation, by using the openssl command line tool.

Example
# /opt/nevisproxy/bin/openssl req -new \
-config /var/opt/neviskeybox/default/public/openssl.cnf \
-out /var/tmp/${appliance}_req.pem -key \
"pkcs11:library=/usr/lib/libCryptoki2_5_64.so&dologin=true&keep=true&cache=true&
tokenlabel=$slot&objectlabel=$appliance&suppressvaliditycheck=true"

Certificate installation

When receiving the signed certificate you should import it into a new slot within the nevisKeybox instance. It is required to import both the CA certificate and the server certificate. These files are referred within the navajo.xml file by the SSLCertificateFile (server certificate) and the SSLCertificateChainFile (CA certificate chain) attributes.

We recommend you use the same name for this slot as you used within "tokenlabel" (the $slot variable). Within the same slot, you also have to create a keypass file called "hsm_keypass", which returns the partition secret. This secret is required by nevisProxy during unattended restarts (e.g., during a server reboot).

Example files (keypass, SSLCertificateChainFile and SSLCertificateFile)
/var/opt/neviskeybox/default/slot/hsm_keypass
/var/opt/neviskeybox/default/slot/node_certificate.pem
/var/opt/neviskeybox/default/slot/truststore.pem

Example nevisProxy configuration

You can configure the HSM keys within the navajo.xml file as shown in the example below.

SSLCertificateKeyFile="pkcs11:library=/usr/lib/libCryptoki2_5_64.so&dologin=true&
keep=false&cache=false&tokenlabel=slot&objectlabel=appliance&suppressvaliditycheck=true"

nevisProxy provides the "Nevis cryptoki wrapper library" and it is usually a good practice to use this library instead of directly loading the vendor's library. See the nevisProxy reference guide chapter "Security Modules" for more information.