RS-Key

Repository on GitHub, which provides public git repositories with URLs.

Repository on GitHub, which uses git. git can track the changes, who made them, and when they were made.

https://github.com/TheMaxMur/RS-Key/commits/develop

Repository on GitHub, which uses git. git is distributed.

Non-trivial release notes file in repository: https://github.com/TheMaxMur/RS-Key/blob/main/CHANGELOG.md.

Non-trivial SECURITY[.md] file found file in repository: https://github.com/TheMaxMur/RS-Key/blob/main/SECURITY.md. [osps_do_02_01]

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

https://github.com/TheMaxMur/RS-Key/issues?q=is%3Aissue

https://github.com/TheMaxMur/RS-Key/issues?q=is%3Aissue

https://github.com/TheMaxMur/RS-Key/issues?q=is%3Aissue

https://github.com/TheMaxMur/RS-Key/security/policy

https://github.com/TheMaxMur/RS-Key/security/advisories/new

No vulnerability reports have been received in the last 6 months. SECURITY.md commits to an acknowledgment within a few days.

https://themaxmur.github.io/RS-Key/build.html

Cargo (the standard Rust build tool) plus Nix flakes for a reproducible toolchain; no bespoke build system.

Every build tool is FLOSS: Rust/cargo (MIT/Apache-2.0), Nix, picotool, rustfmt, clippy, mdBook, Python with uv. No proprietary tool is required at any stage.

The host crates under crates/ carry unit tests run by cargo test, and
tests/*.py holds 60 end-to-end suites that run either against a board or
against the in-repo software emulator (tools/emu) with no hardware. All of it
is in the repository under AGPL-3.0-only.
https://themaxmur.github.io/RS-Key/testing.html

cargo test — the standard invocation for Rust, run per workspace against the
host target (the firmware's own target is thumbv8m, so host tests name it
explicitly). The whole suite, including the device and emulator layers, is one
command that CI runs verbatim: nix develop -c ./scripts/check.sh. The layers
and how to invoke each one are documented here:
https://themaxmur.github.io/RS-Key/testing.html

The gate runs over 100 rows: per-crate unit tests over the protocol parsers, codecs
and state machines, plus 54 fuzz targets, Kani model-checking harnesses, TLA+
models, and 60 device/emulator suites covering FIDO2/CTAP, PIV, OpenPGP and
OATH end to end. https://themaxmur.github.io/RS-Key/testing.html

GitHub Actions runs the same merge gate on every pull request and on every push
to main, plus daily and weekly deep-check workflows (fuzzing, Miri, Kani).
https://github.com/TheMaxMur/RS-Key/blob/main/.github/workflows/ci.yml

CONTRIBUTING.md requires that new functionality ships with tests at the level
it is observable — a host test where the logic is host-testable, a tests/*.py
script where only the USB stack exercises it — and that a bug fix starts with a
failing test. https://github.com/TheMaxMur/RS-Key/blob/main/CONTRIBUTING.md

Recent major changes shipped with their tests: the ML-DSA post-quantum stack with ACVP known-answer vectors and Kani proofs, the PIN policy work with unit tests, the filesystem and reset paths with both unit tests and TLA+/Kani refinement proofs. The gate is red without them.

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

Clippy runs with -D warnings over every workspace and target (firmware,
host crates, TUI, emulator, fuzz targets), and rustdoc runs with
RUSTDOCFLAGS=-D warnings. Rust's own warnings are on top of that.

Warnings are errors: any warning fails scripts/check.sh, which is both the
local gate and the CI merge gate, so a warning cannot be merged. Individual
#[allow] sites must be justified inline at the smallest scope.

-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 maintainer designs to the usual principles — least privilege, minimal
attack surface, no secret in the clear at rest, fail-closed — and the project
documents where each applies: a written threat model with explicit
non-goals, a documented limitations page, every secret AEAD-sealed before it
reaches flash behind a single key chokepoint, and TLA+ models plus Kani proofs
for the security-state machines.
https://themaxmur.github.io/RS-Key/threat-model.html
https://themaxmur.github.io/RS-Key/formal.html

The relevant error classes for an authenticator — memory corruption in the USB
and APDU parsers, missing user-presence/PIN gates, retry-counter and replay
handling, power-cut torn writes, timing side channels in PIN comparison — are
tracked explicitly: the code is Rust no_std with no heap, parsers are fuzzed
(54 targets, AddressSanitizer + Miri), PIN retry spending is proved by Kani,
and repeated security audit rounds are recorded in the repository.
https://themaxmur.github.io/RS-Key/threat-model.html

Only published, standardized algorithms: ECDSA P-256/P-384 (FIPS 186-4), Ed25519 (RFC 8032), X25519 (RFC 7748), RSA-2048/3072/4096 (PKCS#1), ML-DSA-44/-65/-87 (FIPS 204), AES-128/192/256 (FIPS 197) incl. AES-GCM, SHA-256/384/512 (FIPS 180-4), HMAC (RFC 2104), HKDF (RFC 5869), and the CTAP 2.1/2.2, U2F, PIV (SP 800-73), OpenPGP-card and OATH (RFC 4226/6238) protocol suites.

Not applicable: implementing cryptography IS the primary purpose of this
software. It is bare-metal no_std firmware for a security key — there is no
operating system or platform crypto library to call into on the target.

All cryptography is implemented in FLOSS: the project's own AGPL-3.0-only crates (rsk-crypto, rsk-ec, rsk-rsa, rsk-mldsa, rsk-sha512) over MIT/Apache-2.0 RustCrypto components. No proprietary or binary-only crypto is used, and the RP2350 hardware TRNG is documented silicon.

Defaults meet or exceed NIST minimums: ECDSA P-256/P-384, Ed25519, RSA >= 2048
bits, AES-192 (PIV management key) and AES-256 for at-rest sealing, SHA-256 and
above, HMAC-SHA-256 for key derivation, ML-DSA-44/-65/-87 for the post-quantum
path.

No broken algorithm is a default: no MD4/MD5, no RC4, no single DES, no
Dual_EC_DRBG. The PIV management key defaults to AES-192; legacy 3DES is
accepted only for interoperability with existing PIV tooling and is refused
outright by the FIPS profile build. SHA-1 appears only inside HMAC where the
interoperability specifications mandate it (OATH HOTP/TOTP per RFC 4226/6238
and Yubico-compatible HMAC-SHA1 challenge-response), never for signatures or
key derivation.

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

The CTAP pinUvAuthProtocol key agreement uses an ephemeral P-256 key pair that the authenticator regenerates (power-up, reset, PIN change), so a session's shared secret cannot be recovered from any long-term stored key. This is the only key-agreement protocol the device speaks.

Not applicable: the project stores no passwords for authenticating external users. The local device PIN is never stored; what is stored is a verifier derived as HKDF-SHA-256 over HMAC-SHA-256(device key, PIN), where the device key is bound to a per-device OTP secret and the device serial hash, sealed with AES-GCM at rest, and guarded by a hardware-backed retry counter that locks the credential store after the CTAP-mandated number of failures — the offline attack an iterated hash exists to slow down requires extracting a per-device key from the silicon first.

All keys and nonces come from the RP2350 hardware TRNG (with the silicon's
health checks enabled at boot) seeding an HMAC-DRBG from rsk-crypto; every
applet draws from that single DRBG. No language-default or time-seeded RNG is
used anywhere in the firmware.

Distribution channels use HTTPS exclusively. [osps_br_03_02]

Releases are downloaded over HTTPS from GitHub and ship a SHA256SUMS file
signed with keyless cosign, logged in the Rekor transparency log, alongside a
GitHub build-provenance attestation (SLSA Build L3); the verification steps are
documented. Dependencies are pinned by cryptographic hash in Cargo.lock and
flake.lock. No hash is ever fetched over plain HTTP.
https://themaxmur.github.io/RS-Key/supply-chain.html

There are no unpatched vulnerabilities of medium or higher severity. Dependency advisories are checked on every gate run by cargo-audit and cargo-deny; the only entries currently open are RustSec "unmaintained" informational advisories (bare-metal, paste, proc-macro-error2) with no CVE and no patched version in existence — two of the three are build-time proc macros that never reach the firmware image, and all three are documented with their dependency chain in deny.toml.

No critical vulnerability has been reported to date. SECURITY.md commits to a
fix on main as fast as severity warrants, and every firmware change bumps
bcdDevice so affected builds can be named precisely.

gitleaks runs in the pre-commit hook, in scripts/check.sh, and in the CI
docs job (the one job no change can skip), so a secret cannot enter history
unnoticed. The repository contains no private credential; test keys are
explicitly fake and gated behind FAKE_* build knobs.

Several tools beyond compiler warnings run on every change: clippy with
-D warnings over every workspace and target, CodeQL (Rust and Python) on pull
requests, cargo-audit / cargo-deny / cargo-vet over the dependency graph, and
the Kani model checker plus TLA+/TLC over the security state machines
(credential store, reset, PIN token).
https://github.com/TheMaxMur/RS-Key/blob/main/.github/workflows/codeql.yml
https://themaxmur.github.io/RS-Key/formal.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.

Findings are fixed before merge — the tools are gate rows, so a finding is a red build, not a ticket. No medium-or-higher exploitable finding is currently open.

clippy and gitleaks run in the pre-commit hook on every commit and again on every pull request; CodeQL runs on every pull request; the deep-check workflows run daily and weekly.

54 cargo-fuzz (libFuzzer) targets over the USB, CTAP, APDU, PIV, OpenPGP, OATH
and filesystem parsers, run in the scheduled deep-check workflow; Miri runs
every fuzz target's logic under its undefined-behaviour checker; 65 end-to-end
suites drive the real USB stack on a board or the software emulator.
https://themaxmur.github.io/RS-Key/testing.html

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

Fuzzing and the host test suites run with debug assertions on (cargo-fuzz
builds with -C debug-assertions, and cargo test uses the dev profile), so
assert!/debug_assert! and Rust's arithmetic-overflow checks are live during
dynamic analysis.

Every defect found dynamically has been fixed and, where the logic is host-testable, locked in with a regression test in the same commit; the CHANGELOG records them. No medium-or-higher exploitable finding is open.