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.

Install the pkcs11-provider module from Latchset. This module allows OpenSSL 3.x to use PKCS #11 tokens through a provider interface. Follow the steps for your Linux version.

​
Install on Ubuntu or Debian

While apt can 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 the required packages:
Shell
sudo apt update
sudo apt install \
    git build-essential meson libssl-dev pkg-config \
    libnss3 libnss3-dev libnss3-tools \
    p11-kit opensc libp11-kit-dev \
    python3-asn1crypto
2
Create a source directory and change into it:
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 the provider:
Shell
meson setup builddir
meson compile -C builddir
5
Install the provider:
Shell
sudo meson install -C builddir
NoteDuring installation, the pkcs11.so module is copied to the OpenSSL modules directory. You’ll need this path when updating the OpenSSL configuration file.
Example output:
Shell
Installing src/pkcs11.so to /usr/lib/x86_64-linux-gnu/ossl-modules
In this example, pkcs11.so is installed in /usr/lib/x86_64-linux-gnu/ossl-modules.

​
Install on RHEL

ImportantThis step includes enabling the EPEL and CodeReady Builder (CRB) repositories, so ensure you have a valid RHEL subscription.
1
Enable CodeReady Builder (CRB):RHEL 8:
Shell
sudo subscription-manager repos --enable codeready-builder-for-rhel-8-$(arch)-rpms
RHEL 9:
Shell
sudo subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms
Alma and Rocky Linux 8:
Shell
sudo dnf config-manager --set-enabled powertools
Alma and Rocky Linux 9:
Shell
sudo dnf config-manager --set-enabled crb
2
Install the EPEL Release package:
Shell
sudo dnf install epel-release
3
Refresh metadata:
Shell
sudo dnf makecache
4
Install prerequisites:
Shell
sudo dnf check-update
sudo dnf install -y \
    git \
    gcc \
    gcc-c++ \
    meson \
    ninja-build \
    pkgconfig \
    openssl-devel \
    nss-devel \
    p11-kit-devel \
    opensc \
    python3-asn1crypto
5
Change to a source directory:
Shell
cd /usr/local/src
6
Clone the repository:
Shell
git clone https://github.com/latchset/pkcs11-provider.git
cd pkcs11-provider
7
Build the provider:
Shell
meson setup builddir
meson compile -C builddir
8
Install the provider:
Shell
sudo meson install -C builddir
NoteDuring installation, the pkcs11.so module is copied to the OpenSSL modules directory. You’ll need this path when updating the OpenSSL configuration file.
Example output:
Shell
Installing src/pkcs11.so to /usr/lib64/ossl-modules
In this example, pkcs11.so is installed in /usr/lib64/ossl-modules.

​
Configure OpenSSL to load the provider

1
Locate the OpenSSL configuration file. You can verify it using the following command openssl version -d. For instance:
  • For Ubuntu/Debian:
Shell
openssl version -d
OPENSSLDIR: "/usr/lib/ssl"
  • For RHEL:
Shell
openssl version -d
OPENSSLDIR: "/etc/pki/tls"
ImportantThis tutorial assumes openssl.cnf is located in /usr/lib/ssl/. Update the path in the following commands accordingly.
2
Create a backup of the OpenSSL configuration file before making changes:
Shell
cp /usr/lib/ssl/openssl.cnf /usr/lib/ssl/openssl-backup.cnf
3
Open the OpenSSL configuration file for editing:
Shell
nano /usr/lib/ssl/openssl.cnf
4
At the top of the file, add the following line if it’s not already present:
Configuration
openssl_conf = openssl_init
5
At the bottom of the file, add the following configuration block. Update the paths as needed for your system:
Configuration
[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
pkcs11-module-token-pin = file:/path/to/file_with_pin.txt
activate = 1
WarningUpdate the paths accordingly. In our example:
  • Replace /path/to/pkcs11-provider/pkcs11.so with /usr/lib/x86_64-linux-gnu/ossl-modules/pkcs11.so
  • Replace /path/to/file_with_pin.txt with the path to your PIN file
TipIf you’re not sure where pkcs11.so is on your system, run this command:find / -type f -path ‘*/ossl-modules/pkcs11.so’ 2>/dev/null
6
Save and exit the file — Ctrl-X, Y, then Enter.
7
Verify that the PKCS #11 provider loads correctly:
Shell
openssl list -providers
  • You should see both default and pkcs11 listed.
  • Example output:
Shell
Providers:
  default
    name: OpenSSL Default Provider
    version: 3.0.13
    status: active
  pkcs11
    name: PKCS#11 Provider
    version: 1.1
    status: active
For Nginx, the following must also be added your openssl confiugration file. The IP.1 define must be your Nginx server IP address.
None
[ v3_leaf ]
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer
basicConstraints = critical,CA:false
keyUsage = digitalSignature, keyEncipherment, dataEncipherment, keyAgreement, nonRepudiation
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = SUBJECTALTNAME
IP.1 = Nginx server IP