Skip to main content
Each entry below names the error string you see, then the cause and the fix.

​
unsupported kms type 'pkcs11': compiled without cgo or PKCS#11 support

Symptom: step-ca exits at startup with this message as soon as it reads the kms block in ca.json. Cause: You are running the step-ca binary from the official package or release archive. Those builds are compiled without PKCS #11 support and cannot load any PKCS #11 module. Solution: Run the CA from the smallstep/step-ca:hsm container image instead, as described in Start step-ca. Keep the host step-ca package installed for the toolchain, but do not use it to serve the CA.

​
The container exits immediately after docker run

Symptom: sudo docker ps shows no running container, and sudo docker logs stepca reports that a file or directory does not exist, naming a path under your host home directory such as /home/<user>/.step/certs/root_ca.crt or /home/<user>/.step/db. Cause: step ca init writes host-absolute paths into ca.json. The container mounts ~/.step at /home/step/.step, so those host paths do not exist inside it. Solution: Rewrite the root, crt, and db.dataSource values in ca.json to their /home/step/.step/... equivalents:
Shell
Leave the kms block’s module-path unchanged, because the FXPKCS11 directory is mounted at the same absolute path in both runtimes. Then confirm two other container requirements are in place: --entrypoint step-ca, so the image’s startup script does not swallow your arguments, and --password-file, so a detached container is not left waiting for a password prompt it cannot receive.

​
CKR_TEMPLATE_INCONSISTENT from step kms create

Symptom: step kms create --kty RSA --size 3072 fails with CKR_TEMPLATE_INCONSISTENT. Cause: The key template the step-kms-plugin sets is rejected by FXPKCS11 5.23. This is a limitation of that command against this module, not a configuration error. Solution: Generate the key with PKCS11Manager or pkcs11-tool --keypairgen, as described in Generate a CA signing key. Every later step kms, step certificate, and step-ca operation works normally against a key created that way.

​
A step kms or step certificate command cannot find the key

Symptom: step kms key, step kms sign, or step certificate create reports that it cannot find the key, even though pkcs11-tool --list-objects shows smallstep-ca-key. Cause: The PKCS #11 URI names the object but not its ID. FXPKCS11 needs both to resolve the key. Solution: Use the full URI in every command and in both ca.json references:
Text
Substitute your own ID if you chose a value other than 7101 during key generation, and use the same value everywhere.

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

Symptom: step-ca exits at startup with this message. Cause: The intermediate CA certificate at ~/.step/certs/intermediate_ca.crt does not correspond to the key that ca.json references. This happens when the software intermediate certificate from step ca init is still in place, or when the CryptoHub key was regenerated after the intermediate was issued. Solution: Reissue the intermediate certificate against the CryptoHub-resident key and copy it into place, as described in Configure step-ca to use CryptoHub. The certificate on disk and the key in ca.json must always be the same key pair.

​
could not find PKCS#11 token

Symptom: step-ca or a step kms command reports that it cannot find the token. The module loaded, but it could not reach the CryptoHub. Cause: One of the module’s inputs is missing or unresolvable, most often a configuration path, a TLS file path, or the PKCS #12 password. Solution: Check the following in order:
  1. FXPKCS11_CFG points at /usr/local/lib/fxpkcs11/fxpkcs11.cfg. For the container, confirm the -e FXPKCS11_CFG=... flag is present in the run command.
  2. PROD-TLS-KEY and both PROD-TLS-CA values in fxpkcs11.cfg are absolute paths under /usr/local/lib/fxpkcs11 and match the file names present there. Relative names resolve against the working directory, which differs between your shell and the container.
  3. PKCS11_P12 holds the PKCS #12 password. Run echo "$PKCS11_P12" in the shell you use. An empty value passes through -e PKCS11_P12="$PKCS11_P12" silently.
  4. The step-ca host can reach the CryptoHub address and port 2001 named in fxpkcs11.cfg.
Read the FXPKCS11 log for the specific failure. Its location comes from the LOG-FILE setting in fxpkcs11.cfg, and the module falls back to /tmp/fxpkcs11.log when it cannot write there:
Shell

​
step kms sign rejects the —digest flag

Symptom: step kms sign reports an unknown flag for --digest, or rejects a hexadecimal digest passed as a positional argument. Cause: step-kms-plugin 0.15.1 signs a file rather than a precomputed digest. Solution: Pass the input file with --in and the digest algorithm with --alg:
Shell

​
step kms sign —verify prints nothing

Symptom: step kms sign --verify produces signature output but no confirmation that the signature is valid. Cause: The flag reports its result through the process exit code, where 0 means valid. It prints no status word. Solution: Read the exit code, or verify independently with OpenSSL, which prints a visible result:
Shell

​
configTest reports permission denied

Symptom: Running configTest or PKCS11Manager returns Permission denied. Cause: The test utilities are not executable after the endpoint ZIP is extracted. Solution: Add the execute bit:
Shell