Configuration

OpenSSL

To use another engine, OpenSSL requires engine settings in the openssl.cnf file. Some OpenSSL commands allow specifying a dedicated configuration file (-config myssl.cnf) and some do not. Setting the environment variable OPENSSL_CONF is a workaround, but sometimes the default openssl.cnf file contains entries that are needed by some commands (e.g. openssl req).

You may add the engine entries to your default OpenSSL config file or add other requirements for your OpenSSL command into the config file. We suggest that you create a separate config file for interactions with the HSM in order to prevent conflicts with previous settings or defaults.

Locate where OpenSSL and its default configuration file is installed:

openssl version -d

OPENSSLDIR: "/etc/pki/tls"

Create a new configuration file /etc/pki/tls/primusopenssl.cnf with the engine section and other necessary controls:

openssl_conf = openssl_init

[openssl_init]
engines = engine_section

[engine_section]
pkcs11 = pkcs11_section

[pkcs11_section]
engine_id = pkcs11
# dynamic_path is not required if you have installed
# the appropriate pkcs11 engines to your openssl directory
# dynamic_path = /usr/local/primus/lib/libprimusP11.so
MODULE_PATH = /usr/local/primus/lib/libprimusP11.so
# Insert your PKCS11 password, otherwise interactively or command line option
PIN = <PKCS#11 PIN>
# it is not recommended to use "debug" for production use
# INIT_ARGS = connector=http://127.0.0.1:12345 debug
init = 0 

Include above file in /etc/pki/tls/openssl.cnf, the main OpenSSL configuration file:

# Note that you can include other files from the main configuration
# file using the .include directive.
.include /etc/pki/tls/primusopenssl.cnf

Alternatively, you may also create an alias to use a dedicated config file:

alias primusssl='OPENSSL_CONF=/etc/pki/tls/myprimusopenssl.cnf openssl'

At this point the pkcs11 engine should be recognized by OpenSSL:

openssl list -engines

To verify that the configuration was successful, you can try exporting an existing public key:

openssl pkey -engine pkcs11 -inform engine \
	-in "pkcs11:type=public;object=${P11_LABEL}" -pubin

For more commands, see the tutorial.

Apache/httpd

note

The httpd mod_ssl module leverages OpenSSL for TLS connections. OpenSSL needs to be configured.

Add at the end of the main httpd configuration file /etc/httpd/conf/httpd.conf the following lines:

<IfModule ssl_module>
 SSLRandomSeed startup builtin
 SSLRandomSeed connect builtin
</IfModule>

Adapt the mod_ssl configuration file /etc/httpd/conf.d/ssl.conf

SSLPassPhraseDialog builtin

And reference the used Certificate and Private Key within the VirtualHost section using the object (=label) reference:

SSLCertificateFile "pkcs11:token=<partition-name>;object=myrsakey;type=cert"
SSLCertificateKeyFile "pkcs11: token=<partition-name>;object=myrsakey;type=private"

nginx

note

Nginx uses OpenSSL for cryptographic operations. OpenSSL needs to be configured.

Nginx currently supports only loading private keys from an HSM, and a certificate must be provided separately as a regular file. Modify the nginx configuration file /etc/nginx/nginx.conf by activating TLS and referencing the used Certificate as regular file and Private Key within the server section using the object (=label) reference:

ssl_certificate "/path/to/cert.pem"
ssl_certificate_key "engine:pkcs11:pkcs11:token=<partition-name>;pin-value=<PKCS#11 PIN>;object=myrsakey;type=private

HSM Key Reference

HSM objects are referenced in general according RFC7512 URI scheme. Currently only the following URI specifier and forms are supported:

Attribute	Description
token=<token label>	Token Label (partition name)
serial=<serial number>	Serial Number of the partition
object=<object label>	Key Label
id=<key id>	Key ID, note that pkcs11-tool writes the key id in hexadecimal notation to the HSM (e.g. %10%01)
type=<cert|public|private>	Key type
pin-value=<PKCS#11 PIN>	to pass the PKCS11 PIN via command line