Skip to main content

Configuring PKCS#11 for OpenSSL v3

The OpenSSL PKCS#11 Provider API 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:

  1. Find the OPENSSLDIR location using openssl version -d. On Ubuntu, this is /usr/lib/ssl, but the config files are symlinks to /etc/ssl
  2. Edit the openssl.cnf file in the OPENSSLDIR and append .include /etc/ssl/primus.cnf at the end of file.
  3. Create a primus-specific config file /etc/ssl/primus.cnf. Fill it out like in the example below.

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.

Example config file​

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

On Ubuntu, if you used the distribution-provided package to install pkcs11-provider, the module path is /usr/lib/x86_64-linux-gnu/ossl-modules/pkcs11.so.

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 the provider is placed in [pkcs11_sect]. It needs to be listed in the [provider_sect].

  • 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.

  • 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 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.

  • 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.

Verify​

The PKCS#11 provider should now be listed:

openssl list -providers
Providers:
  default
    name: OpenSSL Default Provider
    version: 3.0.13
    status: active
  pkcs11
    name: PKCS#11 Provider
    version: 3.0.13
    status: active

For more details on how to debug configuration issues, see the Troubleshooting page.

More resources​

Get started withCloudHSM for free.
Other questions?Ask Sales.
Feedback
Need help?