Configuring OpenSSLv3 pkcs11-provider
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.
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 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.