Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Releases & verification

Releases live on the GitHub Releases page. Each is cut from a v* git tag by the release workflow. It builds every artifact reproducibly, hashes it, and signs the manifest. It runs only at the tag it releases: a run started by hand from a branch, or from another tag, stops before it builds anything. A run started by hand uses the workflow file at the ref it starts from, though, and the tags published up to v0.4.11 carry one without that test. A run started at one of them can still build another tag, signed under the old tag’s name; the tag pin in step 1 below refuses it, and so does gh attestation verify --source-ref (supply-chain.md, step 3).

What a release contains

  • Fourteen firmware images: rs-key-<tag>-<flavor>.uf2. Every published image requires a physical touch; the no-touch test builds are never released (a signed presence-bypass asset would remove the consent gate):

    flavorflagsuse
    defaulttouchthe normal build; start here
    pqc+ advertise-pqcadvertises all three ML-DSA sets in getInfo (breaks old Firefox)
    fips+ fips-profilethe locked FIPS-style policy (guides/fips.md)
    fips-pqc+ both
    strong-pin+ strong-pin6-code-point PIN floor + trivial-PIN block (build.md, threat-model.md)
    strong-pin-pqc+ both
    always-uv+ always-uvbakes CTAP 2.1 alwaysUv on: user verification (a PIN) for every operation, U2F disabled. Set a PIN after flashing (build.md)
    always-uv-pqc+ both
    strict-up+ strict-upnot spec-conformant: a touch on every assertion, so a WebAuthn allowCredentials login asks for two touches (build.md). Pick it only if you want that stricter stance
    strict-up-pqc+ both
    display+ displayexperimental trusted-display build (Waveshare RP2350-Touch-LCD-2.8, guides/display.md)
    2mbFLASH_SIZE=2M KVMAIN=896K2 MB boards (Seeed XIAO RP2350, Waveshare RP2350-Zero-CM)
    16mbFLASH_SIZE=16M16 MB boards (e.g. TenStar RP2350-USB)
    strict-config+ strict-configthe historical strict admin-write posture: config writes stay presence/PIN-gated and the ungated transport writes are refused (build.md, threat-model.md). The default build is now the permissive full-ykman admin surface

    All fourteen present the default RS-Key USB identity: 0x1209:0xF1D2 from build 0x0A8A; older images use the test PID 0x1209:0x0001. For the YubiKey-interop identity, build VIDPID=Yubikey5 yourself (build.md).

  • SHA256SUMS: a checksum for every image and the SBOM.

  • SHA256SUMS.sigstore.json: a keyless cosign signature of SHA256SUMS (sigstore/Fulcio; the signer is the reusable build workflow’s GitHub OIDC identity, release-build.yml, see the verify step below; logged in Rekor). Releases up to and including v0.4.10 carry the same file under the older name SHA256SUMS.cosign.bundle — identical bytes, and .sigstore.json is simply the canonical extension for what it always was (application/vnd.dev.sigstore.bundle.v0.3+json). Those releases are immutable and cannot be renamed in place, so both names exist in the wild.

  • rs-key-<tag>.intoto.jsonl: the build-provenance attestation, as a file. The authoritative copy stays in GitHub’s attestation API and in Rekor; this one is for checking a download offline.

  • rs-key-<tag>-sbom.cdx.json and rs-key-<tag>-sbom-nonsecure.cdx.json: CycloneDX bills of materials for the Secure and Non-secure dependency trees.

The images are UNSIGNED for secure boot. The cosign signature attests who built them, not the boot seal. On a secure-boot device you seal an image with your own key before flashing. nix run .#flash does it, or see production.md. The reproducibility claim is about the unsigned payload (a seal is signer-specific and not reproducible by a third party).

Verify a download

Grab the images you want plus SHA256SUMS and the signature — SHA256SUMS.sigstore.json, or SHA256SUMS.cosign.bundle on releases up to v0.4.10. Same bytes either way; substitute the name you actually downloaded, and the release’s tag for <tag>.

# 1. the checksums file is authentic (keyless cosign — needs cosign >= 2.0)
#    The signer is the *reusable* build workflow (release-build.yml), not the
#    thin release.yml caller: a workflow_call job's OIDC identity is its own
#    job_workflow_ref, so that is what the Fulcio cert's SAN carries. The ref
#    flag pins the release's own tag; any repository can call the workflow, so
#    the last flag pins the repository of the run.
cosign verify-blob \
  --bundle SHA256SUMS.sigstore.json \
  --certificate-identity-regexp '^https://github\.com/TheMaxMur/RS-Key/\.github/workflows/release-build\.yml@refs/tags/v.*$' \
  --certificate-github-workflow-ref refs/tags/<tag> \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  --certificate-github-workflow-repository TheMaxMur/RS-Key \
  SHA256SUMS

# 2. the images match the (now-trusted) checksums
sha256sum -c SHA256SUMS

Both must pass. Step 1 proves SHA256SUMS was produced by this repo’s release workflow; step 2 ties each .uf2 (and the SBOM) to it.

rsk flash runs these checks and flashes only when they pass. Keep SHA256SUMS and SHA256SUMS.sigstore.json in the folder with the image, put the board in BOOTSEL, and:

rsk flash rs-key-<tag>-default.uf2    # --dry-run checks and writes nothing

It also runs gh attestation verify, pinned to the release’s own tag, when the GitHub CLI is installed, and says so when it is not (supply-chain.md, step 3).

Verify the build is reproducible

The images are bit-for-bit reproducible per platform, per flake.lock, so you can rebuild them yourself and compare (no need to trust the published binary):

git checkout <tag>
nix build .#firmware              # the default flavor (others: .#firmware-fips, …)
sha256sum result/firmware.uf2     # compare against SHA256SUMS for rs-key-<tag>-default.uf2

A match on Linux reproduces the CI-built artifact exactly. (Cross-platform identity, macOS vs Linux, is not guaranteed; the canonical bytes are the Linux ones the workflow publishes.)