Expand description
luks-and: derive a key that requires BOTH a keyfile AND a passphrase.
This crate is the pure, side-effect-free core: key derivation, the
descriptor format, the integrity tag, a constant-time compare, and a
known-answer self-test. All process hardening and I/O lives in the binary
(main.rs), so everything here is directly testable.
§Construction (v0.1)
pepper = BLAKE2b-512("luks-and/pepper/v0.1" ‖ lp(keyfile))[..32]
key = Argon2id(password = passphrase,
salt = salt, // 16 random bytes, in descriptor
secret = pepper, // Argon2 "K"
m, t, p, key_len)
tag = BLAKE2b-512("luks-and/tag/v0.1" ‖ lp(key))[..16]where lp(x) = u64_le(x.len()) ‖ x.
The passphrase is memory-hard stretched, so a leaked keyfile does not make it cheap to brute force; the keyfile is bound in as the Argon2 secret, so a leaked passphrase is useless without it. The random per-descriptor salt makes every enrolled key independent, so the same (keyfile, passphrase) pair yields unrelated keys on different volumes.
The tag is a public 128-bit fingerprint of the derived key. It lets the
caller confirm that a given (keyfile, passphrase, descriptor) reproduces the
enrolled key before invoking cryptsetup, and distinguishes wrong inputs
from a corrupt header. It reveals nothing invertible, but IS a brute-force
oracle for anyone who already holds the keyfile — so the descriptor must be
stored with the LUKS header, never with the keyfile.
Structs§
- Descriptor
- Non-secret metadata needed to reproduce a derivation: everything except the keyfile and passphrase. Stored with the LUKS header; never with the keyfile.
- Params
- Argon2id cost parameters plus derived-key length.
Enums§
Constants§
- KEYFILE_
MAX - KEYFILE_
MIN - Keyfile size sanity bounds. Below the minimum is almost certainly a truncated copy or a mistake and guts the “leaked passphrase is useless” half of the scheme; the maximum stops a wrong path (a disk image) from being silently hashed.
- MAX_
KEY_ LEN - MAX_
M_ COST_ KIB - MAX_
P_ COST - MAX_
T_ COST - MIN_
KEY_ LEN - MIN_
M_ COST_ KIB - Argon2 parameter bounds. The memory floor keeps a typo’d descriptor from silently producing a weak KDF; the ceiling stops a hostile descriptor from requesting an enormous arena.
- MIN_
P_ COST - MIN_
T_ COST - PASSPHRASE_
MAX - Maximum passphrase length accepted from stdin.
- SALT_
LEN - Length of the random salt stored in a descriptor.
- TAG_LEN
- Length of the integrity tag (128-bit truncation of BLAKE2b-512).
Functions§
- ct_eq
- Constant-time equality. Length is not treated as secret (tags are fixed
length).
black_boxon every accumulator step prevents the compiler from proving anything aboutaccmid-loop (e.g. exiting early once it saturates), not merely from short-circuiting the final comparison. - derive
- Derive the key from both factors.
saltmust be exactlySALT_LENbytes. - hex_
decode_ into - Decode exactly
out.len()bytes of lowercase/uppercase hex intoout. - hex_
encode - key_tag
- Public 128-bit integrity fingerprint of a derived key.
- parse_
dec_ u32 - Strict decimal parse: ASCII digits only, non-empty.
str::parsealone also accepts a leading+, which would make the descriptor format non-canonical (“t_cost = +4” round-trips to a different byte string). - parse_
memory_ kib - Parse a memory size in KiB. A bare integer is KiB; suffixes
K/KiB,M/MiB,G/GiB(case-insensitive, binary units) scale it. Overflow is an error rather than a wrap. - scheme_
string - Human-readable summary of the compiled scheme (all public).
- selftest
- Run the known-answer test. Returns
Error::SelfTeston any mismatch. - verify_
tag - Verify a derived key against an expected tag in constant time.