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

> Step-by-step configuration of SunPKCS11 provider to integrate with Futurex PKCS #11 module.

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.

<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 Apache Tomcat cannot load the server key. See [Before you start](/Integrations/CryptoHub/TLS_offloading/Apache_Tomcat/Before_you_start) for how to obtain dc27+.
</Warning>

The corrected 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 dc27+, produces a usable `PrivateKeyEntry` with no CryptoHub UI step.

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 default Futurex PKCS #11 slot number.

      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** on dc27+ so that `keytool -list` surfaces a `PrivateKeyEntry`.
    </Note>
  </Step>

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

    Before running a standalone **keytool** command, 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/TLS_offloading/Apache_Tomcat/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>
    **Register the provider statically in `java.security`:**

    Apache Tomcat loads the **SunPKCS11** provider itself (through `server.xml`) rather than accepting the provider flags on a command line, so static registration is **required** for the Tomcat integration. Open the `java.security` file:

    ```shell expandable lines wrap title="Shell" theme={null}
    sudo vim $JAVA_HOME/conf/security/java.security
    ```

    Add the following line, pointing to the `pkcs11.cfg` file you just created and using **the next available provider number** (do not reuse an existing number). Then save the file.

    ```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.
  </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 just 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
    ```

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

## 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
    }
    ```

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

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

    Before running a standalone **keytool** command, 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/TLS_offloading/Apache_Tomcat/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>
    **Register the provider statically in `java.security`:**

    Apache Tomcat loads the **SunPKCS11** provider itself (through `server.xml`) rather than accepting the provider flags on a command line, so static registration is **required** for the Tomcat integration. Open `%JAVA_HOME%\conf\security\java.security` in a text editor.

    Add the following line, pointing to the `pkcs11.cfg` file you just created and using **the next available provider number** (do not reuse an existing number). Use double backslashes for the path. Then save the file.

    ```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.
  </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 just 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
    ```

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