Troubleshooting - Futurex Documentation

Each entry below names the error string you see, then the cause and the fix. Start with traffic logging: for any failure involving the CryptoHub, it turns an unexplained rejection into the exact command and the appliance’s response.

Enable Futurex traffic logging first

Symptom: A CryptoHub operation is refused and no local log explains why. Cause: Endpoint bundles ship with Futurex traffic logging disabled, so the module records that a request failed but not what the appliance said about it. Solution: Enable both settings in /etc/fxpkcs11.cfg:

fxpkcs11.cfg

<LOG-TRAFFIC>YES</LOG-TRAFFIC>
<LOG-TEMPLATES>YES</LOG-TEMPLATES>

Reproduce the failure, then read the log at the path set in LOG-FILE:

Shell

sudo grep -n 'AOERRO' /tmp/fxpkcs11.log | tail -20

Read the full AOERRO line rather than stopping at the first failure token. The line names the exact missing permission, for example:

AOERRO;ANP;BBNO PERMISSION;ERNo permission of 'CertManage:Export'.

Denials also chain: each one surfaces only after the previous permission is granted, so expect to repeat this cycle until the role holds all six permissions from Before you start.

Turn both settings back off after diagnosis. Traffic logging is verbose and records request detail.

load-token reports success=no

Symptom: swanctl --load-creds --raw returns load-token reply {success=no errmsg=loading private key from token failed}. Cause: charon reached the Futurex module but could not use the key. One of four things is wrong. Solution: Work through these in order:

AppArmor. Check sudo dmesg | grep -i 'apparmor.*DENIED'. This is the most common cause, and it produces no other symptom. Confirm /etc/apparmor.d/local/usr.lib.ipsec.charon is not empty — an empty file parses and reloads cleanly while still denying charon. See Configure AppArmor for charon.
Wrong handle. Confirm the object ID matches the responder key: pkcs11-tool --list-objects --type privkey --id 02 -v.
Wrong PIN. Confirm the pin value in swanctl.conf matches CRYPTO-OPR-PASS in fxpkcs11.cfg.
Module name mismatch. The module value in swanctl.conf must match the module name in strongswan.conf, which is futurex in this guide.

CKR_TEMPLATE_INCONSISTENT during key generation

Symptom: pkcs11-tool --keypairgen fails with CKR_TEMPLATE_INCONSISTENT. The message names no permission and no attribute. Cause: The endpoint role is missing CertManage:Add. On CryptoHub 7.0.3.x, asymmetric key creation is authorized under the CertManage permission family, not under Keys. Keys:Add authorizes symmetric key creation only, so a role with Keys:Add and no CertManage:Add looks correct but cannot create an RSA key pair. Solution: Grant CertManage:Add to the endpoint role in Identity and Access > Roles, then retry. The error is generated client-side, so it does not reflect what the appliance reported; enable traffic logging as described above to see the appliance’s own INSUFFICIENT PERMISSIONS response.

pkcs11-tool —list-objects returns no output

Symptom: pkcs11-tool --list-objects prints nothing at all. No error, no empty-list message, exit status zero. It looks as though the key was never created. Cause: The role is missing CertManage:Export, CertManage:Export Private Key, or both. The key exists on the appliance; the client cannot enumerate it. Solution: Grant both permissions to the endpoint role, then retry. No private key material is exported by either permission — the module needs them to list token objects.

unknown command ‘pki’

Symptom: ipsec pki reports /usr/sbin/ipsec: unknown command 'pki', even though ipsec --help lists pki among its subcommands. Cause: The strongswan-pki package is not installed. The help text is generated from a static list rather than from the installed subcommands, so it advertises a command that is not present. Solution: Install it:

Shell

sudo apt install strongswan-pki

charon cannot load the Futurex module at all

Symptom: charon starts normally but no loaded PKCS#11 or futurex line ever appears in the log, and swanctl --load-creds cannot find the token. Cause: The libstrongswan-pkcs11.so plugin is absent. It ships only in the libstrongswan-extra-plugins package, not in the base strongswan package. Solution: Confirm the plugin is missing, then install the package:

Shell

ls /usr/lib/ipsec/plugins | grep pkcs11
sudo apt install libstrongswan-extra-plugins
sudo systemctl restart strongswan-starter

/var/log/charon-debug.log: No such file or directory

Symptom: A grep command in this guide fails because /var/log/charon-debug.log does not exist. Cause: charon does not write that file by default. The charon.filelog stanza was never added, so there is no log to read. This reads as a failure of the integration when it is only an absent log file. Solution: Add the logging stanza described in Configure strongSwan to load the Futurex PKCS #11 module, then restart strongSwan and reproduce the step you were verifying.

configTest or PKCS11Manager reports permission denied

Symptom: Running configTest or PKCS11Manager returns Permission denied. Cause: The test utilities are not executable after the endpoint zip is extracted. Solution: Add the execute bit:

Shell

sudo chmod +x /usr/local/lib/fxpkcs11/configTest /usr/local/lib/fxpkcs11/PKCS11Manager

swanctl reports connection refused

Symptom: swanctl returns a connection refused error for /var/run/charon.vici. Cause: charon has not finished starting, so the VICI socket does not exist yet. Solution: Inspect the service state:

Shell

sudo systemctl status strongswan-starter --no-pager -l
pgrep -af 'charon|starter' || true
sudo ss -xl | grep -E 'charon|vici' || true

Wait for the VICI socket before loading configuration:

Shell

sudo systemctl restart strongswan-starter

for i in $(seq 1 20); do
    if sudo ss -xl | grep -q /var/run/charon.vici; then
        echo "VICI socket is ready"
        break
    fi
    sleep 1
done

sudo swanctl --load-all --debug 2

CHILD_SA config not found

Symptom: Initiating reports that the CHILD_SA net was not found. Cause: The connection did not load, or the child name does not match. Solution: Reload and compare the names:

Shell

sudo cat /etc/swanctl/swanctl.conf
sudo swanctl --load-all --debug 2
sudo swanctl --list-conns

Confirm the child name in the configuration matches the name passed to --initiate --child.

HSM key ID not found

Symptom: ipsec pki cannot locate the HSM key. Cause: Either the object does not exist, the role cannot enumerate it, or the command is missing --type priv. Solution: Confirm the object exists:

Shell

read -rsp "HSM PIN: " HSM_PIN
echo

sudo env FXPKCS11_CFG=/etc/fxpkcs11.cfg HOME=/root \
pkcs11-tool \
--module /usr/local/lib/fxpkcs11/libfxpkcs11.so \
--login --pin "$HSM_PIN" \
--list-objects --type privkey --id 01 -v

unset HSM_PIN

If the object list is empty with no error, the role is missing CertManage:Export and CertManage:Export Private Key. Then confirm pki can read the public key through the module:

Shell

sudo env FXPKCS11_CFG=/etc/fxpkcs11.cfg HOME=/root \
ipsec pki --pub \
--type priv \
--keyid 01 \
--debug 4 \
> /tmp/ca-01-pub.der

ls -lh /tmp/ca-01-pub.der

If that succeeds but pki --self fails, confirm you passed --type priv.

Authentication fails during IKE_AUTH

Symptom: The IKE_SA reaches IKE_AUTH and then fails authentication. Cause: The identities do not agree between the two peers or between an id and its certificate. Solution: Confirm the identities agree. Each host’s local id must equal the other host’s remote id, and each id must match the subject DN of the corresponding certificate. Print the certificates with ipsec pki --print --in <file> and compare.

Old certificates and keys loading

Symptom: The logs reference certificates or keys you no longer use. Cause: strongSwan loads every file in /etc/swanctl/x509, /etc/swanctl/x509ca, and /etc/swanctl/private. Solution: Leftover test files do not necessarily block the tunnel, but they make the logs hard to read. Remove unused files, then reload with --clear so charon drops what it already holds:

Shell

sudo swanctl --load-all --clear --debug 2

​Enable Futurex traffic logging first

​load-token reports success=no

​CKR_TEMPLATE_INCONSISTENT during key generation

​pkcs11-tool —list-objects returns no output

​unknown command ‘pki’

​charon cannot load the Futurex module at all

​/var/log/charon-debug.log: No such file or directory

​configTest or PKCS11Manager reports permission denied

​swanctl reports connection refused

​CHILD_SA config not found

​HSM key ID not found

​Authentication fails during IKE_AUTH

​Old certificates and keys loading

Enable Futurex traffic logging first

load-token reports success=no

CKR_TEMPLATE_INCONSISTENT during key generation

pkcs11-tool —list-objects returns no output

unknown command ‘pki’

charon cannot load the Futurex module at all

/var/log/charon-debug.log: No such file or directory

configTest or PKCS11Manager reports permission denied

swanctl reports connection refused

CHILD_SA config not found

HSM key ID not found

Authentication fails during IKE_AUTH

Old certificates and keys loading