mirror of
https://github.com/jmcorgan/fips.git
synced 2026-10-05 11:08:25 +00:00
Johnathan Corgan
d7a1a24706
Option::take moves a value out but writes only the None marker, so the old bytes stay in the slot. Completing a handshake left the whole handshake state, the node's long-term private key and the ephemeral key included, in the connection's handshake slot, which on a peer machine is heap memory that outlives the handshake, and take_session left both traffic keys of the session in the session slot. Add clear_slot in the noise module: it drops whatever the slot holds, overwrites every byte of the slot with zeros through zeroize's volatile flat-type erase, and leaves None. complete_handshake takes and unwraps the handshake first and then clears the slot, so a release build copies the handshake once, as before, and then zeroes the slot; clearing inside the take had cost a second stack copy that nothing cleared. take_cleared, built on clear_slot, takes the value out and clears the slot, and take_session uses it, since there the session goes straight to the caller and no extra copy appears. start_handshake and receive_handshake_init hold the node's long-term keypair across early returns, so a guard erases it on every exit. The guard owned a copy: building it copied the keypair into a temporary and then moved it into the guard's binding, and only the binding was erased. On the early-return paths nothing reused the temporary's stack slot, so a copy of the long-term private key stayed in the frame. The guard now borrows the caller's binding and erases it where it lies when dropped, so making or moving it copies no key bytes. Tests cover what safe code can observe: the value comes out intact and is dropped exactly once, the slot is None and reusable, a type whose all-zero bytes would read as Some still ends as None, a handshake and session taken this way still interoperate, and a guard held across an early and a normal return erases the caller's own keypair on both. The clearing itself is shown by a release build's disassembly and a scan of process memory, not by a unit test. The security reference now says the SHA-256 and HMAC states clear themselves on drop and that a completed handshake and a session taken for a rekey leave their slot cleared, and names what is still left: the copies stack moves leave, the session keys or unfinished handshake that stay in a control machine's heap memory when the whole connection state is moved off it on promotion or reaping, and the copies of the private key that loading the identity from a secret string leaves in that constructor's frame, now a known limit. It also no longer says each erase is a volatile write followed by a compiler fence: only secp256k1's erase uses a fence, zeroize's follows the write with an empty asm! optimisation barrier, and in both it is the volatile write that keeps the store.
Reference
Information-oriented technical descriptions for lookup on demand. Reference content describes what is: wire formats, configuration keys, command-line flags, control-socket commands, default values, file paths, exit codes. It is consulted, not read end-to-end.
Reference is austere by design: minimal narrative, no opinions, no guidance on when to use a feature. The "why" lives in design/; the "how do I accomplish X" lives in how-to/.
Available Reference
| Document | Scope |
|---|---|
| wire-formats.md | All FMP and FSP message byte layouts, encapsulation walkthrough |
| configuration.md | Full YAML configuration reference for the daemon and gateway |
| security.md | nftables baseline, peer ACL, cryptographic primitives, rekey defaults, threat-resistance matrix |
| nostr-events.md | Kind 37195 advert, Kind 21059 traversal signaling, Kind 10050 inbox relays |
| transports.md | Per-transport statistics counter inventory |
| control-socket.md | Line-delimited JSON control protocol for the daemon and gateway |
| native-api.md | Native datagram API: the Rust surface, addressing and ports, errno table, ceilings, line protocol, command reference |
| cli-fips.md | fips daemon CLI: options, exit codes, environment, files |
| cli-fipsctl.md | fipsctl control-client: subcommands, options, exit codes |
| cli-fipstop.md | fipstop live-status TUI: tabs, keybindings |
| cli-fips-gateway.md | fips-gateway service CLI: options, exit codes, files |