Configure SunPKCS11 to use the 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. 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:

None

name = Futurex
library = /usr/local/lib/fxpkcs11/libfxpkcs11.so
slotListIndex = 0

# PRIVATE KEY
attributes(generate,CKO_PRIVATE_KEY,*) = {
    CKA_SIGN = true
    CKA_VERIFY = true
    CKA_TOKEN = true
    CKA_PRIVATE = true
    CKA_SENSITIVE = true
    CKA_EXTRACTABLE = false
}

name: Specify a friendly name for the Futurex PKCS #11 provider. library: Specify the full path to the Futurex PKCS #11 module. slotListIndex: Specify the default Futurex PKCS #11 slot number.

Register the library with Java:Open the java.security file.

Shell

sudo vim $JAVA_HOME/conf/security/java.security

Add the following line with the path of the pkcs11.cfg file you just created to the SunPKCS11 security provider line. Then save the file.

None

security.provider.12=SunPKCS11 /[pathTo]/pkcs11.cfg

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:

cat /proc/sys/crypto/fips_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=SunPKCS11 ${java.home}/conf/security/nss.fips.cfg
fips.provider.2=SUN
fips.provider.8=SunPKCS11 /[pathTo]/pkcs11.cfg

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.

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:

Shell

keytool -list -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerName SunPKCS11-Futurex 

If successful, you should see a line similar to this: Your keystore creation contains [number] entries.

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:

None

name = Futurex
library = C:/Program Files/Futurex/fxpkcs11/fxpkcs11.dll
slotListIndex = 0

# PRIVATE KEY
attributes(generate,CKO_PRIVATE_KEY,*) = {
    CKA_SIGN = true
    CKA_VERIFY = true
    CKA_TOKEN = true
    CKA_PRIVATE = true
    CKA_SENSITIVE = true
    CKA_EXTRACTABLE = false
}

Register the library with Java:Open the the java.security file in a text editor. The file is usually located at %JAVA_HOME%\conf\security\java.securityAdd the following line with the path of the pkcs11.cfg file you just created to the SunPKCS11 security provider line. Then, save the file.

Use double backslashes for the path.

None

security.provider.12=SunPKCS11 C:\\[pathTo]\\pkcs11.cfg

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:

Shell

keytool -list -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerName SunPKCS11-Futurex

If successful, you should see a line similar to this: Your keystore contains [number] entries.

​Linux

​Windows

Linux

Windows