Troubleshoot Smallstep step-ca - Futurex Documentation

Match the exact error to the corrective action below. Preserve the first failing application and FxChlibs log lines before changing the configuration.

`unsupported kms type 'pkcs11': step-ca is compiled without cgo or PKCS11 support`

Cause: The standard step-ca package or release binary is running. It cannot load a native PKCS #11 module. Fix: Stop that process and run the pinned HSM image:

Shell

sudo docker pull smallstep/step-ca:0.30.2-hsm
sudo docker run --rm \
  --entrypoint /usr/local/bin/step-ca \
  smallstep/step-ca:0.30.2-hsm version

The version command reports Smallstep CA/0.30.2. Then repeat Start step-ca.

`Please enter User PIN` from `pkcs11-tool`

Cause: OpenSC initiated C_Login before a private-key operation. The Smallstep direct-loader route does not use that login model. Fix: Do not add --login, pin-value, or pin-source. Use step kms sign for the Smallstep signing check and keep the endpoint UserPass credential in protected cryptohub.json.

Shell

source /etc/step-ca/cryptohub.env
export CHLIBS_CONFIG

step kms key \
  --kms "$STEP_KMS_URI" \
  "$STEP_INTERMEDIATE_KEY"

The command prints the intermediate public key without prompting for a PIN.

`error initializing PKCS#11: could not open PKCS#11`

Cause: Smallstep cannot load the module or its endpoint configuration. A missing CHLIBS_CONFIG produces this error before key access. Fix: Verify the environment, module, configuration, and referenced TLS files:

Shell

source /etc/step-ca/cryptohub.env
export CHLIBS_CONFIG

test -r "$CHLIBS_CONFIG"
test -x "$FUTUREX_DIR/libcryptohub-pkcs11.so"
ldd "$FUTUREX_DIR/libcryptohub-pkcs11.so" | grep 'not found' && exit 1 || true

sudo jq -e '
  .cryptohubs[0].tls.verify == true and
  .authentication.users[0].username != "" and
  .authentication.users[0].password != ""
' "$CHLIBS_CONFIG" >/dev/null

All commands exit with status 0 when the module and endpoint configuration are available. For a container failure, also confirm that /opt/futurex is mounted at the same path inside the container.

`Log file ... is not writable; using temporary log file`

Cause: A host process created the log without group-write permission before the container started. Fix: Restore the runtime group and file mode, then restart the container:

Shell

sudo chown root:step-ca /var/log/futurex/smallstep-chlibs.log
sudo chmod 0660 /var/log/futurex/smallstep-chlibs.log
sudo docker restart stepca

Run another certificate issuance. The host log now gains new C_SignInit and C_SignFinal entries.

`x509: provided PrivateKey doesn't match parent's PublicKey`

Cause: ca.json references one CryptoHub key while intermediate_ca.crt contains a different public key. This often occurs when the software intermediate from step ca init remains in place. Fix: Reissue the intermediate certificate with the exact STEP_INTERMEDIATE_KEY, then compare both public keys before replacing the certificate. Follow Configure step-ca to use CryptoHub. Do not delete or replace the CryptoHub key until the public-key comparison and root-chain verification pass.

The container reports a missing path under `/home/step/.step`

Cause: ca.json still contains host paths such as /var/lib/smallstep/.step/db. Those paths do not exist in the container. Fix: Set root, crt, and db.dataSource to their /home/step/.step/ paths, then restart:

Shell

jq '{root, crt, address, db: .db.dataSource}' \
  /var/lib/smallstep/.step/config/ca.json
sudo docker restart stepca

The output must show container paths for both certificates and the database. The health endpoint returns {"status":"ok"} after the restart.

​unsupported kms type 'pkcs11': step-ca is compiled without cgo or PKCS11 support

​Please enter User PIN from pkcs11-tool

​error initializing PKCS#11: could not open PKCS#11

​Log file ... is not writable; using temporary log file

​x509: provided PrivateKey doesn't match parent's PublicKey

​The container reports a missing path under /home/step/.step

`unsupported kms type 'pkcs11': step-ca is compiled without cgo or PKCS11 support`

`Please enter User PIN` from `pkcs11-tool`

`error initializing PKCS#11: could not open PKCS#11`

`Log file ... is not writable; using temporary log file`

`x509: provided PrivateKey doesn't match parent's PublicKey`

The container reports a missing path under `/home/step/.step`