Struct ParamsBuilder

Source

pub struct ParamsBuilder { /* private fields */ }

Expand description

Builder for Params.

Every setter is a const fn taking self by value, so a Params can be built in a const item — see ParamsBuilder::build_or_panic. The builder starts from ParamsBuilder::DEFAULT, so each setter is optional.

use argon2_rust::{Params, params::{Memory, TagLen}};

let params = Params::builder()
    .memory(Memory::mib(64))
    .passes(3)
    .lanes(4)
    .tag_len(TagLen::bytes(32))
    .build()?;
assert_eq!(params.memory(), Memory::mib(64));

Implementations§

Source §

impl ParamsBuilder

Source

pub const DEFAULT: ParamsBuilder

The starting point: OWASP’s Argon2id profile, 19 MiB, two passes, one lane, a 32-byte tag.

These are literals rather than a copy of Params::DEFAULT’s fields on purpose. Params::DEFAULT is built by this builder, so reading it here would be a cyclic const.

Source

pub const fn memory(self, memory: Memory) -> ParamsBuilder

Set the memory cost.

Source

pub const fn passes(self, passes: u32) -> ParamsBuilder

Set the number of passes (t_cost in the C, t= in a PHC string).

Source

pub const fn lanes(self, lanes: u32) -> ParamsBuilder

Set the degree of parallelism (p= in a PHC string).

This one feeds the tag. Changing it changes the hash.

Source

pub const fn threads(self, threads: u32) -> ParamsBuilder

Set the worker-thread budget.

A pure performance knob: it does not affect the tag. Only lanes does. Left unset it tracks ParamsBuilder::lanes, which is what argon2_hash() does — it sets both context.lanes and context.threads from its single parallelism argument. The effective count is min(threads, lanes), see Params::effective_threads.

use argon2_rust::{Algorithm, Argon2, Params, Version, params::Memory};

// Four lanes of work, but never more than two OS threads to run them.
let budgeted = Params::builder()
    .memory(Memory::kib(64))
    .passes(1)
    .lanes(4)
    .threads(2)
    .build()?;
assert_eq!((budgeted.lanes(), budgeted.threads()), (4, 2));
assert_eq!(budgeted.effective_threads(), 2);

// Asking for more threads than lanes is legal, and the extra workers
// simply have no lane to claim.
let oversubscribed = Params::builder()
    .memory(Memory::kib(64))
    .passes(1)
    .lanes(2)
    .threads(8)
    .build()?;
assert_eq!(oversubscribed.effective_threads(), 2);

// Leaving it unset is exactly `threads == lanes`.
let full = Params::builder()
    .memory(Memory::kib(64))
    .passes(1)
    .lanes(4)
    .build()?;
assert_eq!(full, budgeted.to_builder().threads(4).build()?);
assert_eq!(full.threads(), 4);

// And the knob really is free of the tag: same `lanes`, same bytes,
// whichever thread budget produced them.
let two_workers = Argon2::new(Algorithm::Argon2id, Version::V0x13, budgeted);
let four_workers = Argon2::new(Algorithm::Argon2id, Version::V0x13, full);
assert_eq!(
    two_workers.hash(b"password", b"somesalt")?,
    four_workers.hash(b"password", b"somesalt")?,
);

Source

pub const fn tag_len(self, tag_len: TagLen) -> ParamsBuilder

Set the tag length.

Source

pub const fn build(self) -> Result<Params, Error>

Validate and produce Params.

§Errors

Any of the cost-parameter errors from validate_inputs, plus Error::OutputTooLong and Error::MemoryTooMuch for values too large for this target at all.

Source

pub const fn build_or_panic(self) -> Params

Validate and produce Params, panicking on invalid parameters.

This exists for const items, where a panic is a compile error:

use argon2_rust::{Params, params::Memory};

const LOGIN: Params = Params::builder()
    .memory(Memory::mib(64))
    .passes(3)
    .build_or_panic();
assert_eq!(LOGIN.passes(), 3);

§Panics

If the parameters are invalid. Use ParamsBuilder::build anywhere a runtime error is the right answer — it is the normal way in, and it is why no fallible path in this crate panics.