> ## 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 the CryptoHub Client Library

> Install the endpoint-delivered FxChlibs PKCS #11 module, protected configuration, TLS files, and Smallstep KMS variables on Linux.

Install the complete endpoint bundle in one protected directory. Both the host bootstrap tools and the step-ca container use this directory.

<Warning>
  The endpoint configuration contains a UserPass credential and TLS private-key material. Do not print `cryptohub.json`, copy it into an image, or make the directory world-readable.
</Warning>

## Install the endpoint files

Extract the endpoint ZIP and change to the extracted directory. Then run:

```shell title="Shell" theme={null}
sudo groupadd --system step-ca 2>/dev/null || true
sudo install -d -m 0750 -o root -g step-ca /opt/futurex
sudo install -m 0755 -o root -g root \
  libcryptohub-pkcs11.so /opt/futurex/libcryptohub-pkcs11.so
sudo install -m 0755 -o root -g root \
  pkcs11-manager /opt/futurex/pkcs11-manager
sudo install -m 0640 -o root -g step-ca \
  cryptohub.json /opt/futurex/cryptohub.json
find . -maxdepth 1 -type f \
  \( -name '*.crt' -o -name '*.pem' -o -name '*.p12' \) \
  -exec sudo install -m 0640 -o root -g step-ca -t /opt/futurex {} +
```

Confirm the module loads all shared libraries:

```shell title="Shell" theme={null}
ldd /opt/futurex/libcryptohub-pkcs11.so | grep 'not found' && exit 1 || true
```

No output means every shared-library dependency resolved.

## Inspect the endpoint configuration

Run structural checks without printing credentials:

```shell title="Shell" theme={null}
sudo jq -e '
  .global.service_uuid != "" and
  .global.key_protection == "TRUSTED" and
  .pkcs11.check_already_logged_in == true and
  (.pkcs11.default_usages.asymmetric | sort) == ["Sign", "Verify"] and
  (.pkcs11.forced_usages.asymmetric | sort) == ["Sign", "Verify"] and
  .cryptohubs[0].tls.verify == true and
  .authentication.users[0].username != "" and
  .authentication.users[0].password != ""
' /opt/futurex/cryptohub.json >/dev/null
```

The command exits with status 0 when the endpoint targets a TRUSTED Sign/Verify key and contains complete UserPass and TLS settings.

<Note>
  Do not add `pin-value`, `pin-source`, or another PKCS #11 PIN. Smallstep skips `C_Login` when the URI contains no PIN, and FxChlibs authenticates from the protected UserPass entry in `cryptohub.json`.
</Note>

## Configure the runtime paths

Create a protected environment file for the non-secret module and key references. Choose a hexadecimal key ID and a descriptive key label when prompted.

```shell title="Shell" theme={null}
read -r -p 'Intermediate key ID in hexadecimal: ' STEP_KEY_ID
read -r -p 'Intermediate key label: ' STEP_KEY_LABEL

STEP_TOKEN_LABEL=$(sudo jq -r '.cryptohubs[0].label' /opt/futurex/cryptohub.json)
STEP_TOKEN_LABEL_URI=$(printf '%s' "$STEP_TOKEN_LABEL" | jq -sRr @uri)

sudo install -d -m 0755 -o root -g root /etc/step-ca
sudo tee /etc/step-ca/cryptohub.env >/dev/null <<EOF
export FUTUREX_DIR='/opt/futurex'
export CHLIBS_CONFIG='/opt/futurex/cryptohub.json'
export STEP_TOKEN_LABEL='$STEP_TOKEN_LABEL'
export STEP_KMS_URI='pkcs11:module-path=/opt/futurex/libcryptohub-pkcs11.so;token=$STEP_TOKEN_LABEL_URI'
export STEP_KEY_ID='$STEP_KEY_ID'
export STEP_KEY_LABEL='$STEP_KEY_LABEL'
export STEP_INTERMEDIATE_KEY='pkcs11:id=$STEP_KEY_ID;object=$STEP_KEY_LABEL'
EOF
sudo chown root:root /etc/step-ca/cryptohub.env
sudo chmod 0644 /etc/step-ca/cryptohub.env
```

Load the variables into the current shell:

```shell title="Shell" theme={null}
source /etc/step-ca/cryptohub.env
```

Confirm that the KMS URI contains `module-path` and `token`, and that the key URI contains both `id` and `object`. Neither URI contains a PIN parameter.

## Prepare the log path

Create a group-writable log path for the container without relaxing the endpoint-file permissions:

```shell title="Shell" theme={null}
sudo install -d -m 0770 -o root -g step-ca /var/log/futurex
sudo touch /var/log/futurex/smallstep-chlibs.log
sudo chown root:step-ca /var/log/futurex/smallstep-chlibs.log
sudo chmod 0660 /var/log/futurex/smallstep-chlibs.log
```

The step-ca container joins the numeric `step-ca` group when it starts, so it can append to this log while the endpoint credential remains protected.

## Validate the installed runtime

```shell title="Shell" theme={null}
source /etc/step-ca/cryptohub.env
test -r "$CHLIBS_CONFIG"
test -x "$FUTUREX_DIR/libcryptohub-pkcs11.so"
test "$(stat -c '%a' /var/log/futurex/smallstep-chlibs.log)" = '660'
test "$(stat -c '%G' /var/log/futurex/smallstep-chlibs.log)" = 'step-ca'
```

All four checks exit with status 0. Continue to [Install Smallstep and the HSM image](/Integrations/CryptoHub-7.3/Certificate_Authority/Smallstep_step-ca/Install_step-ca_and_the_step_CLI).