pub struct Params { /* private fields */ }Expand description
Validated Argon2 cost parameters.
Holds exactly the fields of argon2_context that are not byte buffers:
m_cost, t_cost, lanes, threads and outlen. Password, salt, secret
and associated data are passed per call.
A Params value can only be built through a constructor that runs
validate_inputs, so lanes >= 1 always holds and the derived values
below never divide by zero.
§Known divergence from the C reference
The constructors validate the cost parameters immediately, whereas the C
checks salt length before m_cost. If a caller supplies both a bad
m_cost and a short salt, this crate reports the m_cost error at
Params construction time while the C reports ARGON2_SALT_TOO_SHORT.
Call validate_inputs directly to reproduce the C ordering exactly.
Implementations§
Source§impl Params
impl Params
Sourcepub const DEFAULT_M_COST: u32 = 19456
pub const DEFAULT_M_COST: u32 = 19456
Default memory cost in KiB (19 MiB), per the OWASP Argon2id guidance.
Sourcepub const DEFAULT_T_COST: u32 = 2
pub const DEFAULT_T_COST: u32 = 2
Default number of passes.
Sourcepub const DEFAULT_LANES: u32 = 1
pub const DEFAULT_LANES: u32 = 1
Default degree of parallelism.
Sourcepub const DEFAULT_OUTPUT_LEN: usize = 32
pub const DEFAULT_OUTPUT_LEN: usize = 32
Default tag length in bytes.
Sourcepub const fn new(
m_cost: u32,
t_cost: u32,
lanes: u32,
output_len: usize,
) -> Result<Params, Error>
pub const fn new( m_cost: u32, t_cost: u32, lanes: u32, output_len: usize, ) -> Result<Params, Error>
Validate and build parameters, with threads == lanes.
This matches argon2_hash(), which sets both context.lanes and
context.threads from its single parallelism argument.
§Errors
Any of the cost-parameter errors from validate_inputs.
Sourcepub const fn new_with_threads(
m_cost: u32,
t_cost: u32,
lanes: u32,
threads: u32,
output_len: usize,
) -> Result<Params, Error>
pub const fn new_with_threads( m_cost: u32, t_cost: u32, lanes: u32, threads: u32, output_len: usize, ) -> Result<Params, Error>
Validate and build parameters with an explicit thread count.
threads is a pure performance knob: it does not affect the tag.
Only lanes does. The effective count is min(threads, lanes), see
Params::effective_threads.
use argon2_rust::{Algorithm, Argon2, Params, Version};
// Four lanes of work, but never more than two OS threads to run them.
let budgeted = Params::new_with_threads(64, 1, 4, 2, 32)?;
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::new_with_threads(64, 1, 2, 8, 32)?;
assert_eq!(oversubscribed.effective_threads(), 2);
// `Params::new` is exactly this call with `threads == lanes`.
let full = Params::new(64, 1, 4, 32)?;
assert_eq!(full, Params::new_with_threads(64, 1, 4, 4, 32)?);
// 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")?,
);§Errors
Any of the cost-parameter errors from validate_inputs.
Sourcepub const fn validate_for(
&self,
pwd_len: usize,
salt_len: usize,
secret_len: usize,
ad_len: usize,
) -> Result<(), Error>
pub const fn validate_for( &self, pwd_len: usize, salt_len: usize, secret_len: usize, ad_len: usize, ) -> Result<(), Error>
Run the full validate_inputs() sequence for a concrete call.
core calls this on every hash so the salt/password/secret/ad checks
fire in the C’s order.
§Errors
Any error from validate_inputs.
Sourcepub const fn threads(&self) -> u32
pub const fn threads(&self) -> u32
Requested worker threads (context.threads). Does not affect the tag.
Sourcepub const fn output_len(&self) -> usize
pub const fn output_len(&self) -> usize
Tag length in bytes (context.outlen).
Sourcepub const fn effective_threads(&self) -> u32
pub const fn effective_threads(&self) -> u32
min(threads, lanes), as argon2_ctx computes it.
Sourcepub const fn memory_layout(&self) -> (u32, u32, u32)
pub const fn memory_layout(&self) -> (u32, u32, u32)
Step 2 of argon2_ctx(): align the memory size.
memory_blocks = m_cost;
if (memory_blocks < 2 * SYNC_POINTS * lanes)
memory_blocks = 2 * SYNC_POINTS * lanes;
segment_length = memory_blocks / (lanes * SYNC_POINTS);
memory_blocks = segment_length * (lanes * SYNC_POINTS);
lane_length = segment_length * SYNC_POINTS;Returns (memory_blocks, segment_length, lane_length). No overflow is
possible: lanes <= MAX_LANES (0xFF_FFFF), so lanes * SYNC_POINTS
fits comfortably in u32, and segment_length * lanes * SYNC_POINTS
is bounded by the original memory_blocks <= MAX_MEMORY.
Sourcepub const fn memory_blocks(&self) -> u32
pub const fn memory_blocks(&self) -> u32
Number of 1 KiB blocks the arena needs (instance.memory_blocks).
Sourcepub const fn segment_length(&self) -> u32
pub const fn segment_length(&self) -> u32
Blocks per segment (instance.segment_length).
Sourcepub const fn lane_length(&self) -> u32
pub const fn lane_length(&self) -> u32
Blocks per lane (instance.lane_length = segment_length * SYNC_POINTS).