Skip to main content
Version: 8.2411.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.2 or newer.

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. 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.