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

Securosys support

This chapter describes how to integrate a Securosys Primus HSM or CloudHSM using the PrimusAPI_PKCS11 library version 2.2.x.

It has also been successfully tested with version 2.4.0.
All 2.3.x versions below 2.3.9 may work with the following limitations:

  • it can only be used with the OpenSSL provider (chapter 4a)
  • the ErrorLog, TransferLog and CustomLog in navajo.xml may not start with a |.

With CloudHSM we recommend due to higher latency to increase the 'keep alive' timeout to at least ten seconds. This may avoid too many cryptographic calls to the HSM. For this, set the KeepAliveTimeout parameter in the navajo.xml configuration file to at least "10". See also the performance measures in chapter Performance measurements for the cloud-based Securosys HSM.

Setup the Securosys HSM or CloudHSM​

Step 1: HSM Configuration requirements​

Following HSM configuration is required, performed by the HSM administrator (SO role):

  • PKCS#11 API needs to be enabled on that partition.
  • PKCS#11 Password must be defined.
  • Enable Session Objects (CKA_TOKEN = False).
  • For security reasons disable Key import, Key export and Key extract.
  • Disable Key invalidation.
  • Check for valid network routing (and firewall rules) for the new client application access.
  • Generate a new setup password for onboarding the Nevis application.
  • The connection details (IP address, TCP port).

Step 2: Setup and configure the Primus library​

  • Read in the vendor's documentation on how to install and configure the Securosys PKCS#11 library.
  • For easier usage, put the environment exports into ~/.bashrc.
    export PRIMUS_HOME=/usr/local/primus
    export PATH=$PRIMUS_HOME/bin:$PATH
    export LD_LIBRARY_PATH=$PRIMUS_HOME/lib:$LD_LIBRARY_PATH
  • Verify that the connection test with the command ppin -t is successful.
  • Contact the vendor in case of problems during this setup.

Step 3: Create the key material​

To create and import the key material you have to install the following libraries:

  • PKCS#11 Provider (API), see Step 2
  • OpenSC/pkcs11-tool from the OpenSC package of your operating system (if not already installed)
note

It is important to use the same HSM API for the generation, import and usage of objects (keys, certificates), as different APIs may support different metadata.

For key material management examples (key generation, CSR, certificate import) consult https://docs.securosys.com/openssl/ossl-legacy/Tutorial/openssl_cli.

Once the above tools are installed, proceed as follows (adapt the commands to your needs):

Create a key pair in the HSM using pkcs11-tool:​

pkcs11-tool --module /usr/local/primus/lib/libprimusP11.so --slot 0 -l -p <the passphrase> --keypairgen --key-type RSA:4096 --id <the id> --label <the label>  --usage-sign --sensitive

Create a certificate signing request (CSR) using OpenSSL:​

OPENSSL_CONF=/usr/local/primus/conf/openssl.cnf /opt/nevisproxy/bin/openssl req -provider pkcs11 -new -key "pkcs11:token=<the token>;object=<the label>;pin-value=<the passphrase>;type=private" -subj "/C=CH/ST=Zurich/L=Zurich/O=Nevis/CN=CloudHSM" -out securosys_req.pem

Sign the cert request using your Certification Authority or OpenSSL:​

/opt/nevisproxy/bin/openssl ca -batch -days 365 -keyfile <the ca keyfile>  -cert <the ca keyfile>  -outdir . -in securosys_req.pem -out securosys_cert.pem

Convert the PEM file to DER:​

OPENSSL_CONF=/usr/local/primus/conf/openssl.cnf /opt/nevisproxy/bin/openssl x509 -outform DER -in securosys_cert.pem -out securosys_cert.der

Import the certificate into the HSM:​

pkcs11-tool --module /usr/local/primus/lib/libprimusP11.so --slot=0 --login --pin <the passphrase> --write-object securosys_cert.der --type cert --label <the label>

Step 4: Configure navajo.xml​

The final step is to adjust the file navajo.xml. There are two ways to configure navajo.xml. The recommended way is to use the OpenSSL provider library. The other way is to use the OpenSSL engine library which may work as long as OpenSSL doesn't end the engine support.

Step 4a: Configure navajo.xml using the OpenSSL provider​

In the env.conf file you have to define the environment variable OPENSSL_CONF which point to the openssl.cnf provided in Step 2.

OPENSSL_CONF=/usr/local/primus/conf/openssl.cnf
export OPENSSL_CONF

To adjust the file navajo.xml proceed as follows:

  • In the SSL tag of the file navajo.xml, configure the parameters SSLCertificateFile and SSLCertificateKeyFile as follows:

    SSLCertificateFile="pkcs11:object=<the label of the certificate>;type=cert"
    SSLCertificateKeyFile="pkcs11:object=<the label of the key>;type=private?pin-value=<the pin>"

  • You can now restart the proxy.

Step 4b: Configure navajo.xml using the OpenSSL engine​

This setup is currently only working for PrimusAPI_PKCS11 library version 2.2.x and lower or 2.3.9 and higher.

To adjust the file navajo.xml proceed as follows:

  • In the SSL tag of the file navajo.xml, configure the parameters SSLCertificateFile and SSLCertificateKeyFile as follows:

    SSLCertificateFile="pkcs11:library=/usr/local/primus/lib/libprimusP11.so&dologin=true&objectlabel=<the label>&type=cert&pinenv=PKCS11_PIN&cache=false"
    SSLCertificateKeyFile="pkcs11:library=/usr/local/primus/lib/libprimusP11.so&dologin=true&objectlabel=<the label>&type=privkey&pinenv=PKCS11_PIN&cache=false"

  • In the Server tag of the file navajo.xml, configure the parameter SSLCryptoDevice as follows:

SSLCryptoDevice="pkcs11"

  • Add the following code block to the file env.conf:

    PKCS11_PIN=...
    export PKCS11_PIN

    PKCS11_PIN_ENVIRONMENT_AHEAD=true
    export PKCS11_PIN_ENVIRONMENT_AHEAD

    OPENSSL_ENGINES=/opt/nevisproxy/lib/engines
    export OPENSSL_ENGINES

  • You can now restart the proxy.