Module argon2i

Available on crate feature dep_orion only.

Argon2i password hashing function as described in the P-H-C specification.

About:

Argon2i version 1.3. This implementation is available with features safe_api and alloc.

Note:

This implementation only supports a single thread/lane.

Parameters:

• expected: The expected derived key.
• password: Password.
• salt: Salt value.
• iterations: Iteration count.
• memory: Memory size in kibibytes (KiB).
• secret: Optional secret value used for hashing.
• ad: Optional associated data used for hashing.
• dst_out: Destination buffer for the derived key. The length of the derived key is implied by the length of dst_out.

Errors:

An error will be returned if:

• The length of the password is greater than u32::MAX.
• The length of the salt is greater than u32::MAX or less than 8.
• The length of the secret is greater than u32::MAX.
• The length of the ad is greater than u32::MAX.
• The length of dst_out is greater than u32::MAX or less than 4.
• iterations is less than 1.
• memory is less than 8.
• The hashed password does not match the expected when verifying.

Panics:

A panic will occur if:

Security:

• Salts should always be generated using a CSPRNG. secure_rand_bytes() can be used for this.
• The minimum recommended length for a salt is 16 bytes.
• The minimum recommended length for a hashed password is 16 bytes.
• The minimum recommended iteration count is 3.
• Password hashes should always be compared in constant-time.
• Please note that when verifying, a copy of the computed password hash is placed into dst_out. If the derived hash is considered sensitive and you want to provide defense in depth against an attacker reading your application’s private memory, then you as the user are responsible for zeroing out this buffer (see the zeroize crate).

The cost parameters were the recommended values at time of writing. Please be sure to also check OWASP for the latest recommended values.

Example:

use orion::{hazardous::kdf::argon2i, util};

let mut salt = [0u8; 16];
util::secure_rand_bytes(&mut salt)?;
let password = b"Secret password";
let mut dst_out = [0u8; 64];

argon2i::derive_key(password, &salt, 3, 1<<16, None, None, &mut dst_out)?;

let expected_dk = dst_out;

assert!(argon2i::verify(
    &expected_dk,
    password,
    &salt,
    3,
    1<<16,
    None,
    None,
    &mut dst_out
)
.is_ok());

Constants

ARGON2_VARIANT

The Argon2 variant (i).

ARGON2_VERSION

The Argon2 version (0x13).

Functions

derive_key

Argon2i password hashing function as described in the P-H-C specification.

verify

Verify Argon2i derived key in constant time.