Crate hkdf 

RustCrypto: HKDF

Pure Rust implementation of the HMAC-based Extract-and-Expand Key Derivation Function (HKDF) generic over hash function.

Usage

The most common way to use HKDF is as follows: you provide the Initial Key Material (IKM) and an optional salt, then you expand it (perhaps multiple times) into some Output Key Material (OKM) bound to an “info” context string.

use sha2::Sha256;
use hkdf::Hkdf;
use hex_literal::hex;

let ikm = hex!("0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b");
let salt = hex!("000102030405060708090a0b0c");
let info = hex!("f0f1f2f3f4f5f6f7f8f9");

let hk = Hkdf::<Sha256>::new(Some(&salt[..]), &ikm);
let mut okm = [0u8; 42];
hk.expand(&info, &mut okm)
    .expect("42 is a valid length for Sha256 to output");

let expected = hex!("
    3cb25f25faacd57a90434f64d0362f2a
    2d2d0a90cf1a5a4c5db02d56ecc4c5bf
    34007208d5b887185865
");
assert_eq!(okm, expected);

Normally the PRK (Pseudo-Random Key) remains hidden within the HKDF object, but if you need to access it, use Hkdf::extract instead of Hkdf::new.

use sha2::Sha256;
use hkdf::Hkdf;
use hex_literal::hex;

let ikm = hex!("0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b");
let salt = hex!("000102030405060708090a0b0c");

let (prk, hk) = Hkdf::<Sha256>::extract(Some(&salt[..]), &ikm);
let expected = hex!("
    077709362c2e32df0ddc3f0dc47bba63
    90b6c73bb50f9c3122ec844ad7c2b3e5
");
assert_eq!(prk[..], expected[..]);

If you already have a strong key to work from (uniformly-distributed and long enough), you can save a tiny amount of time by skipping the extract step. In this case, you pass a Pseudo-Random Key (PRK) into the Hkdf::from_prk constructor, then use the resulting Hkdf object as usual.

use sha2::Sha256;
use hkdf::Hkdf;
use hex_literal::hex;

let salt = hex!("000102030405060708090a0b0c");
let info = hex!("f0f1f2f3f4f5f6f7f8f9");
 
let prk = hex!("
    077709362c2e32df0ddc3f0dc47bba63
    90b6c73bb50f9c3122ec844ad7c2b3e5
");

let hk = Hkdf::<Sha256>::from_prk(&prk).expect("PRK should be large enough");
let mut okm = [0u8; 42];
hk.expand(&info, &mut okm)
    .expect("42 is a valid length for Sha256 to output");

let expected = hex!("
    3cb25f25faacd57a90434f64d0362f2a
    2d2d0a90cf1a5a4c5db02d56ecc4c5bf
    34007208d5b887185865
");
assert_eq!(okm, expected);

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.

Re-exports

pub use hmac;

pub use kdf;kdf

Structs

GenericHkdf

Structure representing the HKDF, capable of HKDF-Expand and HKDF-Extract operations. Recommendations for the correct usage of the parameters can be found in the crate root.

GenericHkdfExtract

Structure representing the streaming context of an HKDF-Extract operation.

InvalidLength

Structure for InvalidLength, used for output error handling.

InvalidPrkLength

Error that is returned when supplied pseudorandom key (PRK) is not long enough.

Traits

HmacImpl

Trait representing a HMAC implementation.

Kdfkdf

Key Derivation Function.

Type Aliases

Hkdf

GenericHkdf variant which uses Hmac for the underlying HMAC implementation.

HkdfExtract

GenericHkdfExtract variant which uses Hmac for the underlying HMAC implementation.

SimpleHkdf

GenericHkdf variant which uses SimpleHmac for the underlying HMAC implementation.

SimpleHkdfExtract

GenericHkdfExtract variant which uses SimpleHmac for the underlying HMAC implementation.