Configuration

OpenSSL

To use the PKCS#11 engine, you must configure OpenSSL to recognize and load the engine, and you must configure the engine to recognize and load the Primus PKCS#11 Provider. Both of these steps are done via an OpenSSL config file.

When OpenSSL is invoked, you have three options to provide a config file:

1. Global default openssl.cnf file. This works best.
2. CLI argument (-config openssl.cnf). However, this is not supported by all OpenSSL subcommands.
3. Environment variable (export OPENSSL_CONF=/path/to/openssl.cnf).

We recommend to write your settings to a separate primus.cnf file and include/import this file in the global openssl.cnf. This allows you to rely on all of the global defaults, while also keeping your Primus-related settings separate, and avoids polluting the global config.

Find the OpenSSL Configuration Directory

Locate where OpenSSL and its default configuration file is installed:

openssl version -d

OPENSSLDIR: "/etc/pki/tls"

Common values for this directory are:

• Debian/Ubuntu: /usr/lib/ssl
  • However, /usr/lib/ssl/openssl.cnf is a symlink to /etc/ssl/openssl.cnf. Therefore, keep your config files in /etc/ssl.
• RHEL: /etc/pki/tls
• Windows: C:\Program Files\Common Files\SSL

Check that this directory contains the global openssl.cnf:

Linux

ls -la /usr/lib/ssl

Windows

dir "C:\Program Files\Common Files\SSL"

Create the Configuration File

Create a new configuration file primus.cnf in the OpenSSL config directory (for example, /etc/ssl/primus.cnf).

This file should have the following content (see the commented lines for the Windows paths):

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 engine from the
# the package manager, because it placed them into the default directory.
# dynamic_path = /usr/lib/x86_64-linux-gnu/engines-3/pkcs11.so
# dynamic_path = "C:\\Users\\<Username>\\Downloads\\libp11\\pkcs11.dll"

# The path to the Primus PKCS#11 Provider module
MODULE_PATH = /usr/local/primus/lib/libprimusP11.so
# MODULE_PATH = "C:\\Program Files\\Securosys\\Primus P11\\primusP11.dll"

# Your PKCS#11 password
# If this option is not set, you need to use another way to provide it to OpenSSL (for example, via the CLI).
# PIN = <PKCS#11 PIN>

init = 0

See the OpenSSL documentation for an explanation of these fields.

Include the Config File

"Include" (import) this separate config file in the main OpenSSL configuration file openssl.cnf, by appending the following snippet at the end of the openssl.cnf. Adjust the paths appropriately, using the base directory you obtained above.

.include /etc/ssl/primus.cnf

Alternatively, you may also create an shell alias so that you can easily invoked OpenSSL with a dedicated config file:

alias primusssl='OPENSSL_CONF=/etc/ssl/primus.cnf openssl'

Test the engine integration

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

$ openssl list -engines

Engines:
dynamic
pkcs11

To verify that the PKCS#11 engine is operating correctly, you can run the following OpenSSL command:

openssl engine pkcs11 -t

If the engine is functioning as expected, OpenSSL will output the following message:

(pkcs11) pkcs11 engine
     [ available ]

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

openssl pkey -engine pkcs11 -inform engine -in "pkcs11:token=${P11_TOKEN};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