Crate pbkdf2 

RustCrypto: PBKDF2

Pure Rust implementation of the Password-Based Key Derivation Function v2 (PBKDF2) as specified in RFC 2898.

License

Licensed under either of:

• Apache License, Version 2.0
• MIT license

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Examples

PBKDF2 is defined in terms of a keyed pseudo-random function (PRF). The most commonly used PRF for this purpose is HMAC. In such cases you can use pbkdf2_hmac and pbkdf2_hmac_array functions. The former accepts a byte slice which gets filled with generated key, while the latter returns an array with generated key of requested length.

Note that it is not recommended to generate keys using PBKDF2 that exceed the output size of the PRF (equal to the hash size in the case of HMAC). If you need to generate a large amount of cryptographic material, consider using a separate key derivation function.

Low-level API

This API operates directly on byte slices:

// NOTE: example requires `getrandom` feature is enabled

use hex_literal::hex;
use pbkdf2::{pbkdf2_hmac, pbkdf2_hmac_array, sha2::Sha256};

let password = b"password";
let salt = b"salt";
// number of iterations
let n = 600_000;
// Expected value of generated key
let expected = hex!("669cfe52482116fda1aa2cbe409b2f56c8e45637");

let mut key1 = [0u8; 20];
pbkdf2_hmac::<Sha256>(password, salt, n, &mut key1);
assert_eq!(key1, expected);

let key2 = pbkdf2_hmac_array::<Sha256, 20>(password, salt, n);
assert_eq!(key2, expected);

If you want to use a different PRF, then you can use pbkdf2 and pbkdf2_array functions.

PHC string API

This crate can produce and verify password hash strings encoded in the Password Hashing Competition (PHC) string format using the [Pbkdf2] struct.

The following example demonstrates the high-level password hashing API:

// NOTE: example requires `getrandom` feature is enabled

use pbkdf2::{
    password_hash::{PasswordHasher, PasswordVerifier},
    phc::PasswordHash,
    Pbkdf2
};

let pbkdf2 = Pbkdf2::default(); // Uses `Algorithm::default()` and `Params::RECOMMENDED`
let password = b"hunter2"; // Bad password; don't actually use!

// Hash password to PHC string ($pbkdf2-sha256$...)
let pwhash: PasswordHash = pbkdf2.hash_password(password)?;
let pwhash_string = pwhash.to_string();

// Verify password against PHC string
let parsed_hash = PasswordHash::new(&pwhash_string)?;
pbkdf2.verify_password(password, &parsed_hash)?;

Re-exports

pub use hmac;

Functions

pbkdf2

Generic implementation of PBKDF2 algorithm which accepts an arbitrary keyed PRF.

pbkdf2_array

A variant of the pbkdf2 function which returns an array instead of filling an input slice.

pbkdf2_hmac

A variant of the pbkdf2 function which uses HMAC for PRF.

pbkdf2_hmac_array

A variant of the pbkdf2_hmac function which returns an array instead of filling an input slice.