Install and configure the CryptoHub Client Library

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

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.

Install the endpoint files

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

Shell

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

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

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.

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.

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

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

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

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

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.

​Install the endpoint files

​Inspect the endpoint configuration

​Configure the runtime paths

​Prepare the log path

​Validate the installed runtime

Install the endpoint files

Inspect the endpoint configuration

Configure the runtime paths

Prepare the log path

Validate the installed runtime