Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.futurex.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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.
1
Create a new directory. We would recommend a directory with a path similar to: /usr/local/lib/fxpkcs11/java
2
Copy the libfxpkcs11.so file to the newly created directory
3
Edit the pkcs11.cfg file. If the user followed the guide, the file would be found in /usr/local/etc
4
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
5
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