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.

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 for how to obtain dc27+.

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:

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

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.

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.

Shell

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.

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.

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

keytool -list -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /usr/local/etc/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.

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
}

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.

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:

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.

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.

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.

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:

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.

​Linux

​Windows

Linux

Windows