Class Hkdf

Namespace

CryptoHives.Foundation.Security.Cryptography.Kdf

Assembly

CryptoHives.Foundation.Security.Cryptography.dll

Implements HKDF (HMAC-based Extract-and-Expand Key Derivation Function) as defined in RFC 5869.

public static class Hkdf

Inheritance

object

Hkdf

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Examples

// Derive a 32-byte key using HMAC-SHA-256
byte[] ikm = ...; // input keying material
byte[] salt = ...; // optional salt
byte[] info = ...; // context info

byte[] derivedKey = Hkdf.DeriveKey(
    key => new HmacSha256(key),
    ikm, outputLength: 32, salt, info);

Remarks

HKDF is a simple and efficient key derivation function based on HMAC. It consists of two stages: Extract concentrates the entropy of the input keying material into a pseudorandom key (PRK), and Expand derives one or more output keys from the PRK.

This implementation uses the CryptoHives IMac interface, making it pluggable with any HMAC variant (SHA-256, SHA-384, SHA-512, SHA3-256, etc.) and fully managed across all platforms.

For situations where the input keying material is already uniformly random, the Extract step can be skipped and the IKM used directly as the PRK in Expand. See RFC 5869 for guidance.

Methods

DeriveKey(HmacFactory, byte[], int, byte[]?, byte[]?)

Performs the combined HKDF Extract-then-Expand key derivation.

public static byte[] DeriveKey(HmacFactory hmacFactory, byte[] ikm, int outputLength, byte[]? salt = null, byte[]? info = null)

Parameters

hmacFactory HmacFactory

A factory that creates an HMAC instance keyed with the given key.

ikm byte[]

The input keying material.

outputLength int

The desired length of the output keying material.

salt byte[]

The optional salt value.

info byte[]

The optional context and application-specific information.

Returns

byte[]

The output keying material.

Exceptions

ArgumentNullException

hmacFactory or ikm is null.

ArgumentOutOfRangeException

outputLength is less than 1.

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

Performs the combined HKDF Extract-then-Expand key derivation.

public static void DeriveKey(HmacFactory hmacFactory, ReadOnlySpan<byte> ikm, Span<byte> output, ReadOnlySpan<byte> salt, ReadOnlySpan<byte> info)

Parameters

hmacFactory HmacFactory

A factory that creates an HMAC instance keyed with the given key.

ikm ReadOnlySpan<byte>

The input keying material.

output Span<byte>

The destination buffer to receive the output keying material.

salt ReadOnlySpan<byte>

The optional salt value. If empty, defaults to a zero-filled byte array.

info ReadOnlySpan<byte>

The optional context and application-specific information.

Exceptions

ArgumentNullException

hmacFactory is null.

ArgumentException

output is empty, or exceeds 255 × MacSize bytes.

Expand(HmacFactory, byte[], int, byte[]?)

Performs the HKDF-Expand function. See RFC 5869 §2.3.

public static byte[] Expand(HmacFactory hmacFactory, byte[] prk, int outputLength, byte[]? info = null)

Parameters

hmacFactory HmacFactory

A factory that creates an HMAC instance keyed with the given key.

prk byte[]

The pseudorandom key.

outputLength int

The desired length of the output keying material.

info byte[]

The optional context and application-specific information.

Returns

byte[]

The output keying material.

Exceptions

ArgumentNullException

hmacFactory or prk is null.

ArgumentOutOfRangeException

outputLength is less than 1.

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

Performs the HKDF-Expand function. See RFC 5869 §2.3.

public static void Expand(HmacFactory hmacFactory, ReadOnlySpan<byte> prk, Span<byte> output, ReadOnlySpan<byte> info)

Parameters

hmacFactory HmacFactory

A factory that creates an HMAC instance keyed with the given key.

prk ReadOnlySpan<byte>

The pseudorandom key (at least MacSize bytes, typically the output of Extract).

output Span<byte>

The destination buffer to receive the output keying material.

info ReadOnlySpan<byte>

The optional context and application-specific information.

Exceptions

ArgumentNullException

hmacFactory is null.

ArgumentException

output is empty, or exceeds 255 × MacSize bytes.

Extract(HmacFactory, byte[], byte[]?)

Performs the HKDF-Extract function. See RFC 5869 §2.2.

public static byte[] Extract(HmacFactory hmacFactory, byte[] ikm, byte[]? salt = null)

Parameters

hmacFactory HmacFactory

A factory that creates an HMAC instance keyed with the given key.

ikm byte[]

The input keying material.

salt byte[]

The optional salt value. If null, defaults to a zero-filled byte array.

Returns

byte[]

The pseudorandom key (PRK).

Exceptions

ArgumentNullException

hmacFactory or ikm is null.

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

Performs the HKDF-Extract function. See RFC 5869 §2.2.

public static int Extract(HmacFactory hmacFactory, ReadOnlySpan<byte> ikm, ReadOnlySpan<byte> salt, Span<byte> prk)

Parameters

hmacFactory HmacFactory

A factory that creates an HMAC instance keyed with the given key.

ikm ReadOnlySpan<byte>

The input keying material.

salt ReadOnlySpan<byte>

The optional salt value (a non-secret random value). If empty, defaults to a zero-filled byte array of length MacSize.

prk Span<byte>

The destination buffer to receive the pseudorandom key. Must be at least MacSize bytes.

Returns

int

The number of bytes written to prk.

Exceptions

ArgumentNullException

hmacFactory is null.

ArgumentException

prk is too small.