Install and configure OpenSSL Provider

This section covers installing the OpenSSL pkcs11 provider, activating it against the CryptoHub PKCS #11 module (libcryptohub-pkcs11.so), and wiring your environment so an OpenSSL 3.x consumer can reference a CryptoHub-stored key by a pkcs11: URI. OpenSSL 3.x uses providers rather than the legacy ENGINE interface, so this integration uses Latchset pkcs11-provider 1.2.0 rather than the older libp11/libengine-pkcs11-openssl ENGINE. Install the provider separately; it is not shipped inside the CryptoHub endpoint download.

Install the OpenSSL pkcs11 provider

Ubuntu/Debian

In a terminal, install the provider package:

sudo apt update
sudo apt install pkcs11-provider

Red Hat/CentOS/Rocky

In a terminal, install the provider package:
sudo dnf install pkcs11-provider
Confirm the location of the installed OpenSSL provider module (pkcs11.so) so you can reference it in the next step:
find / -name "pkcs11.so" -path "*ossl-modules*" 2>/dev/null
The typical location on Ubuntu/Debian is /usr/lib/x86_64-linux-gnu/ossl-modules/pkcs11.so.

Confirm that your package supplies version 1.2.0. If it supplies an older release or does not package pkcs11-provider, build the v1.2.0 tag from Latchset’s source repository with meson and ninja. Note where pkcs11.so is installed; that path is the module value in the OpenSSL configuration below.

Create a dedicated OpenSSL provider configuration file

Create a dedicated OpenSSL configuration file for your application rather than editing the system-wide openssl.cnf. This activates the pkcs11 provider and points pkcs11-module-path at the CryptoHub module installed with the CryptoHub Client Library.

Create /etc/<product>/openssl-cryptohub.cnf with the following contents. Adjust module to the location of the provider module (pkcs11.so) from the install step, and pkcs11-module-path to the location of libcryptohub-pkcs11.so (the endpoint download provides this module; place it where the loader can reach it, such as /usr/local/lib/libcryptohub-pkcs11.so):
openssl_conf = openssl_init [openssl_init] providers = provider_section [provider_section] default = default_sect pkcs11 = pkcs11_sect [default_sect] activate = 1 [pkcs11_sect] module = /usr/lib/x86_64-linux-gnu/ossl-modules/pkcs11.so pkcs11-module-path = /usr/local/lib/libcryptohub-pkcs11.so pkcs11-module-token-pin = file:/etc/<product>/chlibs-pin.txt pkcs11-module-quirks = no-deinit activate = 1
Provider version: distribution packages differ. The pkcs11-module-token-pin = file: directive works with the 0.x and 1.x providers. A 1.x provider built from source also supports a pin-source file attribute in individual URIs. Token PIN: a non-interactive provider consumer must supply the module login PIN. With a UserPass endpoint, the PIN is the endpoint password from cryptohub.json. Store it in a file readable by the application service group:
umask 027 printf '%s\n' '<endpoint-password>' | sudo tee /etc/<product>/chlibs-pin.txt >/dev/null sudo chown root:<service-group> /etc/<product>/chlibs-pin.txt sudo chmod 640 /etc/<product>/chlibs-pin.txt
Replace <product> and <service-group> with the application directory and service group. Do not place a pin-value in the provider configuration or on a command line.
Never add the pkcs11 provider to the system-wide openssl.cnf. Loading the PKCS #11 module into every OpenSSL consumer on the host can break unrelated system services. Always select a dedicated configuration file per-service through OPENSSL_CONF, as shown below.

Select the provider configuration for your application

Set OPENSSL_CONF and CHLIBS_CONFIG in the environment of the process that loads the module, not merely an interactive shell. For a systemd-managed service, use a drop-in:

Create the drop-in directory and file (substitute your application’s systemd unit name):

sudo mkdir -p /etc/systemd/system/<product>.service.d
sudo nano /etc/systemd/system/<product>.service.d/cryptohub.conf

Add the following. This sets OPENSSL_CONF to the provider configuration and CHLIBS_CONFIG to the deployed cryptohub.json:
[Service] Environment=OPENSSL_CONF=/etc/<product>/openssl-cryptohub.cnf Environment=CHLIBS_CONFIG=/etc/cryptohub.json WorkingDirectory=/etc
The library resolves relative TLS authority paths in cryptohub.json against the process working directory. Set WorkingDirectory to the directory containing the CA files, or use absolute authority paths.
Reload systemd so the drop-in takes effect:
sudo systemctl daemon-reload

For an interactive shell instead (for example, while running the verification commands in the next section), export both variables directly:

export OPENSSL_CONF=/etc/<product>/openssl-cryptohub.cnf
export CHLIBS_CONFIG=/etc/cryptohub.json

Note: Supply the module PIN exactly once through pkcs11-module-token-pin = file:. Keep the pkcs11: URI free of pin-value; with a 1.x provider, pin-source is an alternative to the configuration directive, not an additional PIN source.

Confirm the provider loads

openssl list -providers

The pkcs11 provider should appear as active in the output. If it is missing, re-check module and pkcs11-module-path in openssl-cryptohub.cnf.