Common Issues and How to Resolve Them
|
Symptom / Error |
Possible Cause |
Resolution |
|---|---|---|
|
Handshake fails with "no certificate for SNI" |
Certificate not delivered, incorrect cluster binding, or certificate not yet available on the gateway node. |
Verify that the certificate is bound to the correct cluster and that the gateway node has synchronized successfully. |
|
Software-key certificate fails with a "decrypt key" error |
The STOA_ENCRYPTION_KEY value differs between the management console and gateway node. |
Ensure that the same STOA_ENCRYPTION_KEY value is configured on all nodes and the management console. |
|
HSM-managed certificate handshake returns HTTP 502 |
OpenSSL PKCS#11 provider is not installed or configured. |
Install and configure the PKCS#11 provider or use the software-key deployment model. |
|
pkcs11-tool -L cannot connect or no slots are displayed. |
CS_PKCS11_R3_CFG is not set, or the HSM device address is incorrect. |
Verify the configuration file location, environment variable, and HSM device address. |
|
Connection test reports "no token slot found with label X" |
Incorrect token label configured. |
Configure the token label as CryptoServer PKCS11 Token instead of the slot description (SLOT_0000). |
|
Connection test reports "cannot load PKCS#11 module" |
PKCS#11 library is missing or the configured path is incorrect. |
Verify that libcs_pkcs11_R3.so is installed and that the configured module path is correct. |
|
HSM support unavailable (HTTP 501) |
The deployed gateway image does not include HSM support. |
Deploy the HSM-enabled build of Paraview API Security Gateway. |
|
Login succeeds, but key generation fails with 0xB0A60001 |
An administrator account was used instead of a Cryptographic User. |
Use a Cryptographic User account with the required permissions. |
|
Login fails with 0xb906100e |
Incorrect credential type used (password versus key file). |
Use password-based login for user credentials and key-file authentication where applicable. |
|
Operation fails with CKR_PIN_TOO_WEAK |
Initial PIN was not changed after slot initialization. |
Change the initial PIN to a strong production PIN. |
|
TLS handshake reports an unsupported algorithm or version. |
OpenSSL version is earlier than 3.5. |
Upgrade the client or gateway OpenSSL installation to version 3.5 or later. |
Troubleshooting
In-depth troubleshooting: Temporarily set Logging to 4 in cs_pkcs11_R3.cfg . The vendor library then writes every C_* call and every Utimaco::HSM::DeviceException (error_code=…) to the file given by LogFile , which pinpoints the PKCS#11 call at which the failure occurs.