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

# Overview

> Introduces the CryptoHub-backed PKCS#11 module (libcryptohub-pkcs11), how it differs from the legacy fxpkcs11 provider, and its supported platforms and Cryptoki version.

The CryptoHub-backed PKCS#11 module lets applications perform cryptographic operations against CryptoHub-managed keys through the standard PKCS#11 (Cryptoki) API. Instead of connecting directly to an HSM, the module talks to one or more CryptoHub appliances over a REST/TLS connection and presents the keys in a CryptoHub service and key store as PKCS#11 objects. The module reports Cryptoki version 3.2 and implements the PKCS#11 v3.2 key encapsulation interface, so it exposes post-quantum ML-DSA and ML-KEM operations alongside classical RSA, ECC, and symmetric mechanisms.

<Note>
  This guide documents the CryptoHub-backed module (`libcryptohub-pkcs11.*`, configured with `cryptohub.json`). It is a different provider from the legacy Futurex PKCS#11 module (`fxpkcs11` / `libfxpkcs11.so`, configured with the XML-based `fxpkcs11.cfg`), which connects directly to an HSM and is documented in the [PKCS#11 developer guide](/Drivers_and_libraries/Overview/PKCS11_developer_guide/Before_you_start). Choose the guide that matches the library you installed.
</Note>

## Choosing between the CryptoHub-backed and legacy PKCS#11 modules

Both modules expose the same PKCS#11 API to your application, but they connect to Futurex infrastructure in different ways and are configured differently. Futurex recommends the CryptoHub-backed module for new deployments that use CryptoHub, and for any application that needs post-quantum mechanisms.

<table>
  <thead>
    <tr>
      <th><strong>Aspect</strong></th>
      <th><strong>CryptoHub-backed module</strong></th>
      <th><strong>Legacy <code>fxpkcs11</code> module</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Library</td>
      <td><code>cryptohub-pkcs11.dll</code>, <code>libcryptohub-pkcs11.so</code>, <code>libcryptohub-pkcs11.dylib</code></td>
      <td><code>libfxpkcs11.so</code>, <code>fxpkcs11.dll</code></td>
    </tr>

    <tr>
      <td>Configuration file</td>
      <td><code>cryptohub.json</code> (JSON)</td>
      <td><code>fxpkcs11.cfg</code> (XML-like tags)</td>
    </tr>

    <tr>
      <td>Connection</td>
      <td>One or more CryptoHub REST base URIs over TLS</td>
      <td>Direct HSM host and port</td>
    </tr>

    <tr>
      <td>Key location</td>
      <td>CryptoHub service and key store</td>
      <td>HSM token</td>
    </tr>

    <tr>
      <td>Authentication</td>
      <td>CryptoHub user credentials, API key, PKI nonce-signature, or mutual TLS</td>
      <td>HSM operator credentials and direct-HSM TLS</td>
    </tr>

    <tr>
      <td>Cryptoki version</td>
      <td>3.2 (includes PKCS#11 v3.2 KEM)</td>
      <td>3.0</td>
    </tr>

    <tr>
      <td>Post-quantum support</td>
      <td>ML-DSA and ML-KEM</td>
      <td>Not exposed</td>
    </tr>
  </tbody>
</table>

## What the endpoint download includes

The CryptoHub-backed module ships **inside the endpoint download**, not as a standalone package. You deploy a CryptoHub Client Library service, add an endpoint to it, and download a zip file that contains the provider library for the platform you selected, a **pre-filled `cryptohub.json`** and TLS material for that endpoint, and command-line tools for exercising and configuring the module. See [Installation](./Installation) for the full workflow.

<table>
  <thead>
    <tr>
      <th><strong>Item</strong></th>
      <th><strong>Purpose</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>cryptohub-pkcs11.dll</code> / <code>libcryptohub-pkcs11.so</code> / <code>libcryptohub-pkcs11.dylib</code></td>
      <td>The PKCS#11 provider library. Point your application's PKCS#11 module path at this file.</td>
    </tr>

    <tr>
      <td><code>pkcs11-manager</code></td>
      <td>Interactive utility for initializing the module, logging in, listing slots and mechanisms, enumerating objects, generating keys, and running cryptographic operations.</td>
    </tr>

    <tr>
      <td><code>fxchl</code></td>
      <td>Command-line client for CryptoHub Client Library operations, used to verify connectivity and authentication.</td>
    </tr>

    <tr>
      <td><code>config-translator</code></td>
      <td>Helper for producing a <code>cryptohub.json</code> configuration.</td>
    </tr>

    <tr>
      <td><code>cryptohub.json</code></td>
      <td>Your deployment configuration for this endpoint, pre-filled with the connection, authentication, and TLS settings.</td>
    </tr>

    <tr>
      <td>TLS material</td>
      <td>The CA and client TLS files the module uses to establish, and for mutual TLS to authenticate, the connection to CryptoHub.</td>
    </tr>
  </tbody>
</table>

## Supported platforms

The module ships as a native library for each supported platform. Package names and library extensions vary by platform.

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

  <tbody>
    <tr>
      <td>Windows</td>
      <td><code>cryptohub-pkcs11.dll</code></td>
    </tr>

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

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

## Version reference

The following table records the module identifiers this guide documents. Because advertised mechanisms and key-size limits can change between CryptoHub releases, treat the mechanism appendix as a snapshot and verify against your own installation.

<table>
  <thead>
    <tr>
      <th><strong>Property</strong></th>
      <th><strong>Value</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Library-reported manufacturer</td>
      <td>Futurex</td>
    </tr>

    <tr>
      <td>Library-reported description</td>
      <td><code>CryptoHub PKCS11</code></td>
    </tr>

    <tr>
      <td>Cryptoki version</td>
      <td><code>3.2</code></td>
    </tr>

    <tr>
      <td>Backend validated against</td>
      <td>CryptoHub 7.3</td>
    </tr>
  </tbody>
</table>

## Documentation structure

This guide walks you through installing, configuring, and using the CryptoHub-backed PKCS#11 module.

* **Installation**: Install the provider library for your platform and verify it with `pkcs11-manager`.
* **Configuration**: Configure `cryptohub.json`, including connection, authentication, TLS, and key usage policy.
* **Architecture**: Understand how the module maps CryptoHub services, key stores, and protection models onto PKCS#11 slots, tokens, and objects.
* **Post-quantum cryptography**: Generate and use ML-DSA and ML-KEM keys through the PKCS#11 v3.2 interface.
* **Troubleshooting**: Diagnose configuration, connectivity, authentication, and compatibility problems.
* **Appendix A**: Reference the mechanisms the module advertises at runtime.