> ## 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 and configure OpenSSL pkcs11-provider

> Step-by-step guide to install and configure the pkcs11-provider for OpenSSL.

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

<Warning>
  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.
</Warning>

<Steps>
  <Step>
    Install the required packages:

    ```shell expandable lines wrap title="Shell" theme={null}
    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
    ```
  </Step>

  <Step>
    Create a source directory and change into it:

    ```shell expandable lines wrap title="Shell" theme={null}
    mkdir -p ~/src
    cd ~/src
    ```
  </Step>

  <Step>
    Clone the **pkcs11-provider** repository:

    ```shell expandable lines wrap title="Shell" theme={null}
    git clone https://github.com/latchset/pkcs11-provider.git
    cd pkcs11-provider
    ```
  </Step>

  <Step>
    Build the provider:

    ```shell expandable lines wrap title="Shell" theme={null}
    meson setup builddir
    meson compile -C builddir
    ```
  </Step>

  <Step>
    Install the provider:

    ```shell expandable lines wrap title="Shell" theme={null}
    sudo meson install -C builddir
    ```

    <Note>
      During installation, the `pkcs11.so` module is copied to the OpenSSL modules directory. You’ll need this path when updating the OpenSSL configuration file.
    </Note>

    Example output:

    ```shell expandable lines wrap title="Shell" theme={null}
    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`.
  </Step>
</Steps>

## Install on RHEL

<Warning>
  **Important**

  This step includes enabling the `EPEL` and `CodeReady Builder (CRB)` repositories, so ensure you have a valid RHEL subscription.
</Warning>

<Steps>
  <Step>
    Enable **CodeReady Builder (CRB)**:

    **RHEL 8**:

    ```shell expandable lines wrap title="Shell" theme={null}
    sudo subscription-manager repos --enable codeready-builder-for-rhel-8-$(arch)-rpms
    ```

    **RHEL 9**:

    ```shell expandable lines wrap title="Shell" theme={null}
    sudo subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms
    ```

    **Alma** and **Rocky Linux 8**:

    ```shell expandable lines wrap title="Shell" theme={null}
    sudo dnf config-manager --set-enabled powertools
    ```

    **Alma** and **Rocky Linux 9**:

    ```shell expandable lines wrap title="Shell" theme={null}
    sudo dnf config-manager --set-enabled crb
    ```
  </Step>

  <Step>
    Install the **EPEL Release** package:

    ```shell expandable lines wrap title="Shell" theme={null}
    sudo dnf install epel-release
    ```
  </Step>

  <Step>
    Refresh metadata:

    ```shell expandable lines wrap title="Shell" theme={null}
    sudo dnf makecache
    ```
  </Step>

  <Step>
    Install prerequisites:

    ```shell expandable lines wrap title="Shell" theme={null}
    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
    ```
  </Step>

  <Step>
    Change to a source directory:

    ```shell expandable lines wrap title="Shell" theme={null}
    cd /usr/local/src
    ```
  </Step>

  <Step>
    Clone the repository:

    ```shell expandable lines wrap title="Shell" theme={null}
    git clone https://github.com/latchset/pkcs11-provider.git
    cd pkcs11-provider
    ```
  </Step>

  <Step>
    Build the provider:

    ```shell expandable lines wrap title="Shell" theme={null}
    meson setup builddir
    meson compile -C builddir
    ```
  </Step>

  <Step>
    Install the provider:

    ```shell expandable lines wrap title="Shell" theme={null}
    sudo meson install -C builddir
    ```

    <Note>
      During installation, the `pkcs11.so` module is copied to the OpenSSL modules directory. You’ll need this path when updating the OpenSSL configuration file.
    </Note>

    Example output:

    ```shell expandable lines wrap title="Shell" theme={null}
    Installing src/pkcs11.so to /usr/lib64/ossl-modules
    ```

    In this example, `pkcs11.so` is installed in `/usr/lib64/ossl-modules`.
  </Step>
</Steps>

<Note>
  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 HSM functionality. Token verification works as expected on Rocky Linux 10.
</Note>

## Configure OpenSSL to load the provider

<Steps>
  <Step>
    Locate the OpenSSL configuration file. You can verify it using the following command `openssl version -d`. For instance:

    * For **Ubuntu/Debian:**

    ```shell expandable lines wrap title="Shell" theme={null}
    openssl version -d
    OPENSSLDIR: "/usr/lib/ssl"
    ```

    * For **RHEL:**

    ```shell expandable lines wrap title="Shell" theme={null}
    openssl version -d
    OPENSSLDIR: "/etc/pki/tls"
    ```

    <Warning>
      **Important**

      This tutorial assumes `openssl.cnf` is located in `/usr/lib/ssl/`. Update the path in the following commands accordingly.
    </Warning>
  </Step>

  <Step>
    Create a backup of the OpenSSL configuration file before making changes:

    ```shell expandable lines wrap title="Shell" theme={null}
    cp /usr/lib/ssl/openssl.cnf /usr/lib/ssl/openssl-backup.cnf
    ```
  </Step>

  <Step>
    Open the OpenSSL configuration file for editing:

    ```shell expandable lines wrap title="Shell" theme={null}
    nano /usr/lib/ssl/openssl.cnf
    ```
  </Step>

  <Step>
    At the top of the file, add the following line if it’s not already present:

    ```ini expandable lines wrap title="Configuration" theme={null}
    openssl_conf = openssl_init
    ```
  </Step>

  <Step>
    At the bottom of the file, add the following configuration block. Update the paths as needed for your system:

    ```ini expandable lines wrap title="Configuration" theme={null}
    [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
    ```

    <Warning>
      Update 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
    </Warning>

    <Tip>
      If 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`
    </Tip>
  </Step>

  <Step>
    Save and exit the file — Ctrl-X, Y, then Enter.
  </Step>

  <Step>
    Verify that the PKCS #11 provider loads correctly:

    ```shell expandable lines wrap title="Shell" theme={null}
    openssl list -providers
    ```

    * You should see both `default` and `pkcs11` listed.
    * Example output:

    ```shell expandable lines wrap title="Shell" theme={null}
    Providers:
      default
        name: OpenSSL Default Provider
        version: 3.0.13
        status: active
      pkcs11
        name: PKCS#11 Provider
        version: 1.1
        status: active
    ```
  </Step>
</Steps>