Craton HSM

Admin CLI

Admin CLI

craton-hsm-admin (crate: tools/craton-hsm-admin) is a local administrative client built on clap. It loads craton_hsm.toml and operates directly against the same HsmCore state that the PKCS#11 shared library and cratond use. It is intended for operators, not for application code.

Invocation

craton-hsm-admin [--config <PATH>] [--json] <COMMAND> [ARGS]

Global flags:

  • --config <PATH> -- path to craton_hsm.toml. Defaults to craton_hsm.toml in the current directory.
  • --json -- emit machine-readable JSON instead of the default human-oriented output (honoured by the subcommands that support it).

A non-zero exit status indicates failure; error messages are written to stderr.

Command Surface

craton-hsm-admin
  token
    init    --label <LABEL>
    info
  key
    list
    import  --file <PATH> --label <LABEL> --type <RSA|EC|AES>
    delete  --handle <N> [--force]
  pin
    change  [--user-type USER|SO]
    reset
  audit
    dump          [--last <N>]
    export-json
    export-ndjson
    export-syslog
    verify-chain
  status
  backup  --output <PATH>
  restore --input  <PATH>

token

Token-level management.

  • token init --label <LABEL> -- initialise a new token on the configured slot. Prompts for the Security Officer PIN. Equivalent to C_InitToken at the PKCS#11 layer.
  • token info -- print the label, serial, flags, and session-count information for the configured token. Supports --json.

key

Object-level management for keys.

  • key list -- list every key object with its handle, class, key type, label, and lifecycle state. Supports --json.
  • key import --file <PATH> --label <LABEL> --type <RSA|EC|AES> -- import key material from a PEM or DER file. --type selects the key class. RSA and EC private keys are accepted in PKCS#8; AES keys are raw bytes.
  • key delete --handle <N> [--force] -- destroy the object with the given handle. Prompts for confirmation unless --force is set. Equivalent to C_DestroyObject.

Key generation is performed through the PKCS#11 library or the gRPC daemon (GenerateKey, GenerateKeyPair), not through the CLI.

pin

PIN management.

  • pin change [--user-type USER|SO] -- change the specified PIN. Prompts for the current PIN and a new PIN. Defaults to the user PIN if --user-type is not given. Equivalent to C_SetPIN.
  • pin reset -- reset a locked user PIN. Requires the Security Officer PIN. Equivalent to the SO-authenticated C_InitPIN flow.

See Security Model for PIN policy and lockout behaviour.

audit

Audit-log inspection and export.

  • audit dump [--last <N>] -- print the most recent N entries (default 50) in human-readable form. Supports --json.
  • audit export-json -- emit the entire log as a JSON array.
  • audit export-ndjson -- emit newline-delimited JSON, one AuditEvent per line. Suitable for SIEM ingestion.
  • audit export-syslog -- emit the log in RFC 5424 syslog format.
  • audit verify-chain -- recompute the SHA-256 chain over every entry and report the first tampered entry, if any. Supports --json; a non-zero exit status is returned when verification fails.

status

Prints an overview of the HSM: POST status, crypto backend in use, active slot count, and any lockout state. Supports --json.

backup and restore

Encrypted backup of token objects. See Storage -- Backup and Restore for the file format.

  • backup --output <PATH> -- prompt for a passphrase (minimum 16 characters), serialise every token object, encrypt under an AES-256-GCM key derived from the passphrase via PBKDF2-HMAC-SHA256 (1,000,000 iterations), and write the blob to <PATH>.
  • restore --input <PATH> -- prompt for the passphrase, decrypt, validate the header and token-serial binding, and insert the recovered objects into the current token. The staleness window (30 days by default) and cross-token-serial check are enforced.

Operator procedure -- rotation schedules, passphrase custody, air-gapped storage -- is covered in Backup and Recovery.

Diagnostics and Self-Tests

The CLI does not expose a dedicated selftest subcommand. POST self-tests run automatically on every HsmCore construction, which means every craton-hsm-admin invocation executes the full 17-test suite before doing anything else. A failed POST is reported on stderr and the process exits non-zero without executing the requested command.

status reports whether POST has succeeded in the current process. audit verify-chain provides on-demand verification of the audit log integrity. For deeper diagnostics (mechanism enumeration, algorithm policy dump), use the PKCS#11 C_GetMechanismList / C_GetMechanismInfo calls via pkcs11-tool.

Operational Notes

  • The CLI holds the persistent-store file lock while running. If cratond is live against the same database, craton-hsm-admin will fail to open it. Stop the daemon, run the admin command, then restart the daemon.
  • Every security-relevant CLI operation -- token init, PIN change, key import, key delete, backup, restore -- is written to the audit log before the command returns.
  • Import and export operate on unwrapped key material in the process's own memory. Key buffers are mlocked and zeroised on drop, but the file passed to key import must be protected by the surrounding operating-system controls.