Module orion::hazardous::hkdf

HKDF-HMAC-SHA512 (HMAC-based Extract-and-Expand Key Derivation Function) as specified in the RFC 5869.

Parameters:

• salt: Optional salt value
• ikm: Input keying material
• info: Optional context and application specific information (can be a zero-length string)
• okm_out: Destination buffer for the derived key. The length of the derived key is implied by the length of okm_out

See RFC for more information.

Exceptions:

An exception will be thrown if:

• The length of okm_out is less than 1
• The length of okm_out is greater than 255 * hash_output_size_in_bytes

Security:

Salts should always be generated using a CSPRNG. The gen_rand_key function in util can be used for this. The recommended length for a salt is 16 bytes as a minimum. HKDF is not suitable for password storage. Even though a salt value is optional, it is strongly recommended to use one.

Example:

Generating derived key:

use orion::utilities::util;
use orion::hazardous::hkdf;

let mut salt = [0u8; 16];
util::gen_rand_key(&mut salt).unwrap();
let mut okm_out = [0u8; 32];

hkdf::derive_key(&salt, "IKM".as_bytes(), "Info".as_bytes(), &mut okm_out).unwrap();

Verifying derived key:

use orion::utilities::util;
use orion::hazardous::hkdf;

let mut salt = [0u8; 16];
util::gen_rand_key(&mut salt).unwrap();
let mut okm_out = [0u8; 32];

hkdf::derive_key(&salt, "IKM".as_bytes(), "Info".as_bytes(), &mut okm_out).unwrap();
let exp_okm = okm_out;
assert!(hkdf::verify(&exp_okm, &salt, "IKM".as_bytes(), "Info".as_bytes(), &mut okm_out).unwrap());

Functions

derive_key	Combine extract and expand to return a derived key.
expand	The HKDF expand step.
extract	The HKDF extract step.
verify	Verify a derived key in constant time.