Configure SunPKCS11 to use the Futurex PKCS11 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. JSign uses it to reach the signing key on the CryptoHub.

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 for how to obtain a supported build.

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.

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.

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

Linux

Perform the following steps to configure SunPKCS11 in Linux:

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.

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

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

pkcs11.cfg

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
}

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.

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.

Shell

export FXPKCS11_CFG=/etc/fxpkcs11.cfg

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.

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

keytool -list -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /usr/local/etc/pkcs11.cfg -providerName SunPKCS11-Futurex

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.

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.

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

java.security

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.

Windows

Perform the following steps to configure SunPKCS11 in Windows:

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

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:

pkcs11.cfg

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
}

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.

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.

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:

Command Prompt

setx FXPKCS11_CFG "C:\Program Files\Futurex\fxpkcs11\fxpkcs11.cfg" /M

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

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:

Command Prompt

keytool -list -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg C:\path\to\pkcs11.cfg -providerName SunPKCS11-Futurex

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.

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:

java.security

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.

​Linux

​Windows

Linux

Windows