Before you begin
Collect these non-secret facts:- FXCL package version and OpenSSL family
- Operating system and architecture
- Java version, when applicable
- CryptoHub version
- Native Host API address, port, and expected TLS server name
- Key-store retrievable setting and key usage
- Token-profile client-side setting, algorithm, key store, and active key name
C++ build errors
Missing OpenSSL version definition
-DFXCL_OSSL_3 when you use the FXCL OpenSSL 3 package.
Cannot find libfxcl
/usr/lib/libfxcl.so exists and that the linker searches /usr/lib.
Java runtime errors
UnsatisfiedLinkError
Cause: Java foundfxcl-java.jar but could not load the native FXCL library.
Action: Confirm /usr/lib/libfxcl.so exists and start Java with:
TLS and connection errors
Connection fails before authentication
Cause: The application selected the wrong port, CA, server identity, or OpenSSL package family. Action:- Confirm CryptoHub publishes the Native Host API on port 2001.
- Load the CryptoHub production CA, not the web-management CA.
- Connect with the name in the production certificate.
- Confirm the FXCL package matches the host OpenSSL family and architecture.
Authentication errors
USER NOT LOGGED IN
Cause: The key or profile operation ran before the Host API login completed. Action: Authenticate withRKLO. If the API-key response reports LN=0, send a separate [AORKLO;LN1;] request on the same connection. Require AN=Y and LN=1 before the operation.
INVALID PERMISSIONS
Cause: The identity’s partition does not permit the operation, or the partition does not expose the Excrypt port. Action: Confirm the identity is assigned to the intended non-management partition, the partition permits Excrypt access, and the required Host API commands and key permissions are enabled.Key-store errors
Client-side encryption cannot retrieve a key
Cause: The key store is non-retrievable or has no active key. Action: UsesetRetrievable(true) only for an approved client-side key store. Confirm that key-store creation or rotation produced an active key.
Remote encryption rejects the store
Cause: The remote operation targets a retrievable key, or the key usage does not permit encryption and decryption. Action: Use a non-retrievableDEK key store for CryptoHub-backed encryption and confirm RKED is enabled.
Decryption fails after rotation
Cause: The application selected only the current active key and lost the identifier for the key that produced the ciphertext. Action: Store the key identifier and cipher context with the ciphertext, or use a DPM header and the matching header-aware decrypt path.Tokenization errors
USER NOT LOGGED IN on TOKA or TOKG
Cause: CryptoHub did not accept the deployed identity’s token-operation execution context. An identity can manage the key store and profile but still fail a token operation. Action: Authenticate the identity again and run bounded syntheticTOKA and TOKG operations. Confirm the role and object permissions before you change them. Do not widen a production identity only because key-store or profile management succeeds.
FAILED TO RETRIEVE ENCRYPTION KEY
Cause: The tokenization profile does not have a valid active encryption key, or the key was deleted. Action: Bind both objects before you create the server-side profile:keyStore can create a profile that later fails when TOKA or TOKG resolves the encryption key.
FF1 REQUIRES HSM TRUSTED KEYS
Cause: The FF1 profile uses a retrievable client-side store. Action: Use a non-retrievable, HSM-trusted key store for server-side FF1. Use the validated FF3-1 path for client-side tokenization.INVALID KEY GROUP
Cause: The key-store protection model does not match the profile’s client-side setting. Action:- For
clientSide=true, use a retrievable key store. - For
clientSide=false, use a non-retrievable HSM-trusted key store.
HSM LICENSE MISSING
Cause: The profile and active key reached the Anchor HSM, but the Anchor does not have both required FPE features. Action: Enable Format-Preserving Encryption and Format-Preserving Encryption FF1 on the approved Anchor. Do not work around this error by widening application permissions or making the key retrievable.Detokenization response is empty
Cause: The application reused theRemoteTokenizeParams instance that completed tokenization. FXCL updates that object with the selected key.
Action: Create a new profile-only RemoteTokenizeParams instance for detokenization. Do not pass the key returned by getKey() to the detokenization constructor.
VERIFICATION NOT SUPPORTED
Cause: The operation requests token verification, but the profile’s verification length is zero. Action: Set a nonzero verification length or disable the verification request.Verify the repair
Repeat only the failing bounded operation. Require the operation to advance past its prior failure layer:- TLS repair: verified connection completes.
- Authentication repair:
RKLOreportsAN=YandLN=1. - Key-store repair: the active key or remote operation resolves successfully.
- Profile repair: the error advances past key retrieval.
- HSM license repair: remote tokenization completes and detokenization recovers the original value.