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