Trait KDF 

pub trait KDF: Default {
    // Required methods
    fn derive_key(
        self,
        key: &impl KeyMaterial,
        additional_input: &[u8],
    ) -> Result<Box<dyn KeyMaterial>, KDFError>;
    fn derive_key_out(
        self,
        key: &impl KeyMaterial,
        additional_input: &[u8],
        output_key: &mut impl KeyMaterial,
    ) -> Result<usize, KDFError>;
    fn derive_key_from_multiple(
        self,
        keys: &[&impl KeyMaterial],
        additional_input: &[u8],
    ) -> Result<Box<dyn KeyMaterial>, KDFError>;
    fn derive_key_from_multiple_out(
        self,
        keys: &[&impl KeyMaterial],
        additional_input: &[u8],
        output_key: &mut impl KeyMaterial,
    ) -> Result<usize, KDFError>;
    fn max_security_strength(&self) -> SecurityStrength;
}

A Key Derivation Function (KDF) is a function that takes in one or more input key and some unstructured additional input, and uses them to produces a derived key.

Required Methods

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

Implementations of this function are capable of deriving an output key from an input key, assuming that they have been properly initialized.

Entropy Conversion rules

Implementations SHOULD act on a KeyMaterial of any KeyType and will generally return a KeyMaterial of the same type

ex.:

• KeyType::BytesLowEntropy -> KeyType::BytesLowEntropy)
• KeyType::BytesFullEntropy -> KeyType::BytesFullEntropy)
• KeyType::SymmetricCipherKey -> KeyType::SymmetricCipherKey)

If provided with an input key, even if it is KeyType::BytesFullEntropy, but that contains less key material than the internal block size of the KDF, then the KDF will not be considered properly seeded, and the output KeyMaterialInternal will be set to KeyType::BytesLowEntropy – for example, seeding SHA3-256 with a KeyMaterialInternal containing only 128 bits of key material.

An implement can, and in most cases SHOULD, return a HashError if provided with a KeyMaterialInternal of type KeyType::Zeroized.

Additional Input

The additional_input parameter is used in deriving the key, but is not credited with any entropy, and therefore does not affect the type of the output KeyMaterialInternal. This corresponds directly to FixedInfo as defined in NIST SP 800-56C. The additional_input parameter can be empty by passing in &[0u8; 0].

Output length: this function will create a KeyMaterial populated with the default output length of the underlying hash primitive.

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

Same as KDF::derive_key, but fills the provided output KeyMaterialInternal.

Output length: this function will behave differently depending on the underlying hash primitive; some, such as SHA2 or SHA3 will produce a fixed-length output, while others, such as SHAKE or HKDF, will fill the provided KeyMaterial to capacity and require you to truncate it afterwards using KeyMaterial::truncate.

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

Meant to be used for hybrid key establishment schemes or other spit-key scenarios where multiple keys need to be combined into a single key of the same length.

This function can also be used to mix a KeyMaterial of low entropy with one of full entropy to produce a new full entropy key. For the purposes of determining whether enough input key material was provided, the lengths of all full-entropy input keys are added together.

Implementations that are not safe to be used as a split-key PRF MAY still implement this function and return a result, but SHOULD set the entropy level of the returned key appropriately; for example a KDF that is only full-entropy when keyed in the first input SHOULD return a full entropy key only if the first input is full entropy.

Implementations can, and in most cases SHOULD, return a KeyMaterialInternal of the same type as the strongest key, and SHOULD throw a HashError if all input keys are zeroized. For example output a KeyType::BytesFullEntropy key whenever any one of the input keys is a KeyType::BytesFullEntropy key. As another example, combining a KeyType::BytesLowEntropy key with a KeyType::MACKey key should return a KeyType::MACKey.

Output length: this function will create a KeyMaterial populated with the default output length of the underlying hash primitive.

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

Same as KDF::derive_key, but fills the provided output KeyMaterialInternal.

Output length: this function will behave differently depending on the underlying hash primitive; some, such as SHA2 or SHA3 will produce a fixed-length output, while others, such as SHAKE or HKDF, will fill the provided KeyMaterial to capacity and require you to truncate it afterwards by using KeyMaterial::truncate.

fn max_security_strength(&self) -> SecurityStrength

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

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors