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

# Configure SunPKCS11 to use the Futurex PKCS11 module

> Instructions for configuring SunPKCS11 provider to use Futurex PKCS #11 module on Linux and Windows.

This section shows how to configure the **SunPKCS11 provider** to use the Futurex PKCS #11 module, providing separate instructions for Linux and Windows. The **SunPKCS11 provider**, an integral part of the **Java Cryptography Architecture (JCA)**, enables Java applications to access cryptographic services through the PKCS #11 API. JSign uses it to reach the signing key on the CryptoHub.

<Warning>
  This flow requires **Futurex PKCS #11 (FXPKCS11) 6.0 rev dc27 or later**. Earlier libraries (including the 4.59 build bundled in the endpoint ZIP) do not pair the generated certificate with the private key, so `keytool -list` reports 0 entries and **JSign** fails with `privateKey is null`. See [Before you start](/Integrations/CryptoHub/Code_signing/JSign/Before_you_start) for how to obtain a supported build.
</Warning>

The configuration below forces both the generated private key and its public key to be **token objects** on the CryptoHub. This makes `keytool -genkeypair` generate the key pair on the appliance (through `C_GenerateKeyPair`) and, on a supported 6.x library, produces a usable `PrivateKeyEntry` with no CryptoHub UI step.

<Note>
  Two different configuration files are in play throughout this guide, and they are not interchangeable:

  * `fxpkcs11.cfg` is the **Futurex library** configuration. It ships in the endpoint ZIP, holds the CryptoHub connection details and TLS material, and the library finds it through its default location or the **FXPKCS11\_CFG** environment variable.
  * `pkcs11.cfg` is the **SunPKCS11 provider** configuration. You create it in this section, and you pass it to keytool with `-providerArg` and to JSign with `--keystore`.
</Note>

Choose one of the following operating systems and perform the instructions:

## Linux

Perform the following steps to configure **SunPKCS11** in Linux:

<Steps>
  <Step>
    **Locate the Futurex PKCS #11 library**:

    Confirm the location of the `libfxpkcs11.so` file available on your system. Note its full path for later use. For example, it might be located at `/usr/local/lib/fxpkcs11/libfxpkcs11.so`.
  </Step>

  <Step>
    **Create a SunPKCS11 configuration file**:

    The **SunPKCS11** provider uses a configuration file to load the Futurex PKCS #11 module. Perform the following steps:

    1. Create a file named `pkcs11.cfg` (or any name you prefer, with a `.cfg` extension). You can save this file anywhere, but a standard location would be something like `/usr/local/etc/pkcs11.cfg`.
    2. Add the following content to the file, adjusting the library path to indicate the installation location for the Futurex PKCS #11 library on your system:

    ```none expandable lines wrap title="pkcs11.cfg" theme={null}
    name = Futurex
    library = /usr/local/lib/fxpkcs11/libfxpkcs11.so
    slotListIndex = 0

    attributes(generate, CKO_PRIVATE_KEY, CKK_RSA) = {
        CKA_TOKEN = true
        CKA_SIGN = true
        CKA_PRIVATE = true
        CKA_SENSITIVE = true
        CKA_EXTRACTABLE = false
    }
    attributes(generate, CKO_PUBLIC_KEY, CKK_RSA) = {
        CKA_TOKEN = true
        CKA_VERIFY = true
    }
    ```

    <Note>
      `name`: Specify a friendly name for the Futurex PKCS #11 provider. The Java provider name becomes `SunPKCS11-<name>` (for example, `SunPKCS11-Futurex`).

      `library`: Specify the **full, absolute path** to the Futurex PKCS #11 module. A relative path prevents the provider from loading.

      `slotListIndex`: Specify the index of the Futurex PKCS #11 slot to use. This key is `slotListIndex`, not `slot`; the two are different SunPKCS11 settings and `slot` expects a slot ID rather than an index.

      The two `attributes(generate, ...)` blocks force both the private key and the public key to be token objects on the CryptoHub. **Both blocks are required** so that `keytool -list` surfaces a `PrivateKeyEntry`.
    </Note>
  </Step>

  <Step>
    **Set the FXPKCS11\_CFG environment variable**:

    Before running a standalone **keytool** command or JSign, export **FXPKCS11\_CFG** so the Futurex PKCS #11 library can locate its own configuration file (`fxpkcs11.cfg`). Point it at the `fxpkcs11.cfg` you configured in [Install and configure Futurex PKCS #11](/Integrations/CryptoHub/Code_signing/JSign/Install_and_configure_Futurex_PKCS_11).

    ```shell expandable lines wrap title="Shell" theme={null}
    export FXPKCS11_CFG=/etc/fxpkcs11.cfg
    ```

    <Note>
      `FXPKCS11_CFG` points to the **Futurex library** configuration (`fxpkcs11.cfg`), which is separate from the **SunPKCS11 provider** configuration (`pkcs11.cfg`) you created in the previous step. Passing `pkcs11.cfg` on the command line (with `-providerArg`) is not enough on its own; without `FXPKCS11_CFG`, the token does not appear.
    </Note>
  </Step>

  <Step>
    **Verify the configuration:**

    Run the following Java **keytool** command in a terminal to verify that you configured the **SunPKCS11** provider correctly to interact with the Futurex PKCS #11 library. The `-providerArg` flag passes the `pkcs11.cfg` file you created:

    ```shell expandable lines wrap title="Shell" theme={null}
    keytool -list -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /usr/local/etc/pkcs11.cfg -providerName SunPKCS11-Futurex
    ```

    <Note>
      All three provider flags are required, and they are case-sensitive: `-providerClass`, `-providerArg`, and `-providerName`. Lowercase spellings such as `-providerclass` are not recognized, and omitting `-providerName` leaves the provider unnamed, which prevents keytool from generating the key pair on the appliance.
    </Note>

    <Check>
      If successful, you see a line similar to `Your keystore contains [number] entries`. Once you generate a key pair in the next section, this command also lists a `PrivateKeyEntry` for it.
    </Check>
  </Step>
</Steps>

<Note>
  **Optional: register the provider statically in `java.security`.** JSign accepts the SunPKCS11 provider configuration directly through `--keystore` and builds the provider itself, and passing the three provider flags on each **keytool** command covers the key-generation steps. Static registration is not required for this workflow. You only need it when you operate in **FIPS mode** or when another application loads the SunPKCS11 provider without accepting a configuration path. To register it, add the following line to `$JAVA_HOME/conf/security/java.security`, using **the next available provider number** (do not reuse an existing number):

  ```none expandable lines wrap title="java.security" theme={null}
  security.provider.N=SunPKCS11 /usr/local/etc/pkcs11.cfg
  ```

  Replace `N` with the next unused index in the `security.provider.*` list already in the file.
</Note>

## Windows

Perform the following steps to configure **SunPKCS11** in Windows:

<Steps>
  <Step>
    **Locate the JDK installation directory**:

    Find the path to your JDK installation. This is typically something similar to `C:\Program Files\Java\jdk-<version>`.
  </Step>

  <Step>
    **Create a configuration file for SunPKCS11**:

    The **SunPKCS11** provider uses a configuration file to load the Futurex PKCS #11 module. Create a file named `pkcs11.cfg` (or any other name you prefer, with a `.cfg` extension).

    Add the following content to the file, adjusting the library path to point to where you installed the Futurex PKCS #11 library on your system:

    ```none expandable lines wrap title="pkcs11.cfg" theme={null}
    name = Futurex
    library = C:/Program Files/Futurex/fxpkcs11/fxpkcs11.dll
    slotListIndex = 0

    attributes(generate, CKO_PRIVATE_KEY, CKK_RSA) = {
        CKA_TOKEN = true
        CKA_SIGN = true
        CKA_PRIVATE = true
        CKA_SENSITIVE = true
        CKA_EXTRACTABLE = false
    }
    attributes(generate, CKO_PUBLIC_KEY, CKK_RSA) = {
        CKA_TOKEN = true
        CKA_VERIFY = true
    }
    ```

    <Warning>
      Write the `library` path with **forward slashes**, as shown. SunPKCS11 reads this file with Java property escaping rules, so a Windows path written with single backslashes fails to resolve. Do not convert the path to backslashes.
    </Warning>

    <Note>
      Specify the **full, absolute path** to `fxpkcs11.dll` on the `library` line. Use `slotListIndex`, not `slot`. The two `attributes(generate, ...)` blocks are both required so that `keytool -list` surfaces a `PrivateKeyEntry`.
    </Note>
  </Step>

  <Step>
    **Set the FXPKCS11\_CFG environment variable**:

    Before running a standalone **keytool** command or JSign, set **FXPKCS11\_CFG** so the Futurex PKCS #11 library can locate its own configuration file (`fxpkcs11.cfg`). The Futurex PKCS #11 module looks for `fxpkcs11.cfg` in `C:\Program Files\Futurex\fxpkcs11` by default; if you store it elsewhere, set the machine-wide variable in an **elevated** Command Prompt as described in [Install and configure Futurex PKCS #11](/Integrations/CryptoHub/Code_signing/JSign/Install_and_configure_Futurex_PKCS_11):

    ```shell expandable lines wrap title="Command Prompt" theme={null}
    setx FXPKCS11_CFG "C:\Program Files\Futurex\fxpkcs11\fxpkcs11.cfg" /M
    ```

    <Warning>
      Newly set environment variables are only visible to **new** processes. Close and reopen Command Prompt/PowerShell before running **keytool**.
    </Warning>
  </Step>

  <Step>
    **Verify the configuration**:

    Open a command prompt and run the following java **keytool** command to verify that you configured the **SunPKCS11** provider correctly to interact with the Futurex PKCS #11 library. The `-providerArg` flag passes the `pkcs11.cfg` file you created:

    ```shell expandable lines wrap title="Command Prompt" theme={null}
    keytool -list -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg C:\path\to\pkcs11.cfg -providerName SunPKCS11-Futurex
    ```

    <Note>
      All three provider flags are required, and they are case-sensitive: `-providerClass`, `-providerArg`, and `-providerName`. Lowercase spellings such as `-providerclass` are not recognized, and omitting `-providerName` leaves the provider unnamed, which prevents keytool from generating the key pair on the appliance.
    </Note>

    <Check>
      If successful, you see a line similar to `Your keystore contains [number] entries`. Once you generate a key pair in the next section, this command also lists a `PrivateKeyEntry` for it.
    </Check>
  </Step>
</Steps>

<Note>
  **Optional: register the provider statically in `java.security`.** JSign accepts the SunPKCS11 provider configuration directly through `--keystore` and builds the provider itself, and passing the three provider flags on each **keytool** command covers the key-generation steps. Static registration is not required for this workflow. You only need it when you operate in **FIPS mode** or when another application loads the SunPKCS11 provider without accepting a configuration path. To register it, open `%JAVA_HOME%\conf\security\java.security` and add the following line, using **the next available provider number** (do not reuse an existing number). Use double backslashes for the path:

  ```none expandable lines wrap title="java.security" theme={null}
  security.provider.N=SunPKCS11 C:\\path\\to\\pkcs11.cfg
  ```

  Replace `N` with the next unused index in the `security.provider.*` list already in the file.
</Note>