Configuring PKCS#11 for OpenSSL v3
Securosys HSM Integration Guide
The PKCS#11 API 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 GitHub manual. In the following the options that are relevant for the Securosys HSM are presented.
For a system wide configuration of the PKCS#11 API Provider, edit the openssl.cnf
-file in the OPENSSLDIR
. You can find the OPENSSLDIR
location using openssl version -a
.
To restrict the HSM usage to specific applications, you can create a copy of the configuration file in a chosen location and set the OPENSSL_CONF
environment variable to point to it. This ensures OpenSSL uses the new configuration. For additional ways to customize OpenSSL configurations, please refer to the OpenSSL documentation.
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.
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]
.
-
module
and thepkcs11-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. -
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. -
pkcs11-module-load-behavior
can be used to change the behavior on the application start. By setting it toearly
, 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. Theearly
load behavior is needed when working with the OpenSSL on the command line. -
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 callOPENSSL_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.