Install and configure OpenSSL Engine

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.

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.

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

Install libp11 and OpenSC.
Edit the OpenSSL configuration file.

Install libp11 and OpenSC

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.

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

Install the build dependencies and OpenSC:

sudo apt update
sudo apt install -y git build-essential autoconf automake libtool pkg-config libssl-dev opensc

Clone libp11 0.4.21 and verify the source revision:

git clone --depth 1 --branch libp11-0.4.21 https://github.com/OpenSC/libp11.git
cd libp11
git rev-parse HEAD

The revision is ad19678991c5882d252b06ed02c4d4fb990913d0.

Build and install libp11:

./bootstrap
./configure
make -j"$(nproc)"
sudo make install

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.

Display the OpenSSL engine directory:

openssl version -e

The command prints an ENGINESDIR path. Confirm that pkcs11.so exists in that directory.

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

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.

Verify the engine configuration:

export CHLIBS_CONFIG=/etc/cryptohub.json
OPENSSL_CONF=/etc/ssl/openssl-cryptohub-engine.cnf openssl engine -t -c pkcs11

The pkcs11 engine reports [ available ].

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.

​Install libp11 and OpenSC

​Edit the OpenSSL configuration file

​Point the library at your cryptohub.json

Install libp11 and OpenSC

Edit the OpenSSL configuration file

Point the library at your `cryptohub.json`