Craton HSM

Release Signing and Verification

Release Signing and Verification

Craton HSM release binaries — the PKCS#11 shared library, the gRPC daemon, and the admin CLI — are cryptographically signed so that operators can verify authenticity before loading them into a cryptographic boundary. Unsigned or unverifiable binaries must not be deployed.

Two signing paths are supported. Sigstore / cosign is recommended for new deployments because it eliminates long-lived signing keys entirely. GPG is available for environments that cannot reach Sigstore's Rekor transparency log. On Windows, Authenticode is used for the .dll.

Verifying a downloaded binary

Sigstore / cosign (recommended)

Every release publishes a .bundle file alongside each artefact. The bundle contains the signature, the ephemeral signing certificate, and an inclusion proof for the Rekor transparency log.

# 1. Download the library and its bundle.
curl -LO https://github.com/craton-co/craton-hsm-core/releases/download/v0.9.1/libcraton_hsm.so
curl -LO https://github.com/craton-co/craton-hsm-core/releases/download/v0.9.1/libcraton_hsm.so.bundle

# 2. Verify.
cosign verify-blob \
    --bundle libcraton_hsm.so.bundle \
    --certificate-identity-regexp 'https://github.com/craton-co/craton-hsm-core/.*' \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com \
    libcraton_hsm.so

The verification succeeds only if the signing certificate was issued to the Craton HSM release workflow, the signature matches the binary, and the Rekor inclusion proof is valid. Any failure must be treated as a supply-chain event — do not deploy the binary.

GPG

For releases signed with GPG, each binary has a detached .asc signature.

# 1. Import the Craton HSM release key (fingerprint on the release page).
gpg --recv-keys <FINGERPRINT>

# 2. Verify.
gpg --verify libcraton_hsm.so.asc libcraton_hsm.so

The release key fingerprint is published on the project's release page and on a well-known location independent of the distribution channel (for example, the project's HTTPS homepage). Never trust a key delivered alongside the binary.

SHA-256 checksums

Every release also publishes a SHA256SUMS file. Use it as a last-line integrity check after signature verification:

sha256sum -c SHA256SUMS --ignore-missing

sha256sum alone proves only that the file matches the checksum; signature verification is what proves authenticity. Run both.

Authenticode (Windows)

The .dll is signed with Authenticode.

signtool verify /pa craton_hsm.dll

The timestamp on Authenticode signatures survives signing-certificate expiry; a validly timestamped binary remains verifiable after the signing certificate rolls.

Signing (for release engineers)

The canonical flow runs in GitHub Actions on tag push. The workflow builds each target with cargo build --release --locked, publishes SHA-256 checksums, and signs with cosign keyless mode against the GitHub OIDC issuer. The release engineer does not hold a long-lived private key.

A minimal CI step:

- name: Build
  run: cargo build --release --locked --lib

- name: Checksum
  run: sha256sum target/release/libcraton_hsm.so > SHA256SUMS

- name: Sign with cosign (keyless)
  uses: sigstore/cosign-installer@v3
- run: |
    cosign sign-blob --yes \
        --bundle libcraton_hsm.so.bundle \
        target/release/libcraton_hsm.so

For the GPG path, the signing key is stored on a hardware token (YubiKey OpenPGP applet). The token is required to be plugged in for the release workflow to proceed.

On Windows, the Authenticode code-signing certificate is stored in a hardware HSM — in a mature deployment, that HSM can itself be Craton HSM with a certificate issued by the organization's code-signing CA. signtool is invoked with /fd sha256 /t http://timestamp.digicert.com.

Reproducible builds

Release artefacts are built with cargo build --release --locked; Cargo.lock is committed, so dependency versions are pinned. The build environment — base image, toolchain version, target triple — is recorded in the release notes, which lets third parties reproduce the build and compare hashes.

FIPS 140-3 validated builds carry an additional reproducibility constraint: they are cut from tagged versions of the craton-hsm-awslc backend and must match the module hash recorded in the validation certificate. See ../enterprise/certified for the current certificate status and for the hash-verification procedure against the validated module.

Defense in depth

Signature verification is one layer. The module also performs runtime integrity verification:

  • At every C_Initialize, the 16 power-on self-test KATs and the module-integrity self-test run. A binary that has been modified since build will fail at least one KAT and the module enters a permanent failed state where every subsequent call returns CKR_GENERAL_ERROR. See ../fips/self-tests.
  • The cryptographic boundary is covered by Cargo.lock plus supply-chain tooling (cargo audit for CVEs, cargo deny for licences and advisories). These are enforced in CI.

A compromised release would have to defeat signature verification, the transparency log, and the runtime KATs simultaneously — a substantially harder target than subverting any one of them.

Recommended practice

  • Verify every downloaded binary before installation, including in non-production environments. The habit matters.
  • Pin to exact versions in deployment manifests; do not use floating tags.
  • Archive the verified binary plus its signature bundle alongside the corresponding craton_hsm.toml in the same configuration-management repository. Restoring a host should not require downloading anything fresh.
  • Rotate GPG signing keys annually; rely on Sigstore's ephemeral certificates where available.
  • Subscribe to release announcements on a channel independent of the GitHub release RSS, so that a GitHub compromise cannot silence notifications.