Skip to main content

Configuration

p11-kit configuration​

Each configured PKCS#11 module has its own configuration file. Depending on the OS, these configuration files may reside at the following locations:

  • the p11-kit installation folder (modules folder)
  • /etc/pkcs11/ folder (modules folder)
  • .pkcs11/modules folder.

Each user can optionally provide additional configuration or override the system configuration. Note that user configuration files are not loaded from the home directory if running inside a setuid or setgid program

Create the file primus.module for your OS in

RHELUbuntu/Debian
/etc/pkcs11/modules/ or
/usr/share/p11-kit/modules/		/usr/share/p11-kit/modules/

containing the following lines:

# This file describes how to load the primus pkcs11 provider module
# For details see p11-kit and pkcs11.conf 
# and https://p11-glue.github.io/p11-glue/p11-kit/manual/
# This is a relative path, which means it will be loaded from
# the p11-kit default path which is usually $(libdir)/pkcs11.
# Doing it this way allows for packagers to package primus for
# 32-bit and 64-bit and make them parallel installable
module: libprimusP11.so
managed: true
priority: 2
#critical: true
# A comma and/or space separated list of names of programs that this module should only
# be loaded in. The module will not be loaded for other programs using p11-kit. The base
# name of the process executable should be used here, for example seahorse, ssh.
# do not use enable-in and disable-in simultaneously
enable-in: p11-kit, openssl, httpd, nginx
#disable-in:
#remote:
#log-calls: true

Add a symbolic link for libprimusP11.so module in

RHELUbuntu/Debian
/usr/lib64/pkcs11/
/usr/lib64/		/usr/lib/x86_64-linux-gnu/pkcs11/
/usr/lib/x86_64-linux-gnu/

e.g. for RHEL 8:

sudo ln -s /usr/local/primus/lib/libprimusP11.so /usr/lib64/pkcs11/libprimusP11.so
sudo ln -s /usr/local/primus/lib/libprimusP11.so /usr/lib64/libprimusP11.so

Use the following command to check that Primus HSM module is registered:

p11-kit list-modules
primus: libprimusP11.so
    library-description: PKCS#11 Library
    library-manufacturer: Securosys SA
    library-version: 2.1
    token: DEMO-TEST
        manufacturer: Securosys SA
        model: Primus HSM
        serial-number: a1973d4952c5addd
        hardware-version: 2.11
        firmware-version: 2.1
        flags:
               rng
               login-required
               user-pin-initialized
               restore-key-not-needed
               clock-on-token
               token-initialized
p11-kit-trust: p11-kit-trust.so
    library-description: PKCS#11 Kit Trust Module
    library-manufacturer: PKCS#11 Kit
    library-version: 0.23
...
opensc: opensc-pkcs11.so
    library-description: OpenSC smartcard framework
    library-manufacturer: OpenSC Project
    library-version: 0.20
...

Application configuration​

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 be 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 were OpenSSL and it's 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'

The key can be referenced by URI by placing it after the -key option.
E.g: Generating a CSR using the private key "myeckey" on partition "DEMO-TEST" in slot 12:

openssl req -engine pkcs11 -new -key "pkcs11:token=DEMO-TEST;object=myeckey;type=private;pin-value=MYPIN" \
    -keyform engine -out ec.hsm.csr -sha384 -verify

HMS Key Reference​

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

AttributeDescription
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