Struct TimelockBuilder 

pub struct TimelockBuilder { /* private fields */ }

Fluent builder for [timelock] / timelock_async key derivation.

Provides a readable alternative to the 7-positional-argument timelock() function. Create a builder via TimelockBuilder::encrypt (encryption path, _at) or TimelockBuilder::decrypt (decryption path, _now), optionally configure it with setter methods, then call derive or derive_async.

Encryption (key-at path)

All of time, salts, and kdf are required. cadence, precision, and format are optional and fall back to sensible defaults:

• cadence → TimeLockCadence::None (no calendar constraint)
• precision → TimePrecision::Minute
• format → TimeFormat::Hour24

let salts = TimeLockSalts::generate();
let kdf   = KdfPreset::Balanced.params();

let key = TimelockBuilder::encrypt()
    .time(TimeLockTime::new(14, 37).unwrap())
    .salts(salts)
    .kdf(kdf)
    .derive()
    .unwrap();

Decryption (key-now path)

Pass the TimeLockParams header stored in the ciphertext. No other configuration is required; all settings are read from params.

let key = TimelockBuilder::decrypt(header).derive().unwrap();

Implementations

impl TimelockBuilder

pub fn encrypt() -> Self

Begin configuring an encryption (key-at) derivation.

Requires enc-timelock-keygen-input (or async variant) to call derive / derive_async.

Examples found in repository

examples/timelock_round_trip.rs (line 39)

fn main() {
    // ── Encryption side ───────────────────────────────────────────────────────
    // Generate fresh salts.  Salts are NOT secret — store them in plaintext
    // alongside the ciphertext so the decryption side can reproduce the key.
    let salts = TimeLockSalts::generate();

    // Use a deliberately fast preset so the example finishes quickly.
    // In production use KdfPreset::Balanced or stronger.
    let kdf = KdfPreset::Balanced.params();

    // Lock to any Tuesday at 18:00 (hour-precision window = the full 18:00–18:59 block).
    let cadence   = TimeLockCadence::DayOfWeek(Weekday::Tuesday);
    let lock_time = TimeLockTime::new(18, 0).unwrap();

    println!("Deriving encryption key (this may take a few seconds)…");
    let enc_key = TimelockBuilder::encrypt()
        .cadence(cadence.clone())
        .time(lock_time)
        .precision(TimePrecision::Hour)
        .format(TimeFormat::Hour24)
        .salts(salts.clone())
        .kdf(kdf)
        .derive()
        .expect("encryption-side key derivation failed");

    println!("enc_key[:8] = {:02x?}", &enc_key.as_bytes()[..8]);

    // Pack every setting — including salts and KDF params — into a compact header.
    // This header goes into the ciphertext in plaintext; nothing here is secret.
    let header = pack(
        TimePrecision::Hour,
        TimeFormat::Hour24,
        &cadence,
        salts,
        kdf,
    );

    // ── Decryption side ───────────────────────────────────────────────────────
    // Load `header` from the ciphertext and call TimelockBuilder::decrypt at the
    // matching time slot.  All settings are read from the header automatically.
    println!("Deriving decryption key from system clock…");
    let dec_key = TimelockBuilder::decrypt(header)
        .derive()
        .expect("decryption-side key derivation failed");

    println!("dec_key[:8] = {:02x?}", &dec_key.as_bytes()[..8]);

    // ── Verdict ───────────────────────────────────────────────────────────────
    if enc_key.as_bytes() == dec_key.as_bytes() {
        println!("\nKeys match ✓  — running on a Tuesday at 18:xx");
    } else {
        println!("\nKeys differ — not running on a Tuesday at 18:xx (expected outside that window)");
    }
}

pub fn decrypt(params: TimeLockParams) -> Self

Begin configuring a decryption (key-now) derivation from a stored header.

Requires enc-timelock-keygen-now (or async variant) to call derive / derive_async.

Examples found in repository

examples/timelock_round_trip.rs (line 65)

fn main() {
    // ── Encryption side ───────────────────────────────────────────────────────
    // Generate fresh salts.  Salts are NOT secret — store them in plaintext
    // alongside the ciphertext so the decryption side can reproduce the key.
    let salts = TimeLockSalts::generate();

    // Use a deliberately fast preset so the example finishes quickly.
    // In production use KdfPreset::Balanced or stronger.
    let kdf = KdfPreset::Balanced.params();

    // Lock to any Tuesday at 18:00 (hour-precision window = the full 18:00–18:59 block).
    let cadence   = TimeLockCadence::DayOfWeek(Weekday::Tuesday);
    let lock_time = TimeLockTime::new(18, 0).unwrap();

    println!("Deriving encryption key (this may take a few seconds)…");
    let enc_key = TimelockBuilder::encrypt()
        .cadence(cadence.clone())
        .time(lock_time)
        .precision(TimePrecision::Hour)
        .format(TimeFormat::Hour24)
        .salts(salts.clone())
        .kdf(kdf)
        .derive()
        .expect("encryption-side key derivation failed");

    println!("enc_key[:8] = {:02x?}", &enc_key.as_bytes()[..8]);

    // Pack every setting — including salts and KDF params — into a compact header.
    // This header goes into the ciphertext in plaintext; nothing here is secret.
    let header = pack(
        TimePrecision::Hour,
        TimeFormat::Hour24,
        &cadence,
        salts,
        kdf,
    );

    // ── Decryption side ───────────────────────────────────────────────────────
    // Load `header` from the ciphertext and call TimelockBuilder::decrypt at the
    // matching time slot.  All settings are read from the header automatically.
    println!("Deriving decryption key from system clock…");
    let dec_key = TimelockBuilder::decrypt(header)
        .derive()
        .expect("decryption-side key derivation failed");

    println!("dec_key[:8] = {:02x?}", &dec_key.as_bytes()[..8]);

    // ── Verdict ───────────────────────────────────────────────────────────────
    if enc_key.as_bytes() == dec_key.as_bytes() {
        println!("\nKeys match ✓  — running on a Tuesday at 18:xx");
    } else {
        println!("\nKeys differ — not running on a Tuesday at 18:xx (expected outside that window)");
    }
}

pub fn cadence(self, cadence: TimeLockCadence) -> Self

Set the calendar cadence (default: TimeLockCadence::None).

Examples found in repository

examples/timelock_round_trip.rs (line 40)

fn main() {
    // ── Encryption side ───────────────────────────────────────────────────────
    // Generate fresh salts.  Salts are NOT secret — store them in plaintext
    // alongside the ciphertext so the decryption side can reproduce the key.
    let salts = TimeLockSalts::generate();

    // Use a deliberately fast preset so the example finishes quickly.
    // In production use KdfPreset::Balanced or stronger.
    let kdf = KdfPreset::Balanced.params();

    // Lock to any Tuesday at 18:00 (hour-precision window = the full 18:00–18:59 block).
    let cadence   = TimeLockCadence::DayOfWeek(Weekday::Tuesday);
    let lock_time = TimeLockTime::new(18, 0).unwrap();

    println!("Deriving encryption key (this may take a few seconds)…");
    let enc_key = TimelockBuilder::encrypt()
        .cadence(cadence.clone())
        .time(lock_time)
        .precision(TimePrecision::Hour)
        .format(TimeFormat::Hour24)
        .salts(salts.clone())
        .kdf(kdf)
        .derive()
        .expect("encryption-side key derivation failed");

    println!("enc_key[:8] = {:02x?}", &enc_key.as_bytes()[..8]);

    // Pack every setting — including salts and KDF params — into a compact header.
    // This header goes into the ciphertext in plaintext; nothing here is secret.
    let header = pack(
        TimePrecision::Hour,
        TimeFormat::Hour24,
        &cadence,
        salts,
        kdf,
    );

    // ── Decryption side ───────────────────────────────────────────────────────
    // Load `header` from the ciphertext and call TimelockBuilder::decrypt at the
    // matching time slot.  All settings are read from the header automatically.
    println!("Deriving decryption key from system clock…");
    let dec_key = TimelockBuilder::decrypt(header)
        .derive()
        .expect("decryption-side key derivation failed");

    println!("dec_key[:8] = {:02x?}", &dec_key.as_bytes()[..8]);

    // ── Verdict ───────────────────────────────────────────────────────────────
    if enc_key.as_bytes() == dec_key.as_bytes() {
        println!("\nKeys match ✓  — running on a Tuesday at 18:xx");
    } else {
        println!("\nKeys differ — not running on a Tuesday at 18:xx (expected outside that window)");
    }
}

pub fn time(self, time: TimeLockTime) -> Self

Set the explicit lock time (required for the encryption path).

Examples found in repository

examples/timelock_round_trip.rs (line 41)

fn main() {
    // ── Encryption side ───────────────────────────────────────────────────────
    // Generate fresh salts.  Salts are NOT secret — store them in plaintext
    // alongside the ciphertext so the decryption side can reproduce the key.
    let salts = TimeLockSalts::generate();

    // Use a deliberately fast preset so the example finishes quickly.
    // In production use KdfPreset::Balanced or stronger.
    let kdf = KdfPreset::Balanced.params();

    // Lock to any Tuesday at 18:00 (hour-precision window = the full 18:00–18:59 block).
    let cadence   = TimeLockCadence::DayOfWeek(Weekday::Tuesday);
    let lock_time = TimeLockTime::new(18, 0).unwrap();

    println!("Deriving encryption key (this may take a few seconds)…");
    let enc_key = TimelockBuilder::encrypt()
        .cadence(cadence.clone())
        .time(lock_time)
        .precision(TimePrecision::Hour)
        .format(TimeFormat::Hour24)
        .salts(salts.clone())
        .kdf(kdf)
        .derive()
        .expect("encryption-side key derivation failed");

    println!("enc_key[:8] = {:02x?}", &enc_key.as_bytes()[..8]);

    // Pack every setting — including salts and KDF params — into a compact header.
    // This header goes into the ciphertext in plaintext; nothing here is secret.
    let header = pack(
        TimePrecision::Hour,
        TimeFormat::Hour24,
        &cadence,
        salts,
        kdf,
    );

    // ── Decryption side ───────────────────────────────────────────────────────
    // Load `header` from the ciphertext and call TimelockBuilder::decrypt at the
    // matching time slot.  All settings are read from the header automatically.
    println!("Deriving decryption key from system clock…");
    let dec_key = TimelockBuilder::decrypt(header)
        .derive()
        .expect("decryption-side key derivation failed");

    println!("dec_key[:8] = {:02x?}", &dec_key.as_bytes()[..8]);

    // ── Verdict ───────────────────────────────────────────────────────────────
    if enc_key.as_bytes() == dec_key.as_bytes() {
        println!("\nKeys match ✓  — running on a Tuesday at 18:xx");
    } else {
        println!("\nKeys differ — not running on a Tuesday at 18:xx (expected outside that window)");
    }
}

pub fn precision(self, precision: TimePrecision) -> Self

Set the time precision (default: TimePrecision::Minute).

Examples found in repository

examples/timelock_round_trip.rs (line 42)

fn main() {
    // ── Encryption side ───────────────────────────────────────────────────────
    // Generate fresh salts.  Salts are NOT secret — store them in plaintext
    // alongside the ciphertext so the decryption side can reproduce the key.
    let salts = TimeLockSalts::generate();

    // Use a deliberately fast preset so the example finishes quickly.
    // In production use KdfPreset::Balanced or stronger.
    let kdf = KdfPreset::Balanced.params();

    // Lock to any Tuesday at 18:00 (hour-precision window = the full 18:00–18:59 block).
    let cadence   = TimeLockCadence::DayOfWeek(Weekday::Tuesday);
    let lock_time = TimeLockTime::new(18, 0).unwrap();

    println!("Deriving encryption key (this may take a few seconds)…");
    let enc_key = TimelockBuilder::encrypt()
        .cadence(cadence.clone())
        .time(lock_time)
        .precision(TimePrecision::Hour)
        .format(TimeFormat::Hour24)
        .salts(salts.clone())
        .kdf(kdf)
        .derive()
        .expect("encryption-side key derivation failed");

    println!("enc_key[:8] = {:02x?}", &enc_key.as_bytes()[..8]);

    // Pack every setting — including salts and KDF params — into a compact header.
    // This header goes into the ciphertext in plaintext; nothing here is secret.
    let header = pack(
        TimePrecision::Hour,
        TimeFormat::Hour24,
        &cadence,
        salts,
        kdf,
    );

    // ── Decryption side ───────────────────────────────────────────────────────
    // Load `header` from the ciphertext and call TimelockBuilder::decrypt at the
    // matching time slot.  All settings are read from the header automatically.
    println!("Deriving decryption key from system clock…");
    let dec_key = TimelockBuilder::decrypt(header)
        .derive()
        .expect("decryption-side key derivation failed");

    println!("dec_key[:8] = {:02x?}", &dec_key.as_bytes()[..8]);

    // ── Verdict ───────────────────────────────────────────────────────────────
    if enc_key.as_bytes() == dec_key.as_bytes() {
        println!("\nKeys match ✓  — running on a Tuesday at 18:xx");
    } else {
        println!("\nKeys differ — not running on a Tuesday at 18:xx (expected outside that window)");
    }
}

pub fn format(self, format: TimeFormat) -> Self

Set the clock format (default: TimeFormat::Hour24).

Examples found in repository

examples/timelock_round_trip.rs (line 43)

fn main() {
    // ── Encryption side ───────────────────────────────────────────────────────
    // Generate fresh salts.  Salts are NOT secret — store them in plaintext
    // alongside the ciphertext so the decryption side can reproduce the key.
    let salts = TimeLockSalts::generate();

    // Use a deliberately fast preset so the example finishes quickly.
    // In production use KdfPreset::Balanced or stronger.
    let kdf = KdfPreset::Balanced.params();

    // Lock to any Tuesday at 18:00 (hour-precision window = the full 18:00–18:59 block).
    let cadence   = TimeLockCadence::DayOfWeek(Weekday::Tuesday);
    let lock_time = TimeLockTime::new(18, 0).unwrap();

    println!("Deriving encryption key (this may take a few seconds)…");
    let enc_key = TimelockBuilder::encrypt()
        .cadence(cadence.clone())
        .time(lock_time)
        .precision(TimePrecision::Hour)
        .format(TimeFormat::Hour24)
        .salts(salts.clone())
        .kdf(kdf)
        .derive()
        .expect("encryption-side key derivation failed");

    println!("enc_key[:8] = {:02x?}", &enc_key.as_bytes()[..8]);

    // Pack every setting — including salts and KDF params — into a compact header.
    // This header goes into the ciphertext in plaintext; nothing here is secret.
    let header = pack(
        TimePrecision::Hour,
        TimeFormat::Hour24,
        &cadence,
        salts,
        kdf,
    );

    // ── Decryption side ───────────────────────────────────────────────────────
    // Load `header` from the ciphertext and call TimelockBuilder::decrypt at the
    // matching time slot.  All settings are read from the header automatically.
    println!("Deriving decryption key from system clock…");
    let dec_key = TimelockBuilder::decrypt(header)
        .derive()
        .expect("decryption-side key derivation failed");

    println!("dec_key[:8] = {:02x?}", &dec_key.as_bytes()[..8]);

    // ── Verdict ───────────────────────────────────────────────────────────────
    if enc_key.as_bytes() == dec_key.as_bytes() {
        println!("\nKeys match ✓  — running on a Tuesday at 18:xx");
    } else {
        println!("\nKeys differ — not running on a Tuesday at 18:xx (expected outside that window)");
    }
}

pub fn salts(self, salts: TimeLockSalts) -> Self

Set the KDF salts (required for the encryption path).

Examples found in repository

examples/timelock_round_trip.rs (line 44)

fn main() {
    // ── Encryption side ───────────────────────────────────────────────────────
    // Generate fresh salts.  Salts are NOT secret — store them in plaintext
    // alongside the ciphertext so the decryption side can reproduce the key.
    let salts = TimeLockSalts::generate();

    // Use a deliberately fast preset so the example finishes quickly.
    // In production use KdfPreset::Balanced or stronger.
    let kdf = KdfPreset::Balanced.params();

    // Lock to any Tuesday at 18:00 (hour-precision window = the full 18:00–18:59 block).
    let cadence   = TimeLockCadence::DayOfWeek(Weekday::Tuesday);
    let lock_time = TimeLockTime::new(18, 0).unwrap();

    println!("Deriving encryption key (this may take a few seconds)…");
    let enc_key = TimelockBuilder::encrypt()
        .cadence(cadence.clone())
        .time(lock_time)
        .precision(TimePrecision::Hour)
        .format(TimeFormat::Hour24)
        .salts(salts.clone())
        .kdf(kdf)
        .derive()
        .expect("encryption-side key derivation failed");

    println!("enc_key[:8] = {:02x?}", &enc_key.as_bytes()[..8]);

    // Pack every setting — including salts and KDF params — into a compact header.
    // This header goes into the ciphertext in plaintext; nothing here is secret.
    let header = pack(
        TimePrecision::Hour,
        TimeFormat::Hour24,
        &cadence,
        salts,
        kdf,
    );

    // ── Decryption side ───────────────────────────────────────────────────────
    // Load `header` from the ciphertext and call TimelockBuilder::decrypt at the
    // matching time slot.  All settings are read from the header automatically.
    println!("Deriving decryption key from system clock…");
    let dec_key = TimelockBuilder::decrypt(header)
        .derive()
        .expect("decryption-side key derivation failed");

    println!("dec_key[:8] = {:02x?}", &dec_key.as_bytes()[..8]);

    // ── Verdict ───────────────────────────────────────────────────────────────
    if enc_key.as_bytes() == dec_key.as_bytes() {
        println!("\nKeys match ✓  — running on a Tuesday at 18:xx");
    } else {
        println!("\nKeys differ — not running on a Tuesday at 18:xx (expected outside that window)");
    }
}

pub fn kdf(self, kdf: KdfParams) -> Self

Set the KDF parameters (required for the encryption path).

Examples found in repository

examples/timelock_round_trip.rs (line 45)

fn main() {
    // ── Encryption side ───────────────────────────────────────────────────────
    // Generate fresh salts.  Salts are NOT secret — store them in plaintext
    // alongside the ciphertext so the decryption side can reproduce the key.
    let salts = TimeLockSalts::generate();

    // Use a deliberately fast preset so the example finishes quickly.
    // In production use KdfPreset::Balanced or stronger.
    let kdf = KdfPreset::Balanced.params();

    // Lock to any Tuesday at 18:00 (hour-precision window = the full 18:00–18:59 block).
    let cadence   = TimeLockCadence::DayOfWeek(Weekday::Tuesday);
    let lock_time = TimeLockTime::new(18, 0).unwrap();

    println!("Deriving encryption key (this may take a few seconds)…");
    let enc_key = TimelockBuilder::encrypt()
        .cadence(cadence.clone())
        .time(lock_time)
        .precision(TimePrecision::Hour)
        .format(TimeFormat::Hour24)
        .salts(salts.clone())
        .kdf(kdf)
        .derive()
        .expect("encryption-side key derivation failed");

    println!("enc_key[:8] = {:02x?}", &enc_key.as_bytes()[..8]);

    // Pack every setting — including salts and KDF params — into a compact header.
    // This header goes into the ciphertext in plaintext; nothing here is secret.
    let header = pack(
        TimePrecision::Hour,
        TimeFormat::Hour24,
        &cadence,
        salts,
        kdf,
    );

    // ── Decryption side ───────────────────────────────────────────────────────
    // Load `header` from the ciphertext and call TimelockBuilder::decrypt at the
    // matching time slot.  All settings are read from the header automatically.
    println!("Deriving decryption key from system clock…");
    let dec_key = TimelockBuilder::decrypt(header)
        .derive()
        .expect("decryption-side key derivation failed");

    println!("dec_key[:8] = {:02x?}", &dec_key.as_bytes()[..8]);

    // ── Verdict ───────────────────────────────────────────────────────────────
    if enc_key.as_bytes() == dec_key.as_bytes() {
        println!("\nKeys match ✓  — running on a Tuesday at 18:xx");
    } else {
        println!("\nKeys differ — not running on a Tuesday at 18:xx (expected outside that window)");
    }
}

pub fn derive(self) -> Result<TimeLockKey, TimeLockError>

Derive the key synchronously.

Delegates directly to [timelock].

Examples found in repository

examples/timelock_round_trip.rs (line 46)

fn main() {
    // ── Encryption side ───────────────────────────────────────────────────────
    // Generate fresh salts.  Salts are NOT secret — store them in plaintext
    // alongside the ciphertext so the decryption side can reproduce the key.
    let salts = TimeLockSalts::generate();

    // Use a deliberately fast preset so the example finishes quickly.
    // In production use KdfPreset::Balanced or stronger.
    let kdf = KdfPreset::Balanced.params();

    // Lock to any Tuesday at 18:00 (hour-precision window = the full 18:00–18:59 block).
    let cadence   = TimeLockCadence::DayOfWeek(Weekday::Tuesday);
    let lock_time = TimeLockTime::new(18, 0).unwrap();

    println!("Deriving encryption key (this may take a few seconds)…");
    let enc_key = TimelockBuilder::encrypt()
        .cadence(cadence.clone())
        .time(lock_time)
        .precision(TimePrecision::Hour)
        .format(TimeFormat::Hour24)
        .salts(salts.clone())
        .kdf(kdf)
        .derive()
        .expect("encryption-side key derivation failed");

    println!("enc_key[:8] = {:02x?}", &enc_key.as_bytes()[..8]);

    // Pack every setting — including salts and KDF params — into a compact header.
    // This header goes into the ciphertext in plaintext; nothing here is secret.
    let header = pack(
        TimePrecision::Hour,
        TimeFormat::Hour24,
        &cadence,
        salts,
        kdf,
    );

    // ── Decryption side ───────────────────────────────────────────────────────
    // Load `header` from the ciphertext and call TimelockBuilder::decrypt at the
    // matching time slot.  All settings are read from the header automatically.
    println!("Deriving decryption key from system clock…");
    let dec_key = TimelockBuilder::decrypt(header)
        .derive()
        .expect("decryption-side key derivation failed");

    println!("dec_key[:8] = {:02x?}", &dec_key.as_bytes()[..8]);

    // ── Verdict ───────────────────────────────────────────────────────────────
    if enc_key.as_bytes() == dec_key.as_bytes() {
        println!("\nKeys match ✓  — running on a Tuesday at 18:xx");
    } else {
        println!("\nKeys differ — not running on a Tuesday at 18:xx (expected outside that window)");
    }
}

pub async fn derive_async(self) -> Result<TimeLockKey, TimeLockError>

Derive the key asynchronously.

Delegates directly to timelock_async. The blocking KDF work is offloaded to a Tokio blocking thread.