Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.futurex.com/llms.txt

Use this file to discover all available pages before exploring further.

This section describes how to install and configure pkcs11-provider from Latchset for the OpenSSL library. The following list provides an overview of pkcs11-provider library:
LibraryDescription
pkcs11-providerAn OpenSSL 3.x cryptographic provider that enables access to cryptographic tokens—such as smart cards and Hardware Security Modules (HSMs)—through the standard PKCS#11 API. It acts as a bridge between OpenSSL’s provider-based architecture and any PKCS#11-compliant module.

​
Install pkcs11-provider

Instructions for installing pkcs11-provider depend on the Linux version being used. Perform the following instructions to install pkcs11-provider on the supported operating systems:

​
Ubuntu or Debian

Perform the following steps to install pkcs11-provider on Ubuntu 24.04 or Debian 13:
While aptcan install the minimum required version (v0.3) of pkcs11-provider, it’s recommended to compile it from source to ensure you’re using the latest version. This helps avoid compatibility issues and ensures access to the most recent features and bug fixes.
1
Install Prerequisites
Shell
sudo apt update
sudo apt install git build-essential meson libssl-dev pkg-config
2
Build and change directories into a /src directory (recommended to keep source builds organized)
Shell
mkdir -p ~/src
cd ~/src
3
Clone the pkcs11-provider repository
Shell
git clone https://github.com/latchset/pkcs11-provider.git
cd pkcs11-provider
4
Build with Meson
Shell
meson build
ninja -C build
5
Install the provider
Shell
sudo ninja -C build install
When this command is finished, take note of where the pkcs11.so file was installed. The path will be needed for the openssl.cnf file later.

​
Red Hat or CentOS

In a terminal, run the following sequence of commands to install pkcs11-provider on Red Hat or CentOS:
1
Install Prerequisites
Shell
sudo dnf check-update
sudo dnf install -y git gcc gcc-c++ meson ninja-build pkgconfig openssl-devel
If the system does not support dnf, use yuminstead.
2
Change into a /usr/local/src directory (recommended to keep source builds organized)
Shell
cd /usr/local/src
3
Clone the Repository
Shell
git clone https://github.com/latchset/pkcs11-provider.git
cd pkcs11-provider
4
Build with Meson
Shell
meson build
ninja -C build
5
Install the provider
Shell
sudo ninja -C build install
When this command is finished, take note of where the pkcs11.so file was installed. On Red Hat and CentOS-based systems, the default install path is /usr/lib64/ossl-modules/pkcs11.so. The path will be needed for the openssl.cnf file later.
The pkcs11-tool command for listing tokens may not function correctly on Rocky Linux 9 with pkcs11-provider. This is a known limitation and does not affect BIND functionality. Token verification works as expected on Rocky Linux 10.

​
Edit the OpenSSL configuration file

Perform the following steps to edit the OpenSSL configuration file for Ubuntu or Debian-based Linux distributions and Red Hat or CentOS-based distributions:
1
Run the following command to determine the location of the global OpenSSL configuration file for the logged-in user:
Shell
openssl version -d
2
If editing the global OpenSSL configuration file is preferred, skip to the next step.Copy the openssl.cnf file and move it to a preferred directory.
Shell
cp /path/to/openssl.cnf /custom/directory/path/openssl.cnf
3
Open the openssl.cnf file in a text editor.
If editing the global OpenSSL configuration file, open openssl.cnf in a text editor with root privileges.
4
Add the following line at the top of the file, before any sections, if it is not already present:
None
openssl_conf = openssl_init
5
Add the following text, based on your operating system, at the bottom of the file after modifying the module and pkcs11-module-path:
None
[openssl_init]
providers = provider_init

[provider_init]
default = default_init
pkcs11 = pkcs11_init

[default_init]
activate = 1

[pkcs11_init]
module = /path/to/pkcs11-provider/pkcs11.so
pkcs11-module-path = /usr/local/lib/fxpkcs11/libfxpkcs11.so
activate = 1
If you need automatic logging to the token, specify the PIN by adding the following line:pkcs11-module-token-pin = file:/path/to/filewithpin.txtThe file referenced should contain just the PIN.
6
Export the environment variable if not editing the global OpenSSL configuration file.
Shell
export OPENSSL_CONF=/path/to/openssl.cnf
7
Test if OpenSSL successfully loaded the provider.
Shell
openssl list -providers
If successful, both default and pkcs11 should be listed under providers.