Start step-ca - Futurex Documentation

Confirm root, crt, and db.dataSource in ca.json are rewritten to /home/step/.step/... before you run the container. The container mounts your ~/.step directory at /home/step/.step, so the host-absolute paths that step ca init wrote do not exist inside it and the container exits immediately. See Configure step-ca to use CryptoHub.

Confirm the PKCS #12 password is in your shell

The container needs PKCS11_P12 so the FXPKCS11 module can open client.p12. You pass it through from your shell, and /etc/profile.d scripts populate login shells only, so an empty variable is passed silently rather than reported as an error.

Shell

echo "$PKCS11_P12"

If this prints an empty line, the container starts and then fails to authenticate to the CryptoHub. Start a new login shell and check again before you continue. When you run the container with sudo, the variable is expanded by your own shell before sudo runs, so -e PKCS11_P12="$PKCS11_P12" still passes the value, but only if your shell holds one.

Start the CA

Run the container. Replace <CA-PASSWORD-FILE> with the path to the password file you created in Configure step-ca to use CryptoHub, for example /tmp/ca-password.txt.

Shell

sudo docker run -d --name stepca -p 9000:9000 -v "$HOME/.step:/home/step/.step" -v /usr/local/lib/fxpkcs11:/usr/local/lib/fxpkcs11:ro -v <CA-PASSWORD-FILE>:/home/step/ca-password.txt:ro -e FXPKCS11_CFG=/usr/local/lib/fxpkcs11/fxpkcs11.cfg -e PKCS11_P12="$PKCS11_P12" --entrypoint step-ca smallstep/step-ca:hsm /home/step/.step/config/ca.json --password-file /home/step/ca-password.txt

The flags carry the following meaning:

Flag	Purpose
`-p 9000:9000`	Publishes the CA’s HTTPS listener, matching the `address` value in `ca.json`.
`-v "$HOME/.step:/home/step/.step"`	Mounts the CA material and configuration at the path `ca.json` now references.
`-v /usr/local/lib/fxpkcs11:...:ro`	Mounts the FXPKCS11 module, configuration, and TLS material at the same absolute path as on the host, so the `module-path` and the rewritten `PROD-TLS-*` paths resolve unchanged.
`-v <CA-PASSWORD-FILE>:...:ro`	Makes the CA password file readable inside the container.
`-e FXPKCS11_CFG=...`	Tells the module where its configuration file is, since it is not at the default `/etc` location.
`-e PKCS11_P12="$PKCS11_P12"`	Supplies the PKCS #12 password for the mutual TLS client key.
`--entrypoint step-ca`	Overrides the image’s default startup script so the CA binary receives your arguments.
`--password-file`	Decrypts the CA material at startup. Without it, step-ca prompts for the password and a detached container has no terminal to prompt on.

Follow the container log and confirm the CA is serving:

Shell

sudo docker logs -f stepca

The startup output ends with:

Shell

Serving HTTPS on :9000 ...

Serving HTTPS on :9000 ... is the line that confirms the CA is up. If the container exits before printing it, the log line immediately above names the cause. See Troubleshooting.

Confirm the CryptoHub session

The FXPKCS11 log is the proof that the CA reached the appliance rather than falling back to something local. The module writes it to the path in the LOG-FILE setting of fxpkcs11.cfg, and falls back to /tmp/fxpkcs11.log when it cannot write to that path.

Shell

sudo docker exec stepca cat /tmp/fxpkcs11.log

The log records the module initializing, loading the TLS material from /usr/local/lib/fxpkcs11, opening a session to your CryptoHub on port 2001, and logging in:

Shell

C_Initialize: FxPKCS11 library initialized.
C_Initialize: FxPKCS11 library version 5.23
sslSetCerts: Loaded CA '/usr/local/lib/fxpkcs11/CryptoHub <number>.cer' into TLS context.
sslSetKey: Added private key '/usr/local/lib/fxpkcs11/client.p12' to TLS context.
openConnection: Established connection to HSM at Futurex.(Slot 0)

To keep the FXPKCS11 log on the host for troubleshooting after the container stops, add -v /tmp:/tmp to the run command and read /tmp/fxpkcs11.log on the host instead.

If the container exits instead of serving, check sudo docker logs stepca and see Troubleshooting.

​Confirm the PKCS #12 password is in your shell

​Start the CA

​Confirm the CryptoHub session

Confirm the PKCS #12 password is in your shell

Start the CA

Confirm the CryptoHub session