Configuration

The pkcs11-provider tries to be compatible with a wide range of tokens and offers some parameters to adapt to the different Cryptoki implementations. The full range of configuration options can be found in the provider's HOWTO.md and the manual. In the following the options that are relevant for the Securosys HSM are presented.

For a system wide configuration of the pkcs11-provider edit the openssl.cnf-file in the OPENSSLDIR. You can find OPENSSLDIR location using openssl version -a.

When the HSM should only be used for specific applications one possible option is to create a copy of the file to a destination of your choosing and set the OPENSSL_CONF environment variable so OpenSSL will use the new file. Please consult the OpenSSL documentation if you are looking for other options of using alternative OpenSSL configurations.

The OpenSSL configuration is a ini-like configuration file. The example below is a minimal configuration file.

HOME = .
openssl_conf = openssl_init
config_diagnostics = 1

[openssl_init]
providers = provider_sect
random = random_sect

[random_sect]
random = PKCS11-RAND

[provider_sect]
default = default_sect
base = base_sect
pkcs11 = pkcs11_sect

[base_sect]
activate = 1

[default_sect]
activate = 1

[pkcs11_sect]
module = /usr/local/lib/ossl-modules/pkcs11.so
pkcs11-module-path = /usr/local/primus/lib/libprimusP11.so
#pkcs11-module-token-pin = file://$ENV::OSSL_PKCS11_PIN_FILE
pkcs11-module-load-behavior = early
pkcs11-module-quirks = no-deinit no-operation-state
activate = 1

PKCS11-RAND

Enabling the PKCS11-RAND to use the HSM as source for randomness is optional. It is disabled in the configuration obtained by following the quick-start guide.

Important

The base-provider and default-provider need to be enabled explicitly. Otherwise the encoding function as well as the majority of algorithms implemented by OpenSSL will not be accessible.

pkcs11-provider options

The actual configuration of th provider is placed in [pkcs11_sect]. It needs to be listed in the [provider_sect].

The module and the pkcs11-module-path options are mandatory. They have to point to the installed pkcs11.so-file and the libprimusP11.so-file you installed when setting up the HSM's PKCS#11 interface.

The pkcs11-module-token-pin can be used to point to a file containing the PKCS#11 PIN. When multiple tokens are accessible, the PIN for the specific token should be provided in the pkcs11-uri.

The pkcs11-module-load-behavior can be used to change the behavior on the application start. By setting it to early, the pkcs11-provider gets a list of supported operations when it is loaded. Without this option, the connection to the HSM is only established when requested. The early load behavior is needed when working with the OpenSSL on the command line.

The pkcs11-module-quirks are used to inform the pkcs11-provider about certain properties of the token that might be considered unusual.

• The option no-deinit prevents the de-initialization of the Primus pkcs11-provider. As part of the exit routine the OpenSSL command line interface tries to do a clean up. However, the deallocation on exit is done in reverse order of allocation, which means that the C++ objects in the Primus pkcs11 provider are already freed. Applications that call OPENSSL_cleanup before the exiting do not need that flag. Applications that re-load the OpenSSL library should not use this flag to avoid memory leaks.
• The HSM does not support getting and setting the operation state. Thus, the context cannot be duplicated during digest and sign operations. By setting no-operation-state, the duplication is not performed.