Skip to main content

Crate luks_and

Crate luks_and 

Source
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§

Error

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_box on every accumulator step prevents the compiler from proving anything about acc mid-loop (e.g. exiting early once it saturates), not merely from short-circuiting the final comparison.
derive
Derive the key from both factors. salt must be exactly SALT_LEN bytes.
hex_decode_into
Decode exactly out.len() bytes of lowercase/uppercase hex into out.
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::parse alone 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::SelfTest on any mismatch.
verify_tag
Verify a derived key against an expected tag in constant time.