Module pbkdf2
Available on crate feature
dep_orion only.Expand description
PBKDF2(Password-Based Key Derivation Function 2) as specified in the RFC 8018.
§Parameters:
password: Password.salt: Salt value.iterations: Iteration count.dst_out: Destination buffer for the derived key. The length of the derived key is implied by the length ofdst_out.expected: The expected derived key.
§Errors:
An error will be returned if:
- The length of
dst_outis less than 1. - The specified iteration count is less than 1.
- The hashed password does not match the expected when verifying.
§Panics:
A panic will occur if:
- The length of
dst_outis greater than (2^32 - 1) * SHA(256/384/512)_OUTSIZE.
§Security:
- Use
Password::generate()to randomly generate a password of the same length as the underlying SHA2 hash functions blocksize. - Salts should always be generated using a CSPRNG.
secure_rand_bytes()can be used for this. - The recommended length for a salt is 64 bytes.
- The iteration count should be set as high as feasible. Please check OWASP for the recommended minimum amount (600000 at the time of writing).
- 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 thezeroizecrate).
§Example:
use orion::{hazardous::kdf::pbkdf2, util};
let mut salt = [0u8; 64];
util::secure_rand_bytes(&mut salt)?;
let password = pbkdf2::sha512::Password::from_slice("Secret password".as_bytes())?;
let mut dst_out = [0u8; 64];
pbkdf2::sha512::derive_key(&password, &salt, 10000, &mut dst_out)?;
let expected_dk = dst_out;
assert!(pbkdf2::sha512::verify(&expected_dk, &password, &salt, 10000, &mut dst_out).is_ok());