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

# Installation

> Deploy the CryptoHub Client Library service, provision an endpoint, install the CryptoHub-backed PKCS#11 module on Windows, Linux, or macOS, place the configuration file, and verify the module with pkcs11-manager.

This page describes how to deploy the CryptoHub Client Library service, provision a client endpoint, install the CryptoHub-backed PKCS#11 module from the endpoint download, place its configuration file, and verify the installation before you connect a production application.

<Note>
  This guide covers the CryptoHub-backed module (`libcryptohub-pkcs11.*`). If you installed the legacy `fxpkcs11` module (`libfxpkcs11.so` / `fxpkcs11.dll`), follow the [PKCS#11 developer guide](../Overview/PKCS11_developer_guide/Before_you_start) instead.
</Note>

## How the module is delivered

Unlike the legacy Host-API libraries (FXPKCS11 and FXCNG), the CryptoHub Client Library reaches CryptoHub over the **v2 REST API on port 443**. It also ships **inside the endpoint download** rather than as a standalone package. You deploy a service in CryptoHub, add an endpoint to it, and download a zip file that contains the module, its supporting tools, a **pre-filled `cryptohub.json`**, and the TLS material for that endpoint. Deploying the endpoint provisions the identity and connection details the module uses to authenticate.

The workflow is therefore:

1. Deploy the CryptoHub Client Library service and provision an endpoint (on the CryptoHub appliance).
2. Install the module from the endpoint download (on the application host).
3. Place `cryptohub.json` where the module can find it.
4. Verify the module reaches and authenticates to CryptoHub.

## Before you start

Make sure you have the following:

* Access to a CryptoHub appliance (7.2 or later) and permission to deploy a service.
* Network access from the application host to your CryptoHub appliance over HTTPS on port 443.
* The operating system and architecture of the application host, so you can select the matching endpoint platform.

## Step 1: Deploy the service and provision an endpoint

Perform these steps in the CryptoHub web interface. They provision the identity, connection details, and download that the following steps use.

1. Deploy the **CryptoHub Client Library** service (from the Service Management store) into CryptoHub. If you already deployed a supported application's service, use that service instead.
2. Open the deployed service and navigate to its **Endpoints** menu. An endpoint is a device authorized to access the service.
3. In the **Manage Endpoints** menu, click **\[ Add New ]**.
4. In the **Add Endpoint** dialog:
   * Enter a **Name** for the endpoint.
   * Leave the auto-populated **CryptoHub Hostname** as-is.
   * Select the **Platform** the module will run on.
5. Click **\[ Add Endpoint ]**. The browser downloads a zip file that contains a **pre-filled `cryptohub.json`** and the **TLS material** for this endpoint — the connection, authentication, and TLS settings the module uses to reach and authenticate to your CryptoHub instance. Keep this download secure: it is a credential.

<Note>
  To change the authentication credential for an endpoint, go to the **Identity and Access** menu, select the **Applications & Partitions** tab, find the application you deployed, and in the **Manage** section select **Authentication**.
</Note>

<Warning>
  The CryptoHub Client Library authenticates over the REST API. Confirm that the endpoint's role has the **REST API** port enabled. Roles deployed by a service template ship with the **Excrypt** port only, so if the module reports an authentication failure, add the **REST API** port to the role under **Identity and Access**.
</Warning>

## Step 2: Install the provider library

The module ships inside the endpoint download — you do not need to obtain or install a separate package. Transfer the endpoint zip to the application host and extract it. The zip contains the provider library, the `pkcs11-manager` utility, the `fxchl` command-line client, supporting tools, the pre-filled `cryptohub.json`, and the TLS material for your instance.

On **Linux**, the endpoint zip provides:

* `libcryptohub-pkcs11.so` — the PKCS#11 module. This is the module path you point your application at.
* `pkcs11-manager` — interactive utility for testing the configuration and exercising PKCS#11 operations.
* `fxchl` — the CryptoHub command-line client, used here to verify connectivity and authentication.
* `config-translator`, `unit-tests` — supporting tools.
* `cryptohub.json` — your deployment configuration for this endpoint, pre-filled with the connection, authentication, and TLS settings.
* TLS material — the CA and client TLS files the module uses to establish, and for mutual TLS to authenticate, the connection to CryptoHub.

On **Windows**, the endpoint zip provides both client modules — `cryptohub-pkcs11.dll` (PKCS#11) and `cryptohub-cng.dll` (the CNG Key Storage Provider used by the CNG variant of this integration) — along with `pkcs11-manager.exe`, `fxchl.exe`, `config-translator.exe`, and the CNG tools (`cng-install.exe`, `cng-uninstall.exe`, `cng-manager.exe`), plus the pre-filled `cryptohub.json` and TLS material.

Move the provider library to a location your application's loader can reach:

<table>
  <thead>
    <tr>
      <th><strong>Platform</strong></th>
      <th><strong>Provider library</strong></th>
      <th><strong>Typical location</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Windows</td>
      <td><code>cryptohub-pkcs11.dll</code></td>
      <td><code>C:\Program Files\Futurex</code></td>
    </tr>

    <tr>
      <td>Linux and other POSIX systems</td>
      <td><code>libcryptohub-pkcs11.so</code></td>
      <td><code>/usr/local/lib/</code></td>
    </tr>

    <tr>
      <td>macOS (including ARM64)</td>
      <td><code>libcryptohub-pkcs11.dylib</code></td>
      <td><code>/usr/local/lib/</code></td>
    </tr>
  </tbody>
</table>

Record the absolute path to the installed library. You supply this path to any PKCS#11-consuming application as its module path.

<Note>
  Use the library build that matches both your CPU architecture and your application's OpenSSL major version. On macOS ARM64, use the ARM64 build. Select the corresponding endpoint platform in Step 1 so the download carries the correct build.
</Note>

Confirm the CLI runs:

```bash theme={null}
fxchl version
```

## Step 3: Place the configuration file

The endpoint download ships a **pre-filled `cryptohub.json`** for your instance. Start from that file — it already contains the connection, authentication, and TLS settings for the endpoint you created. Copy it to a runtime location the module searches, or point to it with the `CHLIBS_CONFIG` environment variable.

The runtime file must be named `cryptohub.json` unless you point to it with `CHLIBS_CONFIG`. The module searches for its configuration in this order and uses the first file it finds:

1. The path in the `CHLIBS_CONFIG` environment variable.
2. `cryptohub.json` in the current working directory of the calling process.
3. `../config/cryptohub.json` relative to the current working directory.
4. A platform-specific static path:
   * **Windows:** `C:\Program Files\Futurex\cryptohub.json`, then `C:\Program Files\Futurex\config\cryptohub.json`, then `C:\Futurex\cryptohub.json`, then `C:\Futurex\config\cryptohub.json`.
   * **POSIX:** `/etc/cryptohub.json`.

For system-wide POSIX installs, place the configuration at `/etc/cryptohub.json`. For machine-wide Windows installs, use `C:\Program Files\Futurex\cryptohub.json` or `C:\Program Files\Futurex\config\cryptohub.json`. If your application runs from a service account or a custom working directory, setting `CHLIBS_CONFIG` is often the simplest option:

```bash title="Set the configuration path (POSIX)" theme={null}
export CHLIBS_CONFIG=/etc/cryptohub.json
```

```powershell title="Set the configuration path (Windows)" theme={null}
setx CHLIBS_CONFIG "C:\Program Files\Futurex\cryptohub.json"
```

<Note>
  Set `CHLIBS_CONFIG` in the environment of the process that loads the module, and restart the consuming service after you set it so the new value takes effect.
</Note>

You normally do not need to edit the endpoint-provided file. If you configure `cryptohub.json` by hand, or need to understand any field, see [Configuration](./Configuration) for the full schema.

## Step 4: Verify the installation

Use the packaged `pkcs11-manager` utility to confirm the module loads, reads its configuration, authenticates to CryptoHub, and can see the token before you connect a production application. This is the primary verification tool and is included in the endpoint download. Run it and use its menu to:

1. Initialize the module.
2. Log in with the credential from `cryptohub.json`.
3. List slots and mechanisms.
4. Enumerate objects, and optionally generate a key and run a supported cryptographic operation.

```text title="pkcs11-manager" theme={null}
Info -> Get library info
Info -> Get slot list
Info -> List mechanisms
```

Confirm the following:

* **Library info** reports the manufacturer as Futurex, the description as `CryptoHub PKCS11`, and Cryptoki version `3.2`.
* **Slot list** shows a slot for each `PRODUCTION` CryptoHub destination in your configuration.
* **List mechanisms** returns the mechanisms your CryptoHub service and key store support.

A successful login and slot listing confirms that the module, configuration, credential, and TLS trust are all correct.

You can also use the `fxchl` CLI for a focused connectivity and authentication check:

```bash theme={null}
fxchl connect --host <cryptohub-host> --port 443
fxchl login user --user <username>      # username/password
fxchl login apikey --key <api-key>      # API key
fxchl login pki --cert <identity.pem>   # TLS/PKI identity
fxchl status
```

A successful `fxchl status` reports the session as authenticated and the server as reachable.

<Note>
  On CryptoHub 7.3.0.x, `fxchl service list` returns `NOT_FOUND`. Select the service by UUID instead — the UUID is the `global.service_uuid` from your `cryptohub.json` — with `fxchl service use --uuid <service-uuid>`, then confirm it with `fxchl service show`.
</Note>

Where your operating system provides the OpenSC `pkcs11-tool` utility and it is compatible with the PKCS#11 v3.2 mechanism definitions, you can run the same checks against the installed library. `pkcs11-tool` is an **external** tool installed separately (for example, from the `opensc` package) and is not part of the CryptoHub Client Library:

```bash theme={null}
pkcs11-tool --module /usr/local/lib/libcryptohub-pkcs11.so --list-token-slots
pkcs11-tool --module /usr/local/lib/libcryptohub-pkcs11.so --list-mechanisms
```

<Note>
  The authoritative mechanism list is the list the installed library returns for the selected slot. The mechanisms and key sizes in [Appendix A](./Appendices/Appendix_A_Supported_mechanisms) can vary by CryptoHub release; policy and key metadata can further restrict operations. Always verify against your own installation.
</Note>

## Next steps

* Configure the module in [Configuration](./Configuration).
* Learn how CryptoHub services and key stores map onto PKCS#11 objects in [Architecture](./Architecture).
* Use post-quantum mechanisms in [Post-quantum cryptography](./Post_quantum_cryptography).
* Diagnose problems in [Troubleshooting](./Troubleshooting).