Skip to main content
Version: 3.14.x.x LTS

Security modules

nevisProxy relies on the Transport Layer Security (TLS) protocol and the OpenSSL library to secure network connections to client applications and trusted servers. To this end, nevisProxy allows the configuration of public key certificates and private keys for both frontend and backend connections. There are two kinds of supported 'sources' for cryptographic material:

  • File-based certificates and private keys (sometimes called 'soft tokens');
  • Certificates and private keys stored in a Hardware Security Module (HSM, sometimes called 'hard token'), which supports the PKCS#11 specifications or provides an OpenSSL engine to integrate with the Apache HTTP server ('httpd').

If you use a Hardware Security Module (HSM), take into account the following points:

  • nevisProxy provides a standard integration mechanism based on the PKCS#11 protocol or OpenSSL engines.
    • If the HSM is compatible with PKCS#11, OpenSSL accesses it through the Cryptoki library provided by the HSM vendor. The HSM-based certificates and private keys are configured using a PKCS#11 object specification string, as described below.
    • If the HSM vendor provides an OpenSSL engine, OpenSSL uses this engine to interact with the HSM. The HSM-based certificates and private keys are configured as specified in the vendor documentation.
  • To integrate your HSM, follow the integration guides from the HSM vendor. The relevant sections are the ones covering the integration with Apache HTTP server (httpd) and mod_ssl (using engines). The following chapters show example setups for the HSMs we tested, as well as the nevisProxy-specific integration steps.
  • If integration does not work as expected, contact the HSM vendor to address any configuration or migration questions. If the problem lies with nevisProxy, you can also create a nevisProxy support request for further investigation. But only do this after verifying the issue with the HSM vendor.
info

We officially support the HSMs from Securosys and Gemalto, with the configurations as described below. For these officially supported HSMs, we periodically verify the integration and correct functionality.

  • Securosys (PKCS#11): PrimusAPI_PKCS11-1.7.32 (see chapter Securosys support;
  • Gemalto (OpenSSL engine): GemEngine 1.4 (see chapter Gemalto GemEngine support.

The rest of this chapter provides information on the integration of nevisProxy with a PKCS#11-compatible HSM.

PKCS#11 object specification strings​

When interacting with a PKCS#11-compatible HSM, nevisProxy references its content with a PKCS#11 object specification string.

note

The PKCS#11 object specification strings are similar but not identical to the corresponding PKCS#11 URLs defined in RFC-5712.

A configuration for HSM-based certificates within the navajo.xml file using the SSLCertificateKeyFile attribute may look like this:

pkcs11:library=/opt/nevisproxy/lib/libctreinitwrap.so.1&dologin=true&keep=false&cache=false&tokenlabel=daytona&objectlabel=Server

Nevis Cryptoki Wrapper Library​

Some PKCS#11 vendor libraries are not thread-safe. To avoid problems caused by threading and forking, we recommend using the Nevis Cryptoki Wrapper Library.

The Nevis Cryptoki Wrapper Library is configured using environment variables. You configure these variables within the nevisProxy instance's env.conf file.

The following example defines the vendor's PKCS#11 library as well as several options to enable fault tolerance:

PKCS11_LIBRARY=/usr/lunasa/lib/libCryptoki2_64.so
export PKCS11_LIBRARY
PKCS11_SAVESESSION=true
export PKCS11_SAVESESSION
PKCS11_REINIT=true
export PKCS11_REINIT
PKCS11_FORCE_INITIALISATION=true
export PKCS11_FORCE_INITIALISATION
PKCS11_RETRY_AUTO_RECOVERY=true
export PKCS11_RETRY_AUTO_RECOVERY

When using the above configuration string in an XML-based configuration in Appendix E.