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

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.8.6, see chapter Securosys support;
  • Gemalto (OpenSSL engine): GemEngine 1.6, 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.

In order to load the PKCS#11-compatible OpenSSL engine provided by nevisProxy you have to add those lines into the env.conf file:

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

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

PKCS#11 OBJECT SPECIFICATION STRING
     PKCS#11 object specification strings are distinguished from
     PEM files by its 'pkcs11:' protocol prefix.  Following the
     'pkcs11:' protocol prefix are name/value pairs describing
     PKCS#11 library, objects, or object access behavior (caching
     etc).

     Sample:
    
pkcs11:library=./libcryptoki.so&dologin=true&keep=true&cache=true&tokenlabel=one&objectlabel=seven&pinenv=PKCS11_PIN1

     library
         Specify PKCS#11 library.  This may be an absolute
         filename or a relative filename (in which case
         LD_LIBRARY_PATH should be appropriately set).  The
         library filename is typically libcryptoki.so.

     dologin
         Specify login behavior.  Setting it to 'true' forces a
         login into the PKCS#11 token (after opening sessions).
         Some token objects may only be accessible if logged in.
         The tool will try to log into the token anyway, if the
         token indicates 'login-required' thru its information
         flags.

     cache
         This option will reuse token information. Useful if e.g.
         both private key and matching certificate are used.

     keep
         This option will keep PKCS#11 sessions and login states.

     tokenlabel
         Specify label of the token carrying the object in
         question.

     slotnumber
         Is an alternative to tokenlabel.

     objectlabel
         Specify label of the object in question.

     objectid
         Is an alternative to objectlabel.  Note that object ids
         are often not intended to be human readable (e.g. just
         20 random bytes).

     pinenv
         Specify the name of the environment variable that
         contains the pin used to log into the PKCS#11 token. If
         this option is not specified then the environment
         variable that contains the pin is assumed to be
         PKCS11_PIN.

         This option is useful if your objects are distributed on
         several tokens that are protected by different pins.

     pinenvironmentvariable
         Same as option pinenv.

     pinfile
         Specifies the file name containing the PIN used to log in to the PKCS#11 token. Only the first line is read, without the terminating '\n'..

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

When you use the above configuration string in an XML-based configuration (as attribute value), the character & needs to be replaced by &.

To find out the value of the various options, use the PKCS#11 (Cryptoki) interface and utility. See: Appendix E. To test the PKCS#11 OBJECT SPECIFICATION STRING, use the provided libnevisproxypkcs11engine library in combination with the storeutl method of OpenSSL.

Getting a certificate from HSM​

If a certificate is needed out of the HSM, use the provided libnevisproxypkcs11engine library in combination with the storeutl method of OpenSSL. The sample command in the next code block shows you how:

/opt/nevisproxy/bin/openssl storeutl -engine /opt/nevisproxy/lib/libnevisproxypkcs11engine.so -noout -text 'pkcs11:library=/usr/local/primus/lib/libprimusP11.so&dologin=true&objectlabel=proxy.cert&type=cert&pinenv=PKCS11_PIN'

The output of the sample command above is as follows:

 This is a public symbol
 engine "libnevisproxypkcs11engine" set.
 PKCS#11 User PIN for Slot 0 (PRIMUS X-Series):
 0: Certificate
 Certificate:
 Data:
 Version: 3 (0x2)
 Serial Number:
 .....

You can also define one of the following environment variables (usually defined in the file env.conf):

PKCS#11 LIBRARY ENVIRONMENT VARIABLES
     The PKCS#11 library supports the following environment
     variables:

     PKCS11_CACHE_PRIO
         This prioritized environment variable indicates to reuse
         token information.  Useful if e.g. both private key and
         matching certificate are used. This environment variable
         has precedence over the environment variable
         PKCS11_CACHE and over the option 'cache' of the
         corresponding PKCS#11 object specification string.

     PKCS11_CACHE
         Indicates to reuse token information. Useful if e.g.
         both private key and matching certificate are used. This
         environment variable is ignored if either the
         environment variable PKCS11_CACHE_PRIO is set or if the
         option string.

     PKCS11_KEEP_PRIO
         This prioritized environment variable indicates to keep
         PKCS#11 sessions and login states. It has precedence
         over the environment variable PKCS11_KEEP and over the
         option 'keep' of the according PKCS#11 object
         specification string.

     PKCS11_KEEP
         Indicates to keep PKCS#11 sessions and login states.
         This environment variable is ignored if either the
         environment variable PKCS11_KEEP_PRIO is set or if the
         option 'keep' is set in the corresponding PKCS#11 object
         specification string.

     PKCS11_PIN
         Specifies a default pin used to log into the PKCS#11
         token. Used in combination with the environment variable
         PKCS11_PIN_ENVIRONMENT_AHEAD and/or the environment
         variable PKCS11_PIN_ENVIRONMENT.

         By specifying the option pinenv in your PKCS#11 object
         specification string and assigning an environment
         variable name to it you can override this default pin by
         another pin.

         This is useful if your objects are distributed on
         several tokens that are protected by different pins.

     PKCS11_PIN_ENVIRONMENT
         Specifies whether to check if a (single) pin is provided
         in the environment variable PKCS11_PIN (or in the
         environment variable specified by the option pinenv in
         the according PKCS#11 specification string). This check
         is only done if the environment variable
         PKCS11_PIN_ENVIRONMENT_AHEAD is not set and if the
         according pin getter failed. It is of use in the cases
         where the process has disconnected from its controlling
         terminal and /dev/tty is no longer valid.

     PKCS11_PIN_ENVIRONMENT_AHEAD
         Specifies whether to check if a (single) pin is provided
         in the environment variable PKCS11_PIN (or in the
         environment variable specified by the option pinenv in
         the according PKCS#11 specification string). This check
         is done before the according pin getter is called. It is
         of use in the cases where the process has disconnected
         from its controlling terminal and /dev/tty is no longer
         valid. Besides it may be of use to suppress the
         multiplicity of pin prompts.

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 (see: Appendix F).

Last updated on