> ## 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 Provider

> Instructions for installing and configuring the pkcs11-provider for OpenSSL and activating it against the CryptoHub PKCS

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

1. In a terminal, install the provider package:

   ```
   sudo apt update
   sudo apt install pkcs11-provider
   ```

###### Red Hat/CentOS/Rocky

1. In a terminal, install the provider package:

   ```
   sudo dnf install pkcs11-provider
   ```

2. 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](https://github.com/latchset/pkcs11-provider) 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.

1. 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:

   ```sh theme={null}
   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.

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

##### 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:

1. 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
   ```

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

3. 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`.