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 on Linux. 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 Curity cannot use the 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.

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.

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.

Optional: register the provider statically in java.security. Curity loads the SunPKCS11 provider itself at run time through its own Library path configuration (see the Library field in Configure Curity to use the CryptoHub for TLS), and the standalone keytool commands accept the three provider flags (-providerClass, -providerArg, -providerName), so static registration is optional. You only need it when an application loads the SunPKCS11 provider without accepting the flags or when you operate in FIPS mode. 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.

​Linux

Linux