> ## 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.

# Troubleshooting

> Diagnose and resolve the common failure modes of the strongSwan and CryptoHub integration.

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`:

```cfg expandable lines wrap title="fxpkcs11.cfg" theme={null}
<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 expandable lines wrap title="Shell" theme={null}
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](/Integrations/CryptoHub/VPN/strongSwan/Before_you_start).

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

## 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:

1. **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](/Integrations/CryptoHub/VPN/strongSwan/Configure_AppArmor_for_charon).
2. **Wrong handle.** Confirm the object ID matches the responder key: `pkcs11-tool --list-objects --type privkey --id 02 -v`.
3. **Wrong PIN.** Confirm the `pin` value in `swanctl.conf` matches `CRYPTO-OPR-PASS` in `fxpkcs11.cfg`.
4. **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 expandable lines wrap title="Shell" theme={null}
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 expandable lines wrap title="Shell" theme={null}
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](/Integrations/CryptoHub/VPN/strongSwan/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 expandable lines wrap title="Shell" theme={null}
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 expandable lines wrap title="Shell" theme={null}
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 expandable lines wrap title="Shell" theme={null}
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 expandable lines wrap title="Shell" theme={null}
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 expandable lines wrap title="Shell" theme={null}
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 expandable lines wrap title="Shell" theme={null}
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 expandable lines wrap title="Shell" theme={null}
sudo swanctl --load-all --clear --debug 2
```