This commit lands four follow-up items that were explicitly deferred in
TODO.md after the prior file-format change, plus a CLI/units cleanup
that fell out of reviewing them:
1. Manual STREAM nonce construction (drops `stream` cargo feature).
2. Atomic file output (`.tmp` + rename, with cleanup on failure).
3. Argon2id KDF + passphrase prompt + matching CLI flags.
4. Hardened secret handling: zeroize-on-drop, mlock'd buffers,
custom cross-platform tty reader (replaces `rpassword`).
Why
---
The prior version had three concrete weaknesses that were fine for
"early development" but unacceptable past that point:
* `--raw-key` was the only way to supply a key, exposing it in
`/proc/$pid/cmdline`. There was no passphrase mode at all.
* Crashes/aborts during encrypt could leave a half-written output
file in place of (or replacing) the user's target.
* Key material wasn't zeroed and could end up in swap or coredumps.
rpassword's reallocating String buffers also leaked stale heap
copies of typed passphrases that no `Zeroizing` wrapper could
reach after the fact.
(1) Manual STREAM nonces
------------------------
Replaces `aead::stream::EncryptorBE32` / `DecryptorBE32` with
explicit `make_nonce(prefix, counter, last)` and direct
`XChaCha20Poly1305::{encrypt,decrypt}_in_place` calls. The wire format
is unchanged (XChaCha20Poly1305 STREAM-BE32 = 19-byte prefix || 4-byte
big-endian counter || 1-byte last-block flag), so files written by the
previous version still decrypt. Counter overflow is now an explicit
`Format` error rather than a panic in the upstream stream wrapper.
This removes the `stream` cargo feature from `chacha20poly1305` and
prepares the encrypt path for parallelism: with explicit nonces we can
hand chunks to a worker pool keyed by counter without the stream
wrapper's stateful API getting in the way.
(2) Atomic file output
----------------------
New `utils::OutSink` writes to `<path>.tmp`, calls `sync_all()` on
`commit()`, and renames into place. If dropped without commit (panic,
crypto/IO error, ctrl-C), the temp file is unlinked so the existing
target is untouched. Stdout output is unaffected (no temp dance).
A new integration test (`atomic_output_no_stale_tmp_on_failure`)
verifies that a failed decrypt leaves neither the final output nor
the temp file behind.
(3) Argon2id + passphrase
-------------------------
New `KdfParams::Argon2id { salt, m_cost, t_cost, p_cost }` variant
encoded into the header (and authenticated as AAD), so tampering with
KDF params fails authentication on every chunk.
CLI surface (BREAKING):
* `--raw-key` is now optional; one of `--raw-key`, `--passphrase`,
`--passphrase-env <VAR>` is required.
* `--passphrase` prompts on the controlling terminal with echo off,
and asks for confirmation when encrypting.
* `--passphrase-env <VAR>` reads from a named env var; intended for
non-interactive use (scripts, tests). The env-table copy is a
known leak for that path.
* `--argon-memory <MiB>` (default 1024 = 1 GiB), `--argon-passes`
(default 2), `--argon-parallelism` (default 4). Names follow
argon2 RFC 9106 terminology; memory is MiB rather than KiB to
match how humans actually think about RAM. Defaults follow the
"Balanced" preset for 2026-era hardware (~1.5–4 s on a laptop).
The argon2 crate wants KiB internally, so the CLI value is
multiplied by 1024 with overflow-check.
(4) Secret hardening
--------------------
New `secrets` module provides:
* `SecretBytes32`: heap-allocated 32-byte buffer wrapped in
`Zeroizing<[u8; 32]>` and mlock'd via the `region` crate.
Field order ensures the lock guard drops *before* the buffer is
freed (otherwise munlock would target freed memory).
* `SecretVec`: fixed-capacity, mlock'd, zeroize-on-drop byte
buffer. `push()` rejects writes past the reserved capacity so
the underlying allocation never reallocates and moves — which
would invalidate the lock and leave a stale unzeroed copy on
the heap.
* `read_passphrase_tty()`: direct tty reader. On Unix, opens
`/dev/tty`, clears `ECHO` via `tcgetattr`/`tcsetattr` with an
RAII guard that restores termios on drop. On Windows, opens
`CONIN$`/`CONOUT$` and clears `ENABLE_ECHO_INPUT` via
`Get/SetConsoleMode`. Reads byte-by-byte into a pre-reserved
`SecretVec` (1024 bytes), so neither the Rust side nor the libc
side reallocates during read. This replaces `rpassword`, which
returned a `String` that grew by reallocation and left
unzeroed copies of typed passphrases on the heap.
`PartialEq` on `SecretVec` is constant-time-ish (length check +
xor-or accumulate) so the confirmation comparison doesn't early-out
on the first differing byte.
`disable_core_dumps()` calls `setrlimit(CORE, 0)` on Unix; on
Windows it's a no-op (WER/minidump suppression is a per-machine
policy and intentionally not done here).
`Cli`'s secret-bearing fields are moved out into local bindings at
the top of `run()` and the `Cli` is explicitly dropped, so they
don't sit in the parsed struct for the rest of the function.
`Cli.raw_key` is `Option<Zeroizing<String>>` so the field we own
zeroes itself on drop. Clap's own intermediate copies during
parsing are an accepted leak.
Threat model — what is and isn't covered
-----------------------------------------
Covered (best-effort):
* Secrets in coredumps → rlimit on Unix.
* Secrets paged to swap or hibernation → mlock on the AEAD key
and passphrase buffer.
* Half-written ciphertext on crash → atomic rename.
* Stale heap copies of typed passphrase → custom tty reader,
pre-reserved buffer.
* Stale stack/heap copies of the AEAD
key or passphrase post-process-exit → zeroize on drop.
Not covered (and not pretending to be):
* Live-process attackers with ptrace or `/proc/$pid/mem` access.
* The kernel's tty/line buffer.
* Clap's transient String allocations during arg parsing.
* The `environ` table copy of an env-var passphrase.
* Swap on systems without functioning mlock or with
`RLIMIT_MEMLOCK = 0`.
mlock is small (32 bytes + 1024 bytes — two pages at most on any
of the three target OSes), so it fits well under the typical
unprivileged `RLIMIT_MEMLOCK` of 64 KiB.
Portability
-----------
The whole binary targets Linux, macOS, and Windows 11 with the
same security properties where the OS supports them:
* `region` crate provides cross-platform mlock/munlock.
* `libc::tcgetattr`/`tcsetattr` covers Linux + macOS.
* `windows-sys` covers Console API.
* `rlimit` is gated to `cfg(unix)`.
The Windows tty path compiles in my head but is unverified on this
machine — there is no `x86_64-pc-windows-*` target installed and
no Windows runner. Treat that path as "best-effort, needs CI on
Windows" until exercised.
Files written by the previous v0.10 (Raw KDF, BE32 STREAM) are
still readable: the wire format is unchanged for that path.
Test plan
---------
Existing 17 integration tests pass unchanged. Two new tests:
* `roundtrip_passphrase_argon2id` — encrypts and decrypts via
`--passphrase-env` with cheap argon2 params (8 MiB / 1 pass) so
the test stays fast; also verifies that a wrong passphrase
fails.
* `atomic_output_no_stale_tmp_on_failure` — wrong-key decrypt
leaves neither the final file nor the `.tmp` in place.
Manual sanity (not automated): run with `--passphrase` on a
terminal and confirm echo is off and confirmation works.
Follow-ups (still in TODO.md)
-----------------------------
* Multi-threaded encrypt pipeline (now feasible — manual nonces).
* Length-committed mode + random-access decrypt fast path.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Introduce a self-describing on-disk format and use it to address several
shortcomings of the 0.9 file layout, where the file simply began with a
raw 19-byte STREAM nonce prefix and used a hardcoded 64 KiB chunk size.
What changed for users
----------------------
* fcry files now start with a 16-byte header: magic ("fcry"), version,
algorithm id, flags, reserved byte, plaintext chunk_size (u32 LE),
KDF id + params, then the 19-byte nonce prefix. The full encoded
header is bound as AAD to every chunk, so tampering with chunk_size,
algorithm id, nonce prefix, or any future KDF parameter causes
authentication failure on every chunk -- not just the first.
* New `--chunk-size` CLI flag (encryption only). The decryptor reads
the chunk size from the header, so files encrypted with a non-default
size decrypt without the user having to remember it.
* Default plaintext chunk size raised from 64 KiB to 1 MiB.
* Bad input is now reported as an error instead of panicking: empty
ciphertext, truncated final chunk, wrong magic, bad version, zero
chunk_size, unknown algorithm id, and short --raw-key all return a
non-zero exit status with a diagnostic on stderr.
* Empty plaintext now produces a valid (authenticated) empty
ciphertext instead of panicking; the decryptor verifies it.
* `main` exits with status 1 on error (previously it printed and
returned 0).
This is a breaking change to the file format: 0.9.x files have no magic
or header and cannot be read by 0.10.x. Version bumped to 0.10.0.
Why this approach
-----------------
The header-as-AAD pattern is the standard way to make file-format
metadata tamper-evident without a separate signature: any bit-flip in
the header propagates into every chunk's authentication tag check, so
an attacker cannot, for example, change chunk_size to mis-frame the
stream or downgrade the algorithm id.
Storing chunk_size in the header (rather than fixing it at compile
time) lets us experiment with chunk sizes without breaking decrypt
compatibility, and is preparation for the parallel-pipeline work in
Roadmap 1.0 where worker count and chunk size interact.
The KDF section is a tagged variant (currently only `Raw`) so that
adding Argon2id later only adds a new variant + its salt/cost fields;
existing files keep decrypting because they carry `kdf_id = 0`.
Other changes bundled in
------------------------
* Switch RNG from `rand` (0.10) to `getrandom` (0.3). We only need
OS-provided random bytes for the nonce prefix; pulling in the full
`rand` crate for one `OsRng.fill_bytes` call was overkill, and
`rand` 0.10's `OsRng` API churn makes `getrandom` the cleaner fit.
* `FcryError` gains a `Format(String)` variant for header / framing
errors and a `From<getrandom::Error>` impl (replacing the
`rand::Error` impl).
* Drop the noisy `[reader]` / `[encrypt]` / `[decrypt]` stderr
tracing prints and the `dbg!(&cli.raw_key)` (which leaked the key
to stderr).
* Replace `unwrap()` on file open / create with `?` so I/O errors
surface as structured `FcryError::Io` instead of aborting.
* Remove the unused `AheadReader::read_exact` wrapper -- the
decryptor now reads the header through the underlying `BufRead`
directly before wrapping it in `AheadReader`.
Tests
-----
Add `tests/roundtrip.rs` (assert_cmd + tempfile) covering: empty
input, single byte, sub-chunk, exact chunk, chunk+1, multi-chunk,
custom small chunk size (4096), pathological 1-byte chunk size,
stdin/stdout pipe mode, wrong key rejection, tampered header,
tampered ciphertext, truncated ciphertext, bad magic, short raw key,
and the header-is-authoritative property (encrypt with a weird chunk
size, decrypt without specifying one). Also adds a unit test in
`header.rs` for header encode/decode roundtrip and bad-magic rejection.
TODO.md trimmed to the concrete follow-up sequence (manual STREAM
nonces, secrets/rlimit, atomic output, argon2id KDF + prompt,
multi-threaded pipeline, length-committed mode).
Test plan
---------
* `cargo clippy && cargo clippy --tests` -- clean.
* `cargo +nightly fmt` -- no diff.
* `cargo test` -- 16 integration + 2 header unit tests pass.
* Manual: `echo hi | fcry --raw-key 0123456789abcdef0123456789abcdef
| fcry -d --raw-key 0123456789abcdef0123456789abcdef` prints `hi`.
Trailers
--------
Refs: TODO.md (Roadmap 1.0 follow-up sequence)
Breaking-Change: file format; 0.9.x files cannot be decrypted by 0.10.x
ddidderr
