ddidderr/fcry
1
0
Fork 0
Code Issues 2 Pull Requests Projects Releases Wiki Activity

feat!: argon2id passphrases, secret hardening, atomic output, manual STREAM

Browse Source 
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>
This commit is contained in:
ddidderr
2026-05-02 18:26:44 +02:00
parent 4eee8e7a95
commit fe65e1f899
10 changed files with 948 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Cargo.lock
Generated
+202 -6
View File
@@ -48,7 +48,7 @@ version = "1.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
dependencies = [
"windows-sys",
"windows-sys 0.61.2",
]
[[package]]
@@ -59,7 +59,19 @@ checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
dependencies = [
"anstyle",
"once_cell_polyfill",
"windows-sys",
"windows-sys 0.61.2",
]
[[package]]
name = "argon2"
version = "0.5.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3c3610892ee6e0cbce8ae2700349fcf8f98adb0dbfbee85aec3c9179d29cc072"
dependencies = [
"base64ct",
"blake2",
"cpufeatures",
"password-hash",
]
[[package]]
@@ -77,12 +89,42 @@ dependencies = [
"wait-timeout",
]
[[package]]
name = "base64ct"
version = "1.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
[[package]]
name = "bitflags"
version = "1.3.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
[[package]]
name = "bitflags"
version = "2.11.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
[[package]]
name = "blake2"
version = "0.10.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "46502ad458c9a52b69d4d4d32775c788b7a1b85e8bc9d482d92250fc0e3f8efe"
dependencies = [
"digest",
]
[[package]]
name = "block-buffer"
version = "0.10.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
dependencies = [
"generic-array",
]
[[package]]
name = "bstr"
version = "1.12.1"
@@ -207,6 +249,17 @@ version = "0.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6184e33543162437515c2e2b48714794e37845ec9851711914eec9d308f6ebe8"
[[package]]
name = "digest"
version = "0.10.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
dependencies = [
"block-buffer",
"crypto-common",
"subtle",
]
[[package]]
name = "errno"
version = "0.3.14"
@@ -214,7 +267,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
dependencies = [
"libc",
"windows-sys",
"windows-sys 0.61.2",
]
[[package]]
@@ -227,11 +280,17 @@ checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
name = "fcry"
version = "0.10.0"
dependencies = [
"argon2",
"assert_cmd",
"chacha20poly1305",
"clap",
"getrandom 0.3.4",
"libc",
"region",
"rlimit",
"tempfile",
"windows-sys 0.59.0",
"zeroize",
]
[[package]]
@@ -300,6 +359,15 @@ version = "0.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
[[package]]
name = "mach2"
version = "0.4.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d640282b302c0bb0a2a8e0233ead9035e3bed871f0b7e81fe4a1ec829765db44"
dependencies = [
"libc",
]
[[package]]
name = "memchr"
version = "2.8.0"
@@ -324,6 +392,17 @@ version = "0.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381"
[[package]]
name = "password-hash"
version = "0.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "346f04948ba92c43e8469c1ee6736c7563d71012b17d40745260fe106aac2166"
dependencies = [
"base64ct",
"rand_core",
"subtle",
]
[[package]]
name = "poly1305"
version = "0.8.0"
@@ -401,17 +480,38 @@ version = "0.4.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f"
[[package]]
name = "region"
version = "3.0.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e6b6ebd13bc009aef9cd476c1310d49ac354d36e240cf1bd753290f3dc7199a7"
dependencies = [
"bitflags 1.3.2",
"libc",
"mach2",
"windows-sys 0.52.0",
]
[[package]]
name = "rlimit"
version = "0.10.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7043b63bd0cd1aaa628e476b80e6d4023a3b50eb32789f2728908107bd0c793a"
dependencies = [
"libc",
]
[[package]]
name = "rustix"
version = "1.1.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
dependencies = [
"bitflags",
"bitflags 2.11.1",
"errno",
"libc",
"linux-raw-sys",
"windows-sys",
"windows-sys 0.61.2",
]
[[package]]
@@ -476,7 +576,7 @@ dependencies = [
"getrandom 0.3.4",
"once_cell",
"rustix",
"windows-sys",
"windows-sys 0.61.2",
]
[[package]]
@@ -549,6 +649,24 @@ version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
[[package]]
name = "windows-sys"
version = "0.52.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
dependencies = [
"windows-targets",
]
[[package]]
name = "windows-sys"
version = "0.59.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
dependencies = [
"windows-targets",
]
[[package]]
name = "windows-sys"
version = "0.61.2"
@@ -558,6 +676,70 @@ dependencies = [
"windows-link",
]
[[package]]
name = "windows-targets"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
dependencies = [
"windows_aarch64_gnullvm",
"windows_aarch64_msvc",
"windows_i686_gnu",
"windows_i686_gnullvm",
"windows_i686_msvc",
"windows_x86_64_gnu",
"windows_x86_64_gnullvm",
"windows_x86_64_msvc",
]
[[package]]
name = "windows_aarch64_gnullvm"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
[[package]]
name = "windows_aarch64_msvc"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
[[package]]
name = "windows_i686_gnu"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
[[package]]
name = "windows_i686_gnullvm"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
[[package]]
name = "windows_i686_msvc"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
[[package]]
name = "windows_x86_64_gnu"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
[[package]]
name = "windows_x86_64_gnullvm"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
[[package]]
name = "windows_x86_64_msvc"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
[[package]]
name = "wit-bindgen"
version = "0.57.1"
@@ -569,3 +751,17 @@ name = "zeroize"
version = "1.8.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b97154e67e32c85465826e8bcc1c59429aaaf107c1e4a9e53c8d8ccd5eff88d0"
dependencies = [
"zeroize_derive",
]
[[package]]
name = "zeroize_derive"
version = "1.4.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "85a5b4158499876c763cb03bc4e49185d3cccbabb15b33c627f7884f43db852e"
dependencies = [
"proc-macro2",
"quote",
"syn",
]