docs(security): self-contain KEY-05 and PSBT; record the completed entropy migration
Verified the security subsystem's design-doc claims against code:
- KEY-05's foundational claims are accurate: entropy::draw_key_bytes exists,
KeyGenRng is sealed with OsRng as its sole production member, MIN_GUARDED_LEN
is 12, and core/clippy.toml bans rand::random/thread_rng exactly as stated.
- But its per-site table listed every production nonce/key site as disposition
"migrate" (pending), when all of them have since been migrated to
draw_key_bytes(OsRng) — storage_crypto, credentials/store, wallet/bdhke,
mesh/x3dh — and zero rand::random/thread_rng remain in production. Added a
completion note so the doc no longer reads as pending work.
Both KEY-05 and PSBT-SIGNING-ARCHITECTURE referenced
ENTROPY-SEED-AUDIT-2026-07-31.md five times as their evidence base — a doc that
was moved to local-only, so a public reader could not follow it. Reworded all
five to state the audit's findings inline ("the internal entropy audit found
...") without the unresolvable path. No published doc references it now. The
link-checker missed these because they were inline code, not markdown links.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5
parent
bcbd4a7032
commit
dc2d79ce77
@@ -2,12 +2,17 @@
|
||||
|
||||
**Requirement:** ROADMAP `KEY-05`.
|
||||
**Supersedes:** backlog `R-13`. **Absorbs:** `R-05` (duplicate-`rand` visibility) and `R-09`
|
||||
(CSPRNG-readiness record). **Resolves:** `F-10a` in
|
||||
`docs/security/ENTROPY-SEED-AUDIT-2026-07-31.md`, which recorded raw match counts and
|
||||
**deliberately declined to classify them**.
|
||||
(CSPRNG-readiness record). **Resolves:** `F-10a` from the internal entropy and
|
||||
seed-generation audit, which recorded raw match counts and **deliberately declined
|
||||
to classify them**.
|
||||
|
||||
**Tree state this document was derived against:** `HEAD = c5a82cba` (2026-08-02).
|
||||
|
||||
**Update:** every `migrate` disposition in the table below has since been applied.
|
||||
No `rand::random()` / `rand::thread_rng()` call remains in production `archipelago`
|
||||
code — each draws through `entropy::draw_key_bytes` from a named `OsRng`, and
|
||||
`core/clippy.toml` now bans both APIs, so a regression fails the build.
|
||||
|
||||
---
|
||||
|
||||
## Nothing here is broken today
|
||||
@@ -206,8 +211,8 @@ lines are `core/archipelago/src/mesh/x3dh.rs:99` and `:113` —
|
||||
produced there; `:100` and `:114` draw only the `u32` `id` fields of `SignedPrekey` and
|
||||
`OneTimePrekey`. They remain in scope — they are values that go on the wire — but the
|
||||
characterisation "X3DH key agreement — key material" overstates these two specific lines.
|
||||
(The audit has since been corrected in place at `ENTROPY-SEED-AUDIT-2026-07-31.md:508`; this
|
||||
section records the derivation independently.)
|
||||
(The internal audit has since been corrected; this section records the derivation
|
||||
independently.)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -32,8 +32,8 @@
|
||||
> a phased rollout that a future `/gsd-plan-phase` can consume directly. It deliberately
|
||||
> contains no code, adds no dependencies, and changes no wallet or signing behaviour.
|
||||
>
|
||||
> **Companion document:** `docs/security/ENTROPY-SEED-AUDIT-2026-07-31.md` — the entropy and
|
||||
> seed-generation audit that motivated this spec. **Cross-linked design:**
|
||||
> **Companion document:** the internal entropy and seed-generation audit that
|
||||
> motivated this spec. **Cross-linked design:**
|
||||
> `docs/hardware-signer-design.md` — the exploratory TROPIC01 air-gapped signer, which this
|
||||
> architecture treats as the future *first-party* signer, not as a competing design.
|
||||
|
||||
@@ -425,7 +425,7 @@ nagged-at that users stop reading warnings. Concretely:
|
||||
- **A software fix does not repair an already-generated seed.** If a seed was produced by a
|
||||
defective RNG, updating the software leaves it exactly as guessable. This is why Coinkite told
|
||||
users to migrate rather than merely update.
|
||||
- **The audit found no such defect in Archipelago.** `docs/security/ENTROPY-SEED-AUDIT-2026-07-31.md`
|
||||
- **The audit found no such defect in Archipelago.** The internal entropy audit's
|
||||
§2 and §4 record that every first-party key-generation call site draws from a genuine CSPRNG,
|
||||
that the mnemonic is a real 256-bit value, and that `[ARCHY-1]` is a *structural* risk with no
|
||||
present exploitability.
|
||||
@@ -609,7 +609,7 @@ current security posture and should not wait for the rest.
|
||||
|
||||
## 9. Related documents
|
||||
|
||||
- `docs/security/ENTROPY-SEED-AUDIT-2026-07-31.md` — the audit motivating this spec; see F-05
|
||||
- The internal entropy and seed-generation audit — motivating this spec; see F-05
|
||||
(Argon2 parameters) and the F-13 addendum on the xprv-in-Core issue.
|
||||
- `docs/hardware-signer-design.md` — the first-party TROPIC01 air-gapped signer; §4.3 above
|
||||
answers two of its open items.
|
||||
|
||||
Reference in New Issue
Block a user