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

# Install and configure Futurex PKCS #11

> Install the endpoint-distributed CryptoHub Client Library and prepare its UserPass credential for strongSwan.

Install the endpoint download as one protected module, configuration, and TLS unit.

## Install the endpoint files

Extract the endpoint ZIP and change to its extracted directory. Run:

```shell theme={null}
sudo install -d -m 700 /etc/strongswan-chlibs
sudo install -m 755 libcryptohub-pkcs11.so \
  /usr/local/lib/libcryptohub-pkcs11.so
sudo install -m 755 pkcs11-manager /usr/local/bin/pkcs11-manager

sudo cp -- *.crt *.pem *.p12 /etc/strongswan-chlibs/
sudo chown -R root:root /etc/strongswan-chlibs
sudo chmod 600 /etc/strongswan-chlibs/*
```

<Check>
  Run `test -x /usr/local/lib/libcryptohub-pkcs11.so` and `sudo test -r /etc/strongswan-chlibs/client.p12`. Both commands must succeed.
</Check>

## Separate the UserPass password from the config

strongSwan calls PKCS #11 `C_Login`. Keep the endpoint username in `cryptohub.json` and deliver the endpoint password as the token PIN.

Run these commands from the extracted endpoint directory:

```shell theme={null}
ENDPOINT_PASSWORD="$(jq -r '.authentication.users[0].password' cryptohub.json)"
test -n "$ENDPOINT_PASSWORD"

printf '%s\n' "$ENDPOINT_PASSWORD" \
  | sudo install -m 600 -o root -g root /dev/stdin \
      /etc/strongswan-chlibs/token-pin

jq '
  .authentication.users |= map({username}) |
  .pkcs11.check_already_logged_in = true |
  .logging.async_logging = false
' cryptohub.json \
  | sudo install -m 600 -o root -g root /dev/stdin \
      /etc/strongswan-chlibs/cryptohub.json

unset ENDPOINT_PASSWORD
```

<Warning>
  Do not leave the password in the endpoint configuration and also configure it as the token PIN. That duplicate login state causes `CKR_USER_ALREADY_LOGGED_IN` when strongSwan loads the key.
</Warning>

## Set the service environment

```shell theme={null}
sudo install -d -m 755 \
  /etc/systemd/system/strongswan-starter.service.d

sudo tee \
  /etc/systemd/system/strongswan-starter.service.d/chlibs.conf \
  > /dev/null <<'EOF'
[Service]
Environment=CHLIBS_CONFIG=/etc/strongswan-chlibs/cryptohub.json
Environment=HOME=/root
EOF

sudo systemctl daemon-reload
```

<Check>
  Run `sudo systemctl show strongswan-starter -p Environment`. The output must include the `CHLIBS_CONFIG` setting shown in the service drop-in.
</Check>

## Verify the module

```shell theme={null}
sudo env CHLIBS_CONFIG=/etc/strongswan-chlibs/cryptohub.json \
  pkcs11-tool \
  --module /usr/local/lib/libcryptohub-pkcs11.so \
  --login \
  --pin "$(sudo cat /etc/strongswan-chlibs/token-pin)" \
  --list-token-slots
```

<Check>
  The output lists the Futurex token in slot 0.
</Check>