RS-Key

The upgrade path is the product: flashing the newest release replaces the firmware in place, and an already-provisioned device keeps its credentials across the upgrade — a persistent-format change must load older record layouts forward and say how. The one case where that does not hold is documented at the top of the CHANGELOG with the export step to take first. There are no maintained release branches, stated in SECURITY.md; supported means the tip of main.

GitHub Issues, with issue templates:
https://github.com/TheMaxMur/RS-Key/issues

No externally reported vulnerability has been resolved in the last 12 months, so
there is nobody yet to credit. SECURITY.md invites private reports and treats the
reporter's name as theirs to give or withhold.
https://github.com/TheMaxMur/RS-Key/blob/main/SECURITY.md

SECURITY.md documents the whole path: report privately through GitHub's private
vulnerability reporting, what counts as a vulnerability here and what the threat
model already concedes, what a good report contains, what to expect (an
acknowledgment within a few days from one maintainer, a fix on main as fast as
severity warrants), and which versions are supported.
https://github.com/TheMaxMur/RS-Key/blob/main/SECURITY.md

CONTRIBUTING.md and AGENTS.md state the standards contributions must meet:
rustfmt formatting, clippy with -D warnings, no_std and no allocator in firmware
crates, unsafe only with an entry in docs/unsafe.md, an SPDX header on every
file, comments that explain constraints rather than mechanics with a three-line
ceiling, no magic values, typed state instead of string matching, and the Python
conventions for the host CLI.
https://github.com/TheMaxMur/RS-Key/blob/main/CONTRIBUTING.md

Mechanically, in the gate and in the pre-commit hook: cargo fmt --check across
every workspace including the detached ones, clippy with -D warnings on the
embedded, host, TUI, emulator and fuzz targets, and rustdoc with
RUSTDOCFLAGS=-D warnings. CI runs the same script, so a style violation cannot be
merged.

The relevant conventions here are cargo's, and they are honored: RUSTFLAGS, the
target triple, CARGO_TARGET_*_LINKER and the standard profile settings all work
as expected for both the firmware and the native host tools. The one C/assembly
unit is a bare-metal cross-compile for thumbv8m and deliberately pins
arm-none-eabi-gcc, because the dev shell's host CC cannot produce a loadable
object for a Cortex-M33 — honoring an injected CC there would yield a firmware
image that does not boot.

The release profile keeps full debug info (debug = 2) on purpose; the UF2 that
gets flashed is unaffected because debug info is not part of the flashed image,
and the gate itself reads symbol names out of the ELF. Nothing strips.

Cargo workspaces, not recursive make. The dependency graph is explicit in the
manifests, checked by scripts/crate_graph.py to be strictly tiered with no
sideways edges, and enforced by cargo-deny. Nothing recurses into subdirectories
to guess at ordering.

nix build .#firmware is hermetic: the toolchain, the target and every tool are
pinned by flake.lock, and dependencies by Cargo.lock. A scheduled repro job in
the deep-checks workflow rebuilds and compares, so drift is caught rather than
assumed absent.

The firmware installs the way every RP2350 board does: hold BOOTSEL, drag one
.uf2 onto the drive that appears — or use the web flasher. Uninstall is flashing
something else. The host CLI installs through the standard Python conventions
(uv tool install ./tools, pipx install ./tools, or pip), all of which
uninstall the same way.

The host tools honor the conventions of their ecosystems: uv/pipx/pip place the CLI in the standard user location and respect the active virtualenv or prefix, and cargo writes into the usual target directory. The firmware has no install prefix to honor — its destination is a fixed flash offset on the device.

nix develop is the entire setup: Rust stable with the thumbv8m target,
picotool, gitleaks, cargo-audit/deny and the Python stack, pinned by flake.lock.
Entering the shell also installs the pre-commit hook. Without Nix,
rust-toolchain.toml pins the toolchain and components for rustup.
https://themaxmur.github.io/RS-Key/build.html

Machine-readable and pinned: Cargo.toml/Cargo.lock for the Rust side (plus
separate lockfiles for the detached TUI, emulator and fuzz workspaces),
flake.nix/flake.lock for the toolchain and tools, and pyproject for the host CLI.
Git dependencies are restricted to the embassy organization.
https://github.com/TheMaxMur/RS-Key/blob/main/Cargo.lock

Three layers, all in the gate: cargo-audit against the RustSec advisory database, cargo-deny for advisories plus a license allow-list and a source policy, and cargo-vet for supply-chain review status. Dependabot opens update pull requests. No advisory is silently ignored — each entry in deny.toml carries its reason and its dependency chain.

Every reused component is a versioned package in a lockfile, updated with
cargo update or a flake input bump — there are no convenience copies of
third-party source in the build. The vendored third-party test suites under
third_party/ are test harnesses, not shipped code, and are identified as such.

Deprecations are compile errors here, not warnings: clippy runs with -D warnings and rustdoc with RUSTDOCFLAGS=-D warnings, so a deprecated API in the technology stack fails the gate the day the dependency marks it. Where the project stays on an older upstream it is a pinned, stated decision rather than drift.

Every pull request and every push to main runs the same merge gate CI runs
verbatim — nix develop -c ./scripts/check.sh, over a hundred rows — plus the
emulator suites, which drive the real applet stack over a socket with no
hardware. Results are reported per job on the pull request, and scheduled
deep-check workflows run the slower tiers (fuzzing, Miri, Kani, coverage,
reproducibility) daily and weekly.
https://github.com/TheMaxMur/RS-Key/blob/main/.github/workflows/ci.yml

The written policy is that a bug fix starts by reproducing the bug — a failing
host test where the logic is host-testable, a tests/*.py repro otherwise — and
then fixes it. In practice the fixes of the last six months ship with their
tests in the same commit, which is also what makes the gate able to tell a
repaired defect from a rewritten one.

Measured and floored rather than estimated: the deep-checks workflow runs
cargo llvm-cov --fail-under-lines 80 over the host crates, so coverage cannot
silently fall below the bar. The most recent scheduled run reports 86.06% lines
and 84.88% regions. (The floor excludes the firmware glue crate and the flash
wiper, which are embedded-only and not host-executable by construction.)

CONTRIBUTING.md states it as a requirement, not a preference: a protocol-visible
change comes with a test at the level where it is visible — a host test if the
logic is host-testable, a tests/*.py script if only the real USB stack exercises
it — and a new parser comes with a new fuzz target. The pull request template
asks how the change was tested.

The policy is written in CONTRIBUTING.md ("Tests") and the pull request
template asks how the change was tested.
https://github.com/TheMaxMur/RS-Key/blob/main/CONTRIBUTING.md

-D warnings everywhere, no exceptions per crate; plus unsafe sites are
enumerated and justified in docs/unsafe.md, and dependencies are gated by
cargo-deny and cargo-vet. https://themaxmur.github.io/RS-Key/unsafe.html

The assurance case argues this explicitly rather than asserting it: each of
Saltzer and Schroeder's principles against what the tree actually does —
economy of mechanism (no_std, no allocator, no mutexes, ownership as
synchronization), fail-safe defaults (alwaysUv on; a failed flash read is never
laundered into an absence), complete mediation (authorization re-checked at use,
a PIN retry spent before the comparison), open design, separation of privilege,
least privilege (the partition table denies the bootloader the KV store; applets
own disjoint file-id ranges; zero applet-to-applet edges, enforced by cargo-deny)
and least common mechanism. https://themaxmur.github.io/RS-Key/assurance-case.html

Same as crypto_working: SHA-1 is confined to HMAC constructions required by
OATH/challenge-response interoperability, where no collision-resistance
assumption is made; signatures use SHA-256 and above. AES-GCM is used with
unique nonces per sealed record. The FIPS profile build drops every
non-approved option, including secp256k1.
https://themaxmur.github.io/RS-Key/guides/fips.html

Multiple algorithms in every slot that has one: ES256/ES384/ES512 and EdDSA for FIDO, with ML-DSA-44/-65/-87 alongside them; RSA-2048/3072/4096 and EC for OpenPGP and PIV; AES-128/192/256 for PIV management keys; SHA-1/SHA-256/SHA-512 HMAC for OATH as those specifications require. The FIPS-style profile build demonstrates the agility from the other side, dropping every non-approved option (including secp256k1) from both the advertised list and negotiation.

No key or credential is compiled into the program. Private keys and secrets live
in the device's flash KV store, sealed at rest and separate from the image; the
secure-boot signing key is generated and held by the operator on their own host,
never in this repository. The only keys that can be baked into a build are
explicitly fake test keys behind FAKE_* build knobs, which exist so that a test
image is distinguishable from a real one.

The software has no network communications. It is USB firmware for a security key and a host CLI that talks to it over USB HID and CCID; there is no socket, no network stack and no remote endpoint.

The software neither supports nor uses TLS — there is no network interface.

The software does not support TLS; there is no network interface and no certificate chain to verify at runtime.

The software does not support TLS and sends no HTTP headers; it speaks USB protocols only.

Each release publishes a SHA256SUMS file signed with keyless cosign, recorded in
the Rekor transparency log, plus a GitHub build-provenance attestation (SLSA
Build L3). Keyless signing means there is no public key for users to fetch and
trust out of band — the identity is the release workflow in this repository,
verifiable with cosign verify-blob against that identity. The commands are
documented step by step.
https://themaxmur.github.io/RS-Key/releases.html

Release tags are annotated and GPG-signed (git tag -s) as a step of the release
pipeline; the most recent, v0.4.10, carries its signature in the tag object.

Everything arriving over USB is untrusted and is parsed against what the specification allows, not against what is expected: CTAPHID framing, CBOR maps, ISO-7816 APDUs and the CCID bulk stream each reject structurally invalid input with the status the protocol defines rather than best-effort recovery. Lengths are checked against the buffers they index — there is no allocator to grow into — and every one of those parsers has a fuzz target, with a floor in the gate so the set cannot quietly empty.

Hardening is layered and most of it is on by default. The language: no_std Rust
with no allocator, bounds-checked slices, and unsafe sites enumerated and
justified. The image: optional secure boot with an anti-rollback epoch in OTP
fuses, and a partition table carried in the shipped image that denies the USB
bootloader read and write over the key store while secure code keeps it. The
data: every secret AEAD-sealed before it reaches flash, through a single
chokepoint. The process: retry counters with lockout, constant-time comparisons,
and blinding on every private-key path.
https://themaxmur.github.io/RS-Key/threat-model.html

A dedicated assurance case page: what is claimed, the threat model it is claimed
against, six explicitly identified trust boundaries (the USB cable, transport to
worker, RAM to flash, the boot chain and partition table, the owner, and source
to artifact), the secure-design-principles argument, and a table mapping common
implementation weaknesses to what prevents each and where the evidence lives. It
ends with the residuals it cannot justify.
https://themaxmur.github.io/RS-Key/assurance-case.html

CodeQL runs its security query suites for Rust and Python, and cargo-audit/cargo-deny match the dependency graph against the RustSec advisory database on every gate run.

The firmware is Rust, memory-safe by default, and its few unsafe sites are
enumerated and justified in docs/unsafe.md. Those paths are covered
dynamically anyway: cargo-fuzz builds with AddressSanitizer, and
scripts/miri-all.sh re-runs every fuzz target's logic under Miri's
undefined-behaviour checker in CI.
https://themaxmur.github.io/RS-Key/unsafe.html