Hkdf Class

Definition

Namespace

Bodu.Security.Cryptography

Assembly

Bodu.Security.Cryptography.dll

Package

Bodu.Security.Cryptography 1.2.0

Source

Hkdf.cs

Provides the HMAC-based Extract-and-Expand Key Derivation Function (HKDF) defined in RFC 5869, exposing the Extract, Expand, and combined DeriveKey stages over the SHA-1 and SHA-2 family of hash algorithms. This class cannot be instantiated.

public static class Hkdf

Inheritance

object

Hkdf

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

byte[] key = Hkdf.DeriveKey(
    HashAlgorithmName.SHA256,
    inputKeyingMaterial: sharedSecret,
    outputLength: 32,
    salt: salt,
    info: "app v1 traffic key"u8);

Remarks

HKDF turns input keying material that is merely high-entropy - such as a Diffie-Hellman shared secret - into one or more cryptographically strong, fixed-length keys. Extract(HashAlgorithmName, ReadOnlySpan<byte>, ReadOnlySpan<byte>) concentrates the entropy of the input into a pseudorandom key (PRK) of one hash length; Expand(HashAlgorithmName, ReadOnlySpan<byte>, int, ReadOnlySpan<byte>) stretches that PRK into output keying material of any requested length, optionally bound to an application-specific info context. DeriveKey(HashAlgorithmName, ReadOnlySpan<byte>, int, ReadOnlySpan<byte>, ReadOnlySpan<byte>) performs both stages in one call.

The surface mirrors the BCL's HKDF so the two are interchangeable. The supported hash algorithms are SHA1, SHA256, SHA384, and SHA512. Prefer the platform HKDF where it covers your need; this type exists to give the rest of the library a self-contained HKDF surface (for example, the HPKE labeled KDF).

Like the rest of the library, this implementation offers best-effort side-channel resistance and has not been independently audited.

Methods

DeriveKey(HashAlgorithmName, ReadOnlySpan<byte>, int, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Performs the RFC 5869 extract and expand stages in one call, deriving outputLength bytes of output keying material directly from inputKeyingMaterial.

public static byte[] DeriveKey(HashAlgorithmName hashAlgorithm, ReadOnlySpan<byte> inputKeyingMaterial, int outputLength, ReadOnlySpan<byte> salt = default, ReadOnlySpan<byte> info = default)

Parameters

hashAlgorithm HashAlgorithmName

The HMAC hash algorithm to use.

inputKeyingMaterial ReadOnlySpan<byte>

The input keying material to derive from.

outputLength int

The number of bytes to produce.

salt ReadOnlySpan<byte>

The optional non-secret salt. When empty, a string of hash-length zero bytes is used.

info ReadOnlySpan<byte>

The optional context and application-specific information.

Returns

byte[]

The output keying material, outputLength bytes long.

Exceptions

ArgumentException

hashAlgorithm is not a supported HKDF hash algorithm.

ArgumentOutOfRangeException

outputLength is not between 1 and 255 times the hash length.

DeriveKey(HashAlgorithmName, ReadOnlySpan<byte>, Span<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Performs the RFC 5869 extract and expand stages in one call, writing the output keying material into output.

public static void DeriveKey(HashAlgorithmName hashAlgorithm, ReadOnlySpan<byte> inputKeyingMaterial, Span<byte> output, ReadOnlySpan<byte> salt = default, ReadOnlySpan<byte> info = default)

Parameters

hashAlgorithm HashAlgorithmName

The HMAC hash algorithm to use.

inputKeyingMaterial ReadOnlySpan<byte>

The input keying material to derive from.

output Span<byte>

The span that receives the output keying material; its length determines how many bytes are produced.

salt ReadOnlySpan<byte>

The optional non-secret salt. When empty, a string of hash-length zero bytes is used.

info ReadOnlySpan<byte>

The optional context and application-specific information.

Exceptions

ArgumentException

hashAlgorithm is not a supported HKDF hash algorithm.

ArgumentOutOfRangeException

output is empty or longer than 255 times the hash length.

Expand(HashAlgorithmName, ReadOnlySpan<byte>, int, ReadOnlySpan<byte>)

Performs the RFC 5869 expand stage, stretching pseudoRandomKey into outputLength bytes of output keying material.

public static byte[] Expand(HashAlgorithmName hashAlgorithm, ReadOnlySpan<byte> pseudoRandomKey, int outputLength, ReadOnlySpan<byte> info = default)

Parameters

hashAlgorithm HashAlgorithmName

The HMAC hash algorithm to use.

pseudoRandomKey ReadOnlySpan<byte>

The pseudorandom key produced by Extract(HashAlgorithmName, ReadOnlySpan<byte>, ReadOnlySpan<byte>).

outputLength int

The number of bytes to produce.

info ReadOnlySpan<byte>

The optional context and application-specific information.

Returns

byte[]

The output keying material, outputLength bytes long.

Exceptions

ArgumentException

hashAlgorithm is not a supported HKDF hash algorithm, or pseudoRandomKey is shorter than one hash length.

ArgumentOutOfRangeException

outputLength is not between 1 and 255 times the hash length.

Expand(HashAlgorithmName, ReadOnlySpan<byte>, Span<byte>, ReadOnlySpan<byte>)

Performs the RFC 5869 expand stage, writing the output keying material into output.

public static void Expand(HashAlgorithmName hashAlgorithm, ReadOnlySpan<byte> pseudoRandomKey, Span<byte> output, ReadOnlySpan<byte> info = default)

Parameters

hashAlgorithm HashAlgorithmName

The HMAC hash algorithm to use.

pseudoRandomKey ReadOnlySpan<byte>

The pseudorandom key produced by Extract(HashAlgorithmName, ReadOnlySpan<byte>, ReadOnlySpan<byte>).

output Span<byte>

The span that receives the output keying material; its length determines how many bytes are produced.

info ReadOnlySpan<byte>

The optional context and application-specific information.

Exceptions

ArgumentException

hashAlgorithm is not a supported HKDF hash algorithm, or pseudoRandomKey is shorter than one hash length.

ArgumentOutOfRangeException

output is empty or longer than 255 times the hash length.

Extract(HashAlgorithmName, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Performs the RFC 5869 extract stage, condensing inputKeyingMaterial into a pseudorandom key of one hash length.

public static byte[] Extract(HashAlgorithmName hashAlgorithm, ReadOnlySpan<byte> inputKeyingMaterial, ReadOnlySpan<byte> salt = default)

Parameters

hashAlgorithm HashAlgorithmName

The HMAC hash algorithm to use.

inputKeyingMaterial ReadOnlySpan<byte>

The input keying material to extract entropy from.

salt ReadOnlySpan<byte>

The optional non-secret salt. When empty, a string of hash-length zero bytes is used.

Returns

byte[]

The pseudorandom key (PRK), one hash length long.

Exceptions

ArgumentException

hashAlgorithm is not a supported HKDF hash algorithm.

Extract(HashAlgorithmName, ReadOnlySpan<byte>, ReadOnlySpan<byte>, Span<byte>)

Performs the RFC 5869 extract stage, writing the pseudorandom key into destination.

public static int Extract(HashAlgorithmName hashAlgorithm, ReadOnlySpan<byte> inputKeyingMaterial, ReadOnlySpan<byte> salt, Span<byte> destination)

Parameters

hashAlgorithm HashAlgorithmName

The HMAC hash algorithm to use.

inputKeyingMaterial ReadOnlySpan<byte>

The input keying material to extract entropy from.

salt ReadOnlySpan<byte>

The optional non-secret salt. When empty, a string of hash-length zero bytes is used.

destination Span<byte>

The span that receives the pseudorandom key; must be exactly one hash length long.

Returns

int

The number of bytes written to destination, equal to the hash length.

Exceptions

ArgumentException

hashAlgorithm is not a supported HKDF hash algorithm, or destination is not exactly one hash length long.

Applies to

Product	Versions
.NET	8, 10