Skip to main content

Configuring the OpenSSL PKCS#11 Provider

To use the OpenSSL pkcs11-provider, you must configure OpenSSL to recognize and load the provider, and you must configure the provider to recognize and load the Primus PKCS#11 Provider. Both of these steps are done via an OpenSSL config file.

When OpenSSL is invoked, you have three options to provide a config file:

  1. Global default openssl.cnf file. This works best.
  2. CLI argument (-config openssl.cnf). However, this is not supported by all OpenSSL subcommands.
  3. Environment variable (export OPENSSL_CONF=/path/to/openssl.cnf).

We recommend to write your settings to a separate primus.cnf file and include/import this file in the global openssl.cnf. This allows you to rely on all of the global defaults, while also keeping your Primus-related settings separate, and avoids polluting the global config.

Find the OpenSSL Configuration Directory​

Locate where OpenSSL and its default configuration file is installed:

openssl version -d
OPENSSLDIR: "/etc/pki/tls"

Common values for this directory are:

  • Debian/Ubuntu: /usr/lib/ssl
    • However, /usr/lib/ssl/openssl.cnf is a symlink to /etc/ssl/openssl.cnf. Therefore, keep your config files in /etc/ssl.
  • RHEL: /etc/pki/tls
  • Windows: C:\Program Files\Common Files\SSL

Check that this directory contains the global openssl.cnf:

ls -la /usr/lib/ssl

Create the Configuration File​

Create a new configuration file primus.cnf in the OpenSSL config directory (for example, /etc/ssl/primus.cnf).

This file should have the following content:

HOME = .
openssl_conf = openssl_init
config_diagnostics = 1

[openssl_init]
providers = provider_sect
# random = random_sect

# Use the HSM as a source of randomness
# Warning: this can have unexpected side-effects. Only enable if required.
# [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/lib/x86_64-linux-gnu/ossl-modules/pkcs11.so
pkcs11-module-path = /usr/local/primus/lib/libprimusP11.so
# pkcs11-module-token-pin = PRIMUSDEV
pkcs11-module-encode-provider-uri-to-pem = true
pkcs11-module-load-behavior = early
pkcs11-module-quirks = no-deinit no-operation-state
activate = 1
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 configuration of the OpenSSL pkcs11-provider is placed in [pkcs11_sect]. Additionally, the pkcs11_sect section 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. You can leave this empty, and instead specify it in the application calling OpenSSL in the PKCS#11 URI.

  • pkcs11-module-encode-provider-uri-to-pem = true is used to register a PEM encoder for private keys. It encodes private keys in PEM files that contain a PKCS#11 URI referencing the key. The PEM files use the non-standard PKCS#11 PROVIDER URI header/trailer. This encoder is necessary for non-extractable keys, as otherwise OpenSSL will fail to export such keys (for example, during openssl genpkey). It is also necessary for legacy applications that require keys to be passed as PEM files instead of as PKCS#11 URIs.

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

The full range of configuration options can be found in the provider's HOWTO.md and its man page.

Include the Config File​

"Include" (import) this separate config file in the main OpenSSL configuration file openssl.cnf, by appending the following snippet at the end of the openssl.cnf. Adjust the paths appropriately, using the base directory you obtained above.

.include /etc/ssl/primus.cnf

Test the Provider Integration​

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

You can use the OpenSSL storeutl command to show a public key stored on your partition:

openssl storeutl "pkcs11:token=${PARTITION_NAME};type=public;object=${KEY_LABEL}"

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?