Struct HKDF 

pub struct HKDF<H: Hash + HashAlgParams + Default> { /* private fields */ }

Implementations

impl<H: Hash + HashAlgParams + Default> HKDF<H>

pub fn new() -> Self

pub fn get_entropy(&self) -> usize

Returns the amount of entropy currently credited from the keys inputted so far.

pub fn is_fully_seeded(&self) -> bool

Has the entropy input so far met the threshold for this object to be considered fully seeded?

pub fn extract( salt: &impl KeyMaterial, ikm: &impl KeyMaterial, ) -> Result<impl KeyMaterial, MACError>

HKDF-Extract(salt, IKM) -> PRK Options: Hash a hash function; HashLen denotes the length of the hash function output in octets

Inputs: salt optional salt value (a non-secret random value); if not provided, it is set to a string of HashLen zeros. IKM input keying material

Output: PRK a pseudorandom key (of HashLen octets)

The KeyMaterial input parameters can be of any KeyType; but the type of the output will be set accordingly. The output KeyMaterial will be of fixed size, with a capacity large enough to cover any underlying hash function, but the actual key length will be appropriate to the underlying hash function.

Salt is optional, which is indicated by providing an uninitialized KeyMaterial object of length zero, the capacity is irrelevant, so KeyMateriol256::new() or KeyMaterial_internal::<0>::new() would both count as an absent salt.

pub fn extract_out( salt: &impl KeyMaterial, ikm: &impl KeyMaterial, prk: &mut impl KeyMaterial, ) -> Result<usize, MACError>

Same as HKDF::extract, but writes the output to a provided KeyMaterial buffer.

pub fn expand_out( prk: &impl KeyMaterial, info: &[u8], L: usize, okm: &mut impl KeyMaterial, ) -> Result<usize, KDFError>

The definition of HKDF-Expand from RFC5869 is as follows: HKDF-Expand(PRK, info, L) -> OKM Options: Hash a hash function; HashLen denotes the length of the hash function output in octets Inputs: PRK a pseudorandom key of at least HashLen octets (usually, the output from the extract step) info optional context and application specific information (can be a zero-length string) L length of output keying material in octets (<= 255*HashLen)

Output: OKM output keying material (of L octets)

Due to the details of the KeyMaterial object needing to compile to a known size, there is (currently) no way (within a no_std context) to dynamically allocate a KeyMaterial object according to the given ‘L’, therefore this function is provided only as expand_out(), filling the provided KeyMaterial object, and no analogous expand() is provided.

The KeyMaterial input parameters can be of any KeyType; but the type of the output will be set accordingly.

L is the output length. This will throw a MACError::InvalidLength if the provided KeyMaterial is too small to hold the requested output.

Returns the number of bytes written.

pub fn extract_and_expand_out( salt: &impl KeyMaterial, ikm: &impl KeyMaterial, info: &[u8], L: usize, okm: &mut impl KeyMaterial, ) -> Result<usize, KDFError>

Salt is optional, which is indicated by providing an uninitialized KeyMaterial object of length zero, the capacity is irrelevant, so KeyMateriol256::new() or KeyMaterial_internal::<0>::new() would both count as an absent salt.

pub fn do_extract_init( &mut self, salt: &impl KeyMaterial, ) -> Result<usize, MACError>

This, together with HKDF::do_extract_update_key, HKDF::do_extract_update_bytes and HKDF::do_extract_final provide a streaming interface for very long values of ikm. In this mode, the entropy of ikm is untracked, and so only the entropy ef salt is taken into account when computing the entropy of the output prk. The KeyMaterial input parameters can be of any KeyType; but the type of the output will be set accordingly. The output KeyMaterial will be of fixed size, with a capacity large enough to cover any underlying hash function, but the actual key length will be appropriate to the underlying hash function.

Salt is optional, which is indicated by providing an uninitialized KeyMaterial object of length zero, the capacity is irrelevant, so KeyMateriol256::new() or KeyMaterial_internal::<0>::new() would both count as an absent salt.

Returns the number of bits of entropy credited to this input key material.

pub fn do_extract_update_key( &mut self, ikm: &impl KeyMaterial, ) -> Result<usize, MACError>

An update function that allows adding an IKM as a KeyMaterial. Credits the entropy contained in the IKM. This function may be called zero or more times in a workflow. In particular, this function may be called multiple times to add more than one IKM.

Returns the number of bits of entropy credited to this input key material.

pub fn do_extract_update_bytes( &mut self, ikm_chunk: &[u8], ) -> Result<usize, MACError>

An update function that allows streaming of the IKM as bytes. Note that since this interface takes the IKM as raw bytes, it cannot track its entropy and therefore any IKM material provided through this interface will not count towards the entropy of the output key.

State machine: this function must be called after HKDF::do_extract_init, followed by zero or more calls of HKDF::do_extract_update_key, and before HKDF::do_extract_final.

Returns the number of bits of entropy credited to this input key material, which is always 0 for this function.

pub fn do_extract_final(self) -> Result<impl KeyMaterial, MACError>

pub fn do_extract_final_out( self, okm: &mut impl KeyMaterial, ) -> Result<usize, MACError>

Trait Implementations

impl<H: Hash + HashAlgParams + Default> Default for HKDF<H>

fn default() -> Self

Returns the “default value” for a type.

impl<H: Hash + HashAlgParams + Default> KDF for HKDF<H>

As per NIST SP 800-56Cr2 section 5.1, HKDF extract_and_expand can be used as a KDF. Additionally, section 4.1 says that when using HMAC as a KDF, the salt may be set to a string of HashLen zeros. All key material and additional_input is mapped to HKDF’s ikm input. While this is not the only mode in which HKDF can be used as a KDF, this is considered the default mode that is exposed through KDF::derive_key and KDF::derive_key_out. More advanced control of the inputs to HKDF can be achieved by using KDF::derive_key_from_multiple and KDF::derive_key_from_multiple_out, or by using the HKDF impl directly.

Entropy tracking: this implementation will map entropy from the input keys to the output key.

fn derive_key( self, key: &impl KeyMaterial, additional_input: &[u8], ) -> Result<Box<dyn KeyMaterial>, KDFError>

This invokes HKDF::extract_and_expand_out with a zero salt and using the provided key as ikm. This provides a fixed-length output, which may be truncated as needed.

fn derive_key_out( self, key: &impl KeyMaterial, additional_input: &[u8], output_key: &mut impl KeyMaterial, ) -> Result<usize, KDFError>

This invokes HKDF::extract_and_expand_out with a zero salt and using the provided key as ikm. This fills the provided KeyMaterial object in place of exposing a Length parameter.

fn derive_key_from_multiple( self, keys: &[&impl KeyMaterial], additional_input: &[u8], ) -> Result<Box<dyn KeyMaterial>, KDFError>

As with KDF::derive_key and KDF::derive_key_out, This invokes HKDF in the extract_and_expand mode and maps the provided keys in the following way:

• The first (0’th) key is used as the salt for HKDF.extract.
• The remaining keys are concatenated to form HKDF’s ikm parameter.
• Entropy of all provided keys are tracked to determine the output key’s entropy.

Therefore, derive_key_from_multiple(&[KeyMaterial0::new(), &key], &info) is equivalent to derive_key(&key, &info).

This provides a fixed-length output, which may be truncated as needed.

fn derive_key_from_multiple_out( self, keys: &[&impl KeyMaterial], additional_input: &[u8], output_key: &mut impl KeyMaterial, ) -> Result<usize, KDFError>

This behaves the same as KDF::derive_key_from_multiple, except that it fills the provided KeyMaterial object in place of exposing a Length parameter.

fn max_security_strength(&self) -> SecurityStrength

Returns the maximum security strength that this KDF is capable of supporting, based on the underlying primitives.