> ## 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 CNG service, provision a Windows endpoint, install and register the Futurex CryptoHub Key Storage Provider, and verify it reaches CryptoHub.

This page describes how to deploy the CryptoHub Client Library CNG service, provision a Windows client endpoint, install and register the **Futurex CryptoHub Key Storage Provider** from the endpoint download, place its configuration file, and verify the provider reaches CryptoHub before you connect a production application.

<Note>
  This guide covers the CryptoHub Client Library CNG provider (`cryptohub-cng.dll`), which requires CryptoHub 7.2 or later. Earlier releases ship the legacy FXCNG provider, which this guide does not cover. See [Overview](./Overview) for how the providers differ.
</Note>

## How the provider is delivered

The CNG provider reaches CryptoHub over the **v2 REST API on port 443**. It ships **inside the Windows endpoint download** rather than as a standalone package. You deploy a service in CryptoHub, add a Windows endpoint to it, and download a zip file that contains the provider DLL, its installer and management tools, a **pre-filled `cryptohub.json`**, and the TLS material for that endpoint. The workflow is:

1. Deploy the CryptoHub Client Library CNG service and provision a Windows endpoint (on the CryptoHub appliance).
2. Install and register the provider from the endpoint download (on the Windows host).
3. Place `cryptohub.json` where the provider can find it.
4. Verify the provider 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.
* **Local administrator access** on the Windows host. Registering a Key Storage Provider is a machine-wide operation.
* Outbound TCP port **443** from the Windows host to the CryptoHub, allowed through any firewall. Specify the CryptoHub by FQDN or CIDR.

<Warning>
  TLS inspection or SSL proxies can break the mutual TLS handshake. Exempt the CryptoHub FQDN from inspection, and configure the CryptoHub with an FQDN so the exemption applies.
</Warning>

## Step 1: Deploy the service and provision a Windows 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 (CNG)** service (from the Service Management store) into CryptoHub. If you already deployed a supported Windows 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.
   * Set the **Platform** to **Windows**, since the CNG provider is a Windows Key Storage Provider.
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 provider uses to reach and authenticate to your CryptoHub instance. Keep this download secure: it is a credential.

Transfer the endpoint zip to the Windows host where the application you are integrating runs.

<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 CNG provider 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 provider reports an authentication failure, add the **REST API** port to the role under **Identity and Access**.
</Warning>

## Step 2: Extract the endpoint download

Extract the endpoint zip to a working directory on the Windows host. It provides:

<table>
  <thead>
    <tr>
      <th><strong>File</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>cryptohub-cng.dll</code></td>
      <td>The CNG Key Storage Provider that Windows loads after registration.</td>
    </tr>

    <tr>
      <td><code>cng-install.exe</code></td>
      <td>Administrator installer that copies and registers the KSP.</td>
    </tr>

    <tr>
      <td><code>cng-uninstall.exe</code></td>
      <td>Administrator uninstaller that unregisters the KSP.</td>
    </tr>

    <tr>
      <td><code>cng-manager.exe</code></td>
      <td>Interactive utility for listing, generating, deleting, signing, and verifying keys.</td>
    </tr>

    <tr>
      <td><code>cryptohub.json</code></td>
      <td>Your deployment configuration, pre-filled for this endpoint.</td>
    </tr>

    <tr>
      <td>TLS material</td>
      <td>The CA and client TLS files the provider uses to reach and authenticate to CryptoHub.</td>
    </tr>
  </tbody>
</table>

The download also carries the PKCS#11 module (`cryptohub-pkcs11.dll`) and its tools; they are not required for the CNG workflow.

## Step 3: Place the configuration file

The endpoint download ships a **pre-filled `cryptohub.json`** for your instance — use it. It already carries the CryptoHub host, the service this integration uses, the endpoint's authentication material, and the TLS trust settings.

Copy the file to a machine-wide location the provider searches. The CNG provider searches these locations, in order, and uses the first one it finds:

1. `C:\Program Files\Futurex\cryptohub.json`
2. `C:\Program Files\Futurex\config\cryptohub.json`
3. `C:\Futurex\cryptohub.json`
4. `C:\Futurex\config\cryptohub.json`
5. The path in the `CHLIBS_CONFIG` environment variable.

For machine-wide installations, place the file at `C:\Program Files\Futurex\cryptohub.json`. If the calling application runs under a locked-down service account or from a custom working directory, set the machine-level `CHLIBS_CONFIG` environment variable to the full path of your `cryptohub.json` instead:

```powershell theme={null}
[System.Environment]::SetEnvironmentVariable("CHLIBS_CONFIG", "C:\path\to\cryptohub.json", "Machine")
```

<Warning>
  Restart the consuming service (for example, the SQL Server or web-server service) after you set `CHLIBS_CONFIG` so the new value takes effect.
</Warning>

<Note>
  The CNG provider's search order places the static paths **before** `CHLIBS_CONFIG`, which is the reverse of the PKCS#11 module's order. A stray `cryptohub.json` under `C:\Program Files\Futurex` therefore takes precedence over `CHLIBS_CONFIG`.
</Note>

The `cng.provider_name` value in `cryptohub.json` must match the provider name registered at install time. The default is `Futurex CryptoHub Key Storage Provider`. Confirm the key-protection and usage settings your application needs before you create any keys — see [Configuration](./Configuration).

## Step 4: Register the provider

Double-click `cng-install.exe` and approve the UAC prompt, or run it from an administrator command prompt. The installer copies `cryptohub-cng.dll` into the Windows system directory and registers it as the **Futurex CryptoHub Key Storage Provider**. To replace an existing installation, run:

```powershell theme={null}
cng-install.exe -overwrite
```

<Note>
  `cng-install.exe` is a graphical process and does not exit on its own when you start it from a script or a non-interactive session. Registration completes within seconds. If you automate the install, verify registration and then end the process rather than waiting for it to return.
</Note>

## Step 5: Verify the provider

Confirm that the provider can reach and authenticate to CryptoHub, not only that Windows registered it:

```powershell theme={null}
certutil -key -csp "Futurex CryptoHub Key Storage Provider"
```

The command enumerates the keys the provider can see in CryptoHub. On a new deployment the key list is empty, but the command completes without error — that confirms the provider loaded its configuration and authenticated to CryptoHub.

<Warning>
  Do not treat `certutil -csplist` as the verification step. It confirms only that Windows registered the provider, and it succeeds even when every call to CryptoHub is failing. Always confirm the backend with `certutil -key -csp`.
</Warning>

You can also use `cng-manager.exe` to confirm the configuration and perform basic key operations. It provides menu options for enumerating keys, generating supported key types, destroying keys, and testing sign and verify operations. A successful enumerate, generate, sign, and verify cycle confirms that the provider is registered and can reach and authenticate to CryptoHub.

## Uninstalling

Double-click `cng-uninstall.exe` and approve the UAC prompt to unregister the provider. Run `cng-uninstall.exe -remove` from an administrator command prompt to also remove `cryptohub-cng.dll` from the Windows system directory.

## Next steps

* Configure the provider in [Configuration](./Configuration).
* Diagnose problems in [Troubleshooting](./Troubleshooting).
* Reference the supported algorithms in [Appendix A](./Appendices/Appendix_A_Supported_algorithms).