Troubleshooting - Futurex Documentation

Runtime Errors

Symptom: Java hangs after installing and configuring SunPKCS11 with FxPKCS11

If Java and OpenSSL are pointing to the same libfxpkcs11.so, you might run into an issue where running a Java HSM-specific command will cause a hang. Error logs will look similar to:

None

[2025-12-03 17:05:58.378] | DEBUG | 73FE95AFF6C0 | waitForConnect: Blocking for up to 3000 milliseconds on socket connect.
[2025-12-03 17:05:58.379] | INFO  | 73FE95AFF6C0 | establishConnectionIP: Socket 6 connects to 10.0.5.111:9100.
[2025-12-03 17:05:58.379] | INFO  | 73FE95AFF6C0 | setupSSL: Setting up SSL. (Slot 0)
[2025-12-03 17:05:58.645] | DEBUG | 73FF0EDFF6C0 | C_Initialize: Blocking until surveyor has completed its initial HSM check (10s Max).
[2025-12-03 17:06:09.302] |*ERROR*| 73FF0EDFF6C0 | C_Initialize: Surveyor failed to complete its initial HSM check within the timeout.
[2025-12-03 17:06:09.302] | INFO  | 73FF0EDFF6C0 | C_Initialize: FxPKCS11 library initialized.
[2025-12-03 17:06:09.302] | INFO  | 73FF0EDFF6C0 | C_Initialize: FxPKCS11 library version 5.15 (Revision: 4fee).
[2025-12-03 17:06:09.302] | INFO  | 73FF0EDFF6C0 | C_Initialize: Platform: Linux

Solution

Make sure that Java points to a different libfxpkcs11.so by editing the pkcs11.cfg file.

Create a new directory. We would recommend a directory with a path similar to: /usr/local/lib/fxpkcs11/java

Copy the libfxpkcs11.so file to the newly created directory

Edit the pkcs11.cfg file. If the user followed the guide, the file would be found in /usr/local/etc

Edit the library line so that it will point to copied libfxpkcs11.so

None

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

Retest Java command to make sure that it is now able to succeed

Verification

To retest, youi can run a basic HSM + Java command

Shell

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

A successful output should look like:

None

Keystore type: PKCS11
Keystore provider: SunPKCS11-Futurex

Your keystore contains 0 entries

​Runtime Errors

​Symptom: Java hangs after installing and configuring SunPKCS11 with FxPKCS11

​Solution

​Verification

Runtime Errors

Symptom: Java hangs after installing and configuring SunPKCS11 with FxPKCS11

Solution

Verification