Enum KdfPreset

Source

pub enum KdfPreset {
Show 13 variants    Fast,
    Balanced,
    Paranoid,
    FastMac,
    BalancedMac,
    ParanoidMac,
    FastX86,
    BalancedX86,
    ParanoidX86,
    FastArm,
    BalancedArm,
    ParanoidArm,
    Custom(KdfParams),
}

Expand description

Pre-tuned KdfParams sets.

Pick the variant that matches your target platform and security goal. Use Custom to supply entirely your own parameters.

Why device-specific presets? Apple Silicon has exceptional memory bandwidth (unified memory, ~400 GB/s on M2). The same parameters that take 2 seconds on an M2 may take 15+ seconds on a typical x86-64 server. Device-specific variants let you choose a cost that is consistent across the hardware you actually deploy on.

§Generic (cross-platform)

Suitable for any platform. Use these when you don’t know or don’t control the target hardware.

Preset	Peak RAM	Est. Mac M2	Est. x86-64
`Fast`	~128 MiB	~500 ms	~1.5 s
`Balanced`	~512 MiB	~2 s	~8–15 s
`Paranoid`	~768 MiB	~4–6 s	~20–30 s

§Apple Silicon (`*Mac`)

Harder parameters calibrated for Apple Silicon’s superior memory bandwidth. All three tiers assume at least 8 GiB unified memory (all M-series chips).

Preset	Peak RAM	Est. Mac M2	Est. Mac M3/M4
`FastMac`	~512 MiB	~2 s	faster
`BalancedMac`	~1 GiB	~5–12 s	faster
`ParanoidMac`	~3 GiB	~30–60 s	faster

§x86-64 (`*X86`)

Equivalent to Generic; provided as explicit named variants so code documents intent clearly.

Preset	Peak RAM	Est. x86-64
`FastX86`	~128 MiB	~1.5 s
`BalancedX86`	~512 MiB	~8–15 s
`ParanoidX86`	~768 MiB	~20–30 s

§Linux ARM64 (`*Arm`)

Tuned for AWS Graviton3 / similar high-end ARM servers. Raspberry Pi and lower-end ARM boards will be slower.

Preset	Peak RAM	Est. Graviton3
`FastArm`	~256 MiB	~3 s
`BalancedArm`	~512 MiB	~10–20 s
`ParanoidArm`	~768 MiB	~30–50 s

§Custom

Custom(KdfParams) lets you supply exactly the parameters you measured and tuned for your own hardware.

Variants§

§

Fast

~128 MiB · scrypt 2¹⁶ · ~64 MiB, 3 iters each.

§

Balanced

~512 MiB · scrypt 2¹⁷ · ~256 MiB, 4 iters each.

§

Paranoid

~768 MiB · scrypt 2¹⁸ · ~512 MiB, 5 iters each.

§

FastMac

Dev / CI on macOS. ~512 MiB · scrypt 2¹⁷ · ~256 MiB, 4 iters each.

§

BalancedMac

Production on macOS (Apple Silicon). ~1 GiB · scrypt 2¹⁸ · ~512 MiB, 4 iters each.

§

ParanoidMac

Maximum security on macOS. ~3 GiB · scrypt 2²⁰ · ~1 GiB, 4 iters each. Assumes 8+ GiB unified memory (all M-series chips).

§

FastX86

Dev / CI on x86-64. Same params as Fast.

§

BalancedX86

Production on x86-64. Same params as Balanced.

§

ParanoidX86

Maximum security on x86-64. Same params as Paranoid.

§

FastArm

Dev / CI on Linux ARM64. ~256 MiB · scrypt 2¹⁶ · ~128 MiB, 3 iters each.

§

BalancedArm

Production on Linux ARM64. ~512 MiB · scrypt 2¹⁷ · ~256 MiB, 5 iters each.

§

ParanoidArm

Maximum security on Linux ARM64. ~768 MiB · scrypt 2¹⁸ · ~512 MiB, 5 iters each.

§

Custom(KdfParams)

Fully user-defined parameters. Use when you have measured and tuned KDF cost on your own hardware.

§Example

use toolkit_zero::encryption::timelock::*;
let p = KdfPreset::Custom(KdfParams {
    pass1: Argon2PassParams { m_cost: 262_144, t_cost: 3, p_cost: 1 },
    pass2: ScryptPassParams { log_n: 16, r: 8, p: 1 },
    pass3: Argon2PassParams { m_cost: 131_072, t_cost: 3, p_cost: 1 },
});

Implementations§

Source §

impl KdfPreset

Source

pub fn params(self) -> KdfParams

Return the KdfParams for this preset.

Examples found in repository ?

examples/timelock_round_trip.rs (line 32)

24fn main() {
25    // ── Encryption side ───────────────────────────────────────────────────────
26    // Generate fresh salts.  Salts are NOT secret — store them in plaintext
27    // alongside the ciphertext so the decryption side can reproduce the key.
28    let salts = TimeLockSalts::generate();
29
30    // Use a deliberately fast preset so the example finishes quickly.
31    // In production use KdfPreset::Balanced or stronger.
32    let kdf = KdfPreset::Balanced.params();
33
34    // Lock to any Tuesday at 18:00 (hour-precision window = the full 18:00–18:59 block).
35    let cadence   = TimeLockCadence::DayOfWeek(Weekday::Tuesday);
36    let lock_time = TimeLockTime::new(18, 0).unwrap();
37
38    println!("Deriving encryption key (this may take a few seconds)…");
39    let enc_key = TimelockBuilder::encrypt()
40        .cadence(cadence.clone())
41        .time(lock_time)
42        .precision(TimePrecision::Hour)
43        .format(TimeFormat::Hour24)
44        .salts(salts.clone())
45        .kdf(kdf)
46        .derive()
47        .expect("encryption-side key derivation failed");
48
49    println!("enc_key[:8] = {:02x?}", &enc_key.as_bytes()[..8]);
50
51    // Pack every setting — including salts and KDF params — into a compact header.
52    // This header goes into the ciphertext in plaintext; nothing here is secret.
53    let header = pack(
54        TimePrecision::Hour,
55        TimeFormat::Hour24,
56        &cadence,
57        salts,
58        kdf,
59    );
60
61    // ── Decryption side ───────────────────────────────────────────────────────
62    // Load `header` from the ciphertext and call TimelockBuilder::decrypt at the
63    // matching time slot.  All settings are read from the header automatically.
64    println!("Deriving decryption key from system clock…");
65    let dec_key = TimelockBuilder::decrypt(header)
66        .derive()
67        .expect("decryption-side key derivation failed");
68
69    println!("dec_key[:8] = {:02x?}", &dec_key.as_bytes()[..8]);
70
71    // ── Verdict ───────────────────────────────────────────────────────────────
72    if enc_key.as_bytes() == dec_key.as_bytes() {
73        println!("\nKeys match ✓  — running on a Tuesday at 18:xx");
74    } else {
75        println!("\nKeys differ — not running on a Tuesday at 18:xx (expected outside that window)");
76    }
77}