HKDF

RFC 5869 - HMAC-based Extract-and-Expand Key Derivation Function

siotls.crypto.hkdf.hkdf_expand(digestmod, pseudorandom_key, info, okm_length)

Take a strong key and expand it to the desired length. It is possible to supply additional info (e.g. a label) to expand a same input key into multiple ones (one per different info).

Parameters:

  • digestmod (siotls.crypto.HashFunction) – The hash function for the underlying HMAC.

  • pseudorandom_key (bytes) – A strong key, usually coming from hkdf_extract().

  • info (bytes) – Additional info that need to be nor random, nor secret nor unique. It can very well be a human readable label. Used to expand a same input key into multiple different ones.

  • okm_length (int) – The length (in bytes) of the output key.

Returns:

Another strong key, of okm_length bytes.

Return type:

bytes

siotls.crypto.hkdf.hkdf_expand_label(digestmod, secret, label, context, length)

Expand multiple TLS secrets from a same strong pseudo random key.

This function is the TLS take on hkdf_expand() and is defined at RFC 8446 Section 7.1.

Parameters:

  • digestmod (siotls.crypto.HashFunction) – The hash function for the underlying HMAC.

  • secret (bytes) – A strong secret, from wich other strong keys will be expanded.

  • label (bytes) – Free text, usually human readable, used to name the output key. Used together with context as salt.

  • context (bytes) – Some additional bytes to use as salt. Usually the current TLS transcript digest.

  • length (int) – The length of the output.

Returns:

Another strong key, of length bytes.

Return type:

bytes

siotls.crypto.hkdf.hkdf_extract(digestmod, salt, input_keying_material)

Take a random key that is not necessarly distributed uniformly and turn it in a short but cryptographically strong key.

Parameters:

  • digestmod (siotls.crypto.HashFunction) – The hash function for the underlying HMAC.

  • salt (bytes | None) – Some bytes that need to be nor secret, nor unique. Used to strengthen the output key.

  • input_keying_material (bytes) – The weak input key such as a secret shared via a key exchange algorithm (diffie-hellman) or a random value coming from a TRNG (getrandom(2)).

Returns:

A strong pseudo random key, of digestmod().digest_size bytes.

Return type:

bytes