> ## 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 the CryptoHub Client Library

> Install the endpoint-delivered CryptoHub Client Library and configure its connection for an OpenSSL engine consumer.

##### Install the CryptoHub Client Library (FXCHLIBS)

Your OpenSSL-based application is a Linux OpenSSL-engine consumer, so it reaches CryptoHub through the Linux PKCS #11 module (`libcryptohub-pkcs11.so`) loaded through the OpenSSL pkcs11 engine. The endpoint download contains the module, its supporting tool, configuration, credentials, and TLS files.

1. Extract the endpoint zip on the OpenSSL host. It provides:

   * `libcryptohub-pkcs11.so`: The CryptoHub PKCS #11 module loaded by the OpenSSL engine.
   * `pkcs11-manager`: The interactive utility for initializing the module and checking slots and objects.
   * `cryptohub.json`: The service-matched configuration with the endpoint's UserPass credential.
   * TLS material: The CA chain and client PKCS #12 material referenced by `cryptohub.json`.

2. Install the module and utility in locations available to the account that runs OpenSSL. For example:

   ```bash theme={null}
   sudo install -m 755 libcryptohub-pkcs11.so /usr/local/lib/libcryptohub-pkcs11.so
   sudo install -m 755 pkcs11-manager /usr/local/bin/pkcs11-manager
   ```

##### Configure the connection (`cryptohub.json`)

The CryptoHub Client Library reads its connection and authentication settings from a `cryptohub.json` file. The endpoint download you generated above provides a pre-filled `cryptohub.json` and TLS material for your instance: use it. It carries the CryptoHub host and REST API port, the service reference, the endpoint's authentication material, and the TLS settings, on top of the library-behavior defaults pinned by this template.

1. Place `cryptohub.json` and every TLS file from the same endpoint download in one protected directory that the OpenSSL account can read. Preserve the filenames because the configuration uses paths relative to its own directory.

2. Verify `cryptohubs[].base_uri`. If the host is empty, such as `https://:443`, enter the CryptoHub FQDN or address. Endpoint downloads do not always populate it.

3. Confirm that every file referenced by `cryptohubs[].tls.authorities` and `cryptohubs[].tls.client_file` is present. If one is missing, generate a new endpoint download; do not remove the client-certificate setting. Keep TLS verification enabled and trust CryptoHub through the shipped CA files.

4. Set `global.key_protection` to `PROTECTED`. The test procedure uses one RSA key for signing and decryption, and `TRUSTED` does not support that mixed usage set.

5. Point the library at the file by setting the `CHLIBS_CONFIG` environment variable to its full path. The variable must be present in the environment of every process that loads the module:

   ```
   export CHLIBS_CONFIG=/etc/cryptohub.json
   ```

   On POSIX systems the module also searches `./cryptohub.json`, `../config/cryptohub.json`, and `/etc/cryptohub.json` when `CHLIBS_CONFIG` is unset, but setting `CHLIBS_CONFIG` explicitly is the most reliable option for a service account.

**Note**: For production deployments, keep TLS verification enabled in `cryptohub.json` and trust CryptoHub's certificate through its CA.

**Note**: The service and its key store must exist in CryptoHub before the service reference in `cryptohub.json` can resolve. You deployed this service earlier in this guide, so it already exists.

##### Verify the module

Use the bundled `pkcs11-manager` to confirm the module can reach and authenticate to CryptoHub before configuring the OpenSSL engine. It is an interactive menu utility, not an automatic connectivity probe, and its first argument is the configuration path. Complete the initialization, login, and slot-listing menu actions.

```
CHLIBS_CONFIG=/etc/cryptohub.json pkcs11-manager /etc/cryptohub.json
```

A successful login and slot listing confirm that the module reaches CryptoHub and accepts the endpoint credential.