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;hmac

pub use password_hash;mcf or phc

pub use sha2;sha2

Modules

mcfmcf

Implementation of the password-hash traits for Modular Crypt Format (MCF) password hash strings which begin with $pbkdf$, $pbkdf-sha256$, or $pbkdf-sha512:

phcphc

Implementation of the password-hash crate API.

Structs

Paramssha2

PBKDF2 params

Pbkdf2sha2

PBKDF2 type for use with the PasswordHasher and PasswordVerifier traits, which implements support for password hash strings.

Enums

Algorithmsha2

PBKDF2 variants.

Traits

PasswordHashermcf or phc

High-level trait for password hashing functions.

PasswordVerifiermcf or phc

Trait for password verification.

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_hmachmac

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

pbkdf2_hmac_arrayhmac

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

pbkdf2_hmac_with_paramssha2

API for using pbkdf2_hmac which supports the Algorithm and Params types and with it runtime selection of which algorithm to use.