Skip to main content
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 Java applications that load the key fail with privateKey is null. 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:
1
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.
2
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:
pkcs11.cfg
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.
3
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
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.
4
Register the library with Java:Standalone keytool commands can load the provider from the three provider flags shown in the verify step (-providerClass, -providerArg, -providerName), so static registration is optional for them. However, third-party applications that load the SunPKCS11 provider themselves (rather than accepting the provider flags on the command line) require the provider to be registered statically in java.security. Register it as follows.Open the java.security file:
Shell
Add the following line, pointing at the pkcs11.cfg file you just created, using the next available provider number (do not reuse an existing number). Then save the file.
java.security
Replace N with the next unused index in the security.provider.* list already in the file.
FIPS mode systems: If your Linux system is running in FIPS mode, the security.provider.N line above will be ignored by the JVM. Java in FIPS mode loads providers from fips.provider.N entries only.Check whether FIPS mode is enabled:
If the command returns 1, FIPS mode is on. In that case, append the Futurex provider as a new fips.provider.N entry, using the next free index in the existing list. Do not modify fips.provider.1, and do not point it at your Futurex pkcs11.cfg.On a stock Red Hat Enterprise Linux 9 JDK the list runs from fips.provider.1 through fips.provider.7, so the Futurex entry becomes fips.provider.8:
fips.provider.1 must keep pointing at ${java.home}/conf/security/nss.fips.cfg. In FIPS mode the SUN provider registers no MessageDigest implementations at all, which makes the NSS provider on that line the only software digest source in the JVM. Replacing it removes SHA-384 and every other digest from the entire JVM, which breaks signing, TLS, and jarsigner for all applications on that JDK.Keep the numbering contiguous. The loader stops at the first missing index, so a gap silently drops every provider after it.To avoid editing the JDK’s own java.security, put your entries in a separate file and pass it on the command line with -Djava.security.properties=/[pathTo]/fips-futurex.properties instead.For the full procedure, including the token-login behavior that FIPS mode imposes on network HSMs, see Configure the provider in FIPS mode. Save the file, then continue to the verification step.
5
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
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:
1
Locate the JDK installation directory:Find the path to your JDK installation. This is typically something similar to C:\Program Files\Java\jdk-<version>.
2
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
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.
3
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
Newly set environment variables are only visible to new processes. Close and reopen Command Prompt/PowerShell before running keytool.
4
Register the library with Java:Standalone keytool commands can load the provider from the three provider flags shown in the verify step (-providerClass, -providerArg, -providerName), so static registration is optional for them. However, third-party applications that load the SunPKCS11 provider themselves (rather than accepting the provider flags on the command line) require the provider to be registered statically in java.security. Register it as follows.Open the java.security file in a text editor. The file is usually located at %JAVA_HOME%\conf\security\java.security.Add the following line, pointing at the pkcs11.cfg file you just created, using the next available provider number (do not reuse an existing number). Then save the file.
Use double backslashes for the path.
java.security
Replace N with the next unused index in the security.provider.* list already in the file.
5
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
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.

​
Generate a key pair

Use Java keytool to generate a new key pair on the CryptoHub. On FXPKCS11 6.0 rev dc27 or later, this single command generates the key pair on the CryptoHub (through C_GenerateKeyPair) and produces a usable PrivateKeyEntry with no CryptoHub UI step.
1
Confirm FXPKCS11_CFG is set (see the configuration steps above) so the Futurex PKCS #11 library can locate its own configuration file (fxpkcs11.cfg).
2
Execute the following command, passing the pkcs11.cfg file you created with -providerArg. Set -alias and -dname to a value that identifies this key. The example uses the Linux pkcs11.cfg path; on Windows, substitute your pkcs11.cfg path:
Text
The keytool application generates the key pair on the CryptoHub and self-signs a certificate for it. With no -storepass on the command line, keytool prompts for the KeyStore password.
3
When prompted for the KeyStore password, enter the CryptoHub identity password (PKCS #11 PIN) configured inside the <CRYPTO-OPR-PASS> tag in the fxpkcs11.cfg file.
Run the following keytool command to confirm the key pair generated on the CryptoHub and lists a PrivateKeyEntry. The -providerArg flag passes your pkcs11.cfg file:
Shell
The response is similar to the following:
Shell
The CryptoHub assigns the on-token key its own alias in the form <alias>-<id>:<alias> (for example, generic-demo-1784141140:generic-demo), where <id> is generated per key. This alias, not the short -alias value you passed to keytool -genkeypair, is what downstream tools must reference. Copy the exact alias from this keytool -list output for any application that operates on the key.