Class CryptoHkdf

Namespace

LibSodium

Assembly

LibSodium.Net.dll

Provides HKDF key derivation (RFC 5869) using SHA-256 or SHA-512.

public static class CryptoHkdf

Inheritance

object

CryptoHkdf

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Fields

MinOkmLen

Minimum length of output key material (OKM) in bytes (4).

public const int MinOkmLen = 4

Field Value

int

Sha256MaxOkmLen

Maximum length of output key material (OKM) for SHA256 in bytes (8160 = 32 * 255).

public const int Sha256MaxOkmLen = 8160

Field Value

int

Sha256PrkLen

Length of the pseudorandom key (PRK) for SHA256 in bytes (32).

public const int Sha256PrkLen = 32

Field Value

int

Sha512MaxOkmLen

Maximum length of output key material (OKM) for SHA512 in bytes (8160 = 64 * 255).

public const int Sha512MaxOkmLen = 16320

Field Value

int

Sha512PrkLen

Length of the pseudorandom key (PRK) for SHA256 in bytes (32).

public const int Sha512PrkLen = 64

Field Value

int

Methods

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

Derives key material from input key material in one step using HKDF (RFC 5869).

public static void DeriveKey(HashAlgorithmName hashAlgorithmName, SecureMemory<byte> ikm, SecureMemory<byte> okm, ReadOnlySpan<byte> salt, ReadOnlySpan<byte> info)

Parameters

hashAlgorithmName HashAlgorithmName

Hash algorithm to use (SHA-256 or SHA-512).

ikm SecureMemory<byte>

Input keying material.

okm SecureMemory<byte>

Output buffer to receive the derived keying material (16–64 bytes).

salt ReadOnlySpan<byte>

Optional salt value (can be empty).

info ReadOnlySpan<byte>

Optional context and application-specific information.

Exceptions

ArgumentException

Thrown if okm or internal buffers have invalid lengths.

NotSupportedException

Thrown if the hash algorithm is unsupported.

LibSodiumException

Thrown if the underlying native call fails.

DeriveKey(HashAlgorithmName, Stream, SecureMemory<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Derives key material from input key material in one step using HKDF (RFC 5869) from a stream.

public static void DeriveKey(HashAlgorithmName hashAlgorithmName, Stream ikm, SecureMemory<byte> okm, ReadOnlySpan<byte> salt, ReadOnlySpan<byte> info)

Parameters

hashAlgorithmName HashAlgorithmName

Hash algorithm to use (SHA-256 or SHA-512).

ikm Stream

Stream of input keying material.

okm SecureMemory<byte>

Buffer to receive the output keying material.

salt ReadOnlySpan<byte>

Optional salt value.

info ReadOnlySpan<byte>

Optional application-specific information.

Exceptions

NotSupportedException

Thrown if the hash algorithm is unsupported.

LibSodiumException

Thrown if the underlying native call fails.

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

Derives key material from input key material in one step using HKDF (RFC 5869) from a stream.

public static void DeriveKey(HashAlgorithmName hashAlgorithmName, Stream ikm, Span<byte> okm, ReadOnlySpan<byte> salt, ReadOnlySpan<byte> info)

Parameters

hashAlgorithmName HashAlgorithmName

Hash algorithm to use (SHA-256 or SHA-512).

ikm Stream

Stream of input keying material.

okm Span<byte>

Buffer to receive the output keying material.

salt ReadOnlySpan<byte>

Optional salt value.

info ReadOnlySpan<byte>

Optional application-specific information.

Exceptions

NotSupportedException

Thrown if the hash algorithm is unsupported.

LibSodiumException

Thrown if the underlying native call fails.

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

Derives key material from input key material in one step using HKDF (RFC 5869).

public static void DeriveKey(HashAlgorithmName hashAlgorithmName, ReadOnlySpan<byte> ikm, Span<byte> okm, ReadOnlySpan<byte> salt, ReadOnlySpan<byte> info)

Parameters

hashAlgorithmName HashAlgorithmName

Hash algorithm to use (SHA-256 or SHA-512).

ikm ReadOnlySpan<byte>

Input keying material.

okm Span<byte>

Output buffer to receive the derived keying material (16–64 bytes).

salt ReadOnlySpan<byte>

Optional salt value (can be empty).

info ReadOnlySpan<byte>

Optional context and application-specific information.

Exceptions

ArgumentException

Thrown if okm or internal buffers have invalid lengths.

NotSupportedException

Thrown if the hash algorithm is unsupported.

LibSodiumException

Thrown if the underlying native call fails.

DeriveKeyAsync(HashAlgorithmName, Stream, SecureMemory<byte>, ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, CancellationToken)

Asynchronously derives key material from input key material in one step using HKDF (RFC 5869) from a stream.

public static Task DeriveKeyAsync(HashAlgorithmName hashAlgorithmName, Stream ikm, SecureMemory<byte> okm, ReadOnlyMemory<byte> salt, ReadOnlyMemory<byte> info, CancellationToken cancellationToken = default)

Parameters

hashAlgorithmName HashAlgorithmName

Hash algorithm to use (SHA-256 or SHA-512).

ikm Stream

Stream of input keying material.

okm SecureMemory<byte>

Buffer to receive the output keying material.

salt ReadOnlyMemory<byte>

Optional salt value.

info ReadOnlyMemory<byte>

Optional application-specific information.

cancellationToken CancellationToken

Cancellation token.

Returns

Task

Exceptions

NotSupportedException

Thrown if the hash algorithm is unsupported.

LibSodiumException

Thrown if the underlying native call fails.

DeriveKeyAsync(HashAlgorithmName, Stream, Memory<byte>, ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, CancellationToken)

Asynchronously derives key material from input key material in one step using HKDF (RFC 5869) from a stream.

public static Task DeriveKeyAsync(HashAlgorithmName hashAlgorithmName, Stream ikm, Memory<byte> okm, ReadOnlyMemory<byte> salt, ReadOnlyMemory<byte> info, CancellationToken cancellationToken = default)

Parameters

hashAlgorithmName HashAlgorithmName

Hash algorithm to use (SHA-256 or SHA-512).

ikm Stream

Stream of input keying material.

okm Memory<byte>

Buffer to receive the output keying material.

salt ReadOnlyMemory<byte>

Optional salt value.

info ReadOnlyMemory<byte>

Optional application-specific information.

cancellationToken CancellationToken

Cancellation token.

Returns

Task

Exceptions

NotSupportedException

Thrown if the hash algorithm is unsupported.

LibSodiumException

Thrown if the underlying native call fails.

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

Performs the expand step of HKDF (RFC 5869), using the specified hash algorithm.

public static void Expand(HashAlgorithmName hashAlgorithmName, SecureMemory<byte> prk, SecureMemory<byte> okm, ReadOnlySpan<byte> info)

Parameters

hashAlgorithmName HashAlgorithmName

Hash algorithm to use (SHA-256 or SHA-512).

prk SecureMemory<byte>

Pseudorandom key obtained from the extract step (32 or 64 bytes).

okm SecureMemory<byte>

Output buffer to receive the derived keying material (4–8160 or 16320 bytes).

info ReadOnlySpan<byte>

Optional context and application-specific information.

Exceptions

ArgumentOutOfRangeException

Thrown if okm is not in valid range.

ArgumentException

Thrown if prk is not valid size for the selected hash.

NotSupportedException

Thrown if the hash algorithm is unsupported.

LibSodiumException

Thrown if the underlying native call fails.

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

Performs the expand step of HKDF (RFC 5869), using the specified hash algorithm.

public static void Expand(HashAlgorithmName hashAlgorithmName, ReadOnlySpan<byte> prk, Span<byte> okm, ReadOnlySpan<byte> info)

Parameters

hashAlgorithmName HashAlgorithmName

Hash algorithm to use (SHA-256 or SHA-512).

prk ReadOnlySpan<byte>

Pseudorandom key obtained from the extract step (32 or 64 bytes).

okm Span<byte>

Output buffer to receive the derived keying material (4–8160 or 16320 bytes).

info ReadOnlySpan<byte>

Optional context and application-specific information.

Exceptions

ArgumentOutOfRangeException

Thrown if okm is not in valid range.

ArgumentException

Thrown if prk is not valid size for the selected hash.

NotSupportedException

Thrown if the hash algorithm is unsupported.

LibSodiumException

Thrown if the underlying native call fails.

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

Performs the extract step of HKDF (RFC 5869), using the specified hash algorithm.

public static void Extract(HashAlgorithmName hashAlgorithmName, SecureMemory<byte> ikm, ReadOnlySpan<byte> salt, SecureMemory<byte> prk)

Parameters

hashAlgorithmName HashAlgorithmName

Hash algorithm to use (SHA-256 or SHA-512).

ikm SecureMemory<byte>

Input keying material.

salt ReadOnlySpan<byte>

Optional salt value (can be empty).

prk SecureMemory<byte>

Buffer to receive the pseudorandom key (32 bytes for SHA256 and 64 bytes for SHA512).

Exceptions

ArgumentException

Thrown if prk is not exactly the required size.

NotSupportedException

Thrown if the hash algorithm is unsupported.

LibSodiumException

Thrown if the underlying native call fails.

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

Performs the extract step of HKDF (RFC 5869) using a stream as input keying material.

public static void Extract(HashAlgorithmName hashAlgorithmName, Stream ikm, ReadOnlySpan<byte> salt, SecureMemory<byte> prk)

Parameters

hashAlgorithmName HashAlgorithmName

Hash algorithm to use (SHA-256 or SHA-512).

ikm Stream

Stream of input keying material (IKM).

salt ReadOnlySpan<byte>

Optional salt value (can be empty).

prk SecureMemory<byte>

Buffer to receive the pseudorandom key (32 bytes for SHA256 and 64 bytes for SHA512).

Exceptions

ArgumentNullException

Thrown if ikm is null.

ArgumentException

Thrown if prk length is incorrect.

NotSupportedException

Thrown if the hash algorithm is unsupported.

LibSodiumException

Thrown if the underlying native call fails.

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

Performs the extract step of HKDF (RFC 5869) using a stream as input keying material.

public static void Extract(HashAlgorithmName hashAlgorithmName, Stream ikm, ReadOnlySpan<byte> salt, Span<byte> prk)

Parameters

hashAlgorithmName HashAlgorithmName

Hash algorithm to use (SHA-256 or SHA-512).

ikm Stream

Stream of input keying material (IKM).

salt ReadOnlySpan<byte>

Optional salt value (can be empty).

prk Span<byte>

Buffer to receive the pseudorandom key (32 bytes for SHA256 and 64 bytes for SHA512).

Exceptions

ArgumentNullException

Thrown if ikm is null.

ArgumentException

Thrown if prk length is incorrect.

NotSupportedException

Thrown if the hash algorithm is unsupported.

LibSodiumException

Thrown if the underlying native call fails.

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

Performs the extract step of HKDF (RFC 5869), using the specified hash algorithm.

public static void Extract(HashAlgorithmName hashAlgorithmName, ReadOnlySpan<byte> ikm, ReadOnlySpan<byte> salt, Span<byte> prk)

Parameters

hashAlgorithmName HashAlgorithmName

Hash algorithm to use (SHA-256 or SHA-512).

ikm ReadOnlySpan<byte>

Input keying material.

salt ReadOnlySpan<byte>

Optional salt value (can be empty).

prk Span<byte>

Buffer to receive the pseudorandom key (32 bytes for SHA256 and 64 bytes for SHA512).

Exceptions

ArgumentException

Thrown if prk is not exactly the required size.

NotSupportedException

Thrown if the hash algorithm is unsupported.

LibSodiumException

Thrown if the underlying native call fails.

ExtractAsync(HashAlgorithmName, Stream, ReadOnlyMemory<byte>, SecureMemory<byte>, CancellationToken)

Asynchronously performs the extract step of HKDF (RFC 5869) using a stream as input keying material.

public static Task ExtractAsync(HashAlgorithmName hashAlgorithmName, Stream ikm, ReadOnlyMemory<byte> salt, SecureMemory<byte> prk, CancellationToken cancellationToken = default)

Parameters

hashAlgorithmName HashAlgorithmName

Hash algorithm to use (SHA-256 or SHA-512).

ikm Stream

Stream of input keying material (IKM).

salt ReadOnlyMemory<byte>

Optional salt value (can be empty).

prk SecureMemory<byte>

Buffer to receive the pseudorandom key (32 bytes for SHA256 and 64 bytes for SHA512).

cancellationToken CancellationToken

Cancellation token.

Returns

Task

Exceptions

ArgumentNullException

Thrown if ikm is null.

ArgumentException

Thrown if prk length is incorrect.

NotSupportedException

Thrown if the hash algorithm is unsupported.

LibSodiumException

Thrown if the underlying native call fails.

ExtractAsync(HashAlgorithmName, Stream, ReadOnlyMemory<byte>, Memory<byte>, CancellationToken)

Asynchronously performs the extract step of HKDF (RFC 5869) using a stream as input keying material.

public static Task ExtractAsync(HashAlgorithmName hashAlgorithmName, Stream ikm, ReadOnlyMemory<byte> salt, Memory<byte> prk, CancellationToken cancellationToken = default)

Parameters

hashAlgorithmName HashAlgorithmName

Hash algorithm to use (SHA-256 or SHA-512).

ikm Stream

Stream of input keying material (IKM).

salt ReadOnlyMemory<byte>

Optional salt value (can be empty).

prk Memory<byte>

Buffer to receive the pseudorandom key (32 bytes for SHA256 and 64 bytes for SHA512).

cancellationToken CancellationToken

Cancellation token.

Returns

Task

Exceptions

ArgumentNullException

Thrown if ikm is null.

ArgumentException

Thrown if prk length is incorrect.

NotSupportedException

Thrown if the hash algorithm is unsupported.

LibSodiumException

Thrown if the underlying native call fails.