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

> Procedural guide to installing and configuring libp11, OpenSC, and OpenSSL Engine config.

This section covers installing and configuring the following components of the OpenSSL library:

* **libp11**: Provides a higher-level interface (compared to the PKCS #11 library) for accessing PKCS #11 objects. It integrates with applications that use OpenSSL.
* **OpenSC**: Provides a set of libraries and utilities to work with smart cards. It focuses on cards that support cryptographic operations and facilitates their use in security applications such as authentication, mail encryption, and digital signatures.
* **pkcs11 engine plugin**: Engine plugin for the OpenSSL library that allows accessing PKCS #11 modules in a semi-transparent way.

<Note>
  The OpenSSL ENGINE interface is legacy and was deprecated in OpenSSL 3.x. On OpenSSL 3.x, Futurex recommends the OpenSSL **provider** path (see the OpenSSL Provider integration) instead. Use this ENGINE path for OpenSSL 1.1.x or where an existing application still relies on the engine interface.
</Note>

Perform the following tasks to install and configure the OpenSSL Engine:

1. Install libp11 and OpenSC.
2. Edit the OpenSSL configuration file.

## Install libp11 and OpenSC

<Warning>
  Use libp11 0.4.21 with OpenSSL 3. Ubuntu 24.04 provides libp11 0.4.12, which can abort when ENGINE loads a CryptoHub-backed key.
</Warning>

The following steps build the validated libp11 release on Ubuntu 24.04 or Debian 12.

<Steps>
  <Step>
    Install the build dependencies and OpenSC:

    ```bash theme={null}
    sudo apt update
    sudo apt install -y git build-essential autoconf automake libtool pkg-config libssl-dev opensc
    ```
  </Step>

  <Step>
    Clone libp11 0.4.21 and verify the source revision:

    ```bash theme={null}
    git clone --depth 1 --branch libp11-0.4.21 https://github.com/OpenSC/libp11.git
    cd libp11
    git rev-parse HEAD
    ```

    <Check>
      The revision is `ad19678991c5882d252b06ed02c4d4fb990913d0`.
    </Check>
  </Step>

  <Step>
    Build and install libp11:

    ```bash theme={null}
    ./bootstrap
    ./configure
    make -j"$(nproc)"
    sudo make install
    ```
  </Step>
</Steps>

## Edit the OpenSSL configuration file

Create a dedicated OpenSSL configuration for the ENGINE consumer. Do not activate the engine in the system-wide OpenSSL configuration.

<Steps>
  <Step>
    Display the OpenSSL engine directory:

    ```bash theme={null}
    openssl version -e
    ```

    <Check>
      The command prints an `ENGINESDIR` path. Confirm that `pkcs11.so` exists in that directory.
    </Check>
  </Step>

  <Step>
    Create a dedicated OpenSSL configuration file and add the following configuration. Replace `<openssl-engines-directory>` with the `ENGINESDIR` value from the previous step:

    ```ini theme={null}
    openssl_conf = openssl_init

    [openssl_init]
    engines = engine_section

    [engine_section]
    pkcs11 = pkcs11_section

    [pkcs11_section]
    engine_id = pkcs11
    dynamic_path = <openssl-engines-directory>/pkcs11.so
    MODULE_PATH = /usr/local/lib/libcryptohub-pkcs11.so
    init = 1
    ```

    Do not add a `PIN` control or a `pin-value` or `pin-source` URI attribute. The CryptoHub Client Library authenticates with the endpoint credential in `cryptohub.json`.
  </Step>

  <Step>
    Verify the engine configuration:

    ```bash theme={null}
    export CHLIBS_CONFIG=/etc/cryptohub.json
    OPENSSL_CONF=/etc/ssl/openssl-cryptohub-engine.cnf openssl engine -t -c pkcs11
    ```

    <Check>
      The `pkcs11` engine reports `[ available ]`.
    </Check>
  </Step>
</Steps>

## Point the library at your `cryptohub.json`

Point the CryptoHub Client Library at your deployed `cryptohub.json` by setting `CHLIBS_CONFIG` in the environment of the shell (and any application) that loads the module:

```
export CHLIBS_CONFIG=/etc/cryptohub.json
export OPENSSL_CONF=/etc/ssl/openssl-cryptohub-engine.cnf
```

`CHLIBS_CONFIG` must be present in the environment of any process that loads the module. The engine uses the module set through `MODULE_PATH` in `openssl.cnf`, so you do not set a separate module environment variable.