> ## 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 Futurex PKCS #11

> Instructions for installing and configuring the Futurex PKCS #11 library on the Windows host that runs Nexus Certificate Manager.

Install **Futurex PKCS #11 (FXPKCS11)** on the Windows host that runs Certificate Manager and `hwsetup`.

<Steps>
  <Step>
    Extract the endpoint ZIP file you downloaded after deploying the client endpoint. The ZIP file contains the following files:

    | File | Description |
    | - | - |
    | `PKCS11Manager.exe` | Program to test the connection to the CryptoHub and perform basic functions through the FXPKCS11 module, such as logging in and generating random data. |
    | `ca-chain.pem` | CA certificate bundle. |
    | `client-cert.pem` | Client TLS certificate. |
    | `client.p12` | Full client PKI in encrypted PKCS #12 format (contains the CA chain, client certificate, and client private key). |
    | `configTest.exe` | Program to test the configuration and connection to the CryptoHub. |
    | `fxpkcs11.cfg` | Configuration file for the Futurex PKCS #11 library. |
    | `fxpkcs11.dll` | The Futurex PKCS #11 library file. |
    | `CryptoHub <number>.cer` | Auto-generated self-signed CA certificate used to issue client endpoint TLS certificates (the number is random). |
    | `Futurex Test Root CA (ECC).cer` or `Futurex Test Root SSL CA.cer` | Futurex Test Root CA for embedded Futurex Test TLS certificates (ECC or RSA, based on the algorithm configured for the connection pair). |
  </Step>

  <Step>
    As an administrator, create the `C:\Program Files\Futurex\fxpkcs11` directory and move all of the preceding files into it.

    Every `hwsetup` command in this guide loads the library from `C:\Program Files\Futurex\fxpkcs11\fxpkcs11.dll`.
  </Step>

  <Step>
    Keep `fxpkcs11.cfg` in the same directory.

    The module looks for `fxpkcs11.cfg` in `C:\Program Files\Futurex\fxpkcs11` by default. If you store the configuration elsewhere, set the **FXPKCS11\_CFG** environment variable to the full path of the configuration file. The TLS files that the configuration references must stay in the same directory as `fxpkcs11.cfg`.
  </Step>

  <Step>
    Record the PKCS #11 PIN.

    * Find the PIN in the `CRYPTO-OPR-PASS` setting inside `fxpkcs11.cfg`.
    * Copy the PIN to a secure location. You pass it to `hwsetup` and configure it in Certificate Manager in later steps.
    * Comment out the `CRYPTO-OPR-PASS` line, so the PIN is supplied only by the application that logs in:

    ```cfg expandable lines wrap title="fxpkcs11.cfg" theme={null}
    # <CRYPTO-OPR-PASS>your-pin-here</CRYPTO-OPR-PASS>
    ```

    <Note>
      If the PIN contains `&`, run every `hwsetup` command in this guide from Command Prompt and wrap the PIN in double quotes. PowerShell does not pass `&` to a batch file intact.
    </Note>
  </Step>

  <Step>
    Move the PKCS #12 password to an environment variable.

    * Find the password in the `PROD-TLS-KEY-PASS` setting inside `fxpkcs11.cfg`.
    * Copy the password, then replace the value in `fxpkcs11.cfg` with `env:PKCS11_P12`.
    * Set the machine-wide environment variable in an elevated Command Prompt (**Run as Administrator**):

    ```shell expandable lines wrap title="Command Prompt" theme={null}
    setx PKCS11_P12 "your-p12-password" /M
    ```

    Replace `your-p12-password` with the password you copied.

    <Warning>
      Newly set environment variables are visible only to **new** processes. Close and reopen Command Prompt, and restart the Certificate Manager services, before you run anything that relies on `PKCS11_P12`.
    </Warning>
  </Step>

  <Step>
    Locate the logs.

    * The default FXPKCS11 log location is `C:\Program Files\Futurex\fxpkcs11`.
    * To change it, modify the `LOG-FILE` setting in `fxpkcs11.cfg`.
  </Step>

  <Step>
    Validate the configuration and connection.

    Open a new Command Prompt and run `configTest.exe` from `C:\Program Files\Futurex\fxpkcs11`:

    ```shell expandable lines wrap title="Command Prompt" theme={null}
    cd /d "C:\Program Files\Futurex\fxpkcs11"
    configTest.exe
    ```

    <Check>
      The connection test succeeds. If it fails, read the FXPKCS11 log file and confirm the PKCS #12 password and TLS files are in the expected locations.
    </Check>
  </Step>

  <Step>
    Validate PKCS #11 operations.

    Run `PKCS11Manager.exe` from the same directory, log in with the PKCS #11 PIN, and perform a simple action such as generating random data.

    <Check>
      The login succeeds and the action returns a result. If authentication fails, confirm the PIN. To reset it, go to **Identity and Access** > **Applications & Partitions**, find the application you deployed, and select **\[ Authentication ]** in the **Manage** section.
    </Check>
  </Step>
</Steps>