Class CryptoKeyDerivation

Namespace

LibSodium

Assembly

LibSodium.Net.dll

Provides deterministic key derivation using libsodium's crypto_kdf_* API, based on the BLAKE2b hash function.

public static class CryptoKeyDerivation

Inheritance

object

CryptoKeyDerivation

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Fields

ContextLen

Length of the context in bytes (8).

public const int ContextLen = 8

Field Value

int

MasterKeyLen

Length of the master key in bytes (32).

public const int MasterKeyLen = 32

Field Value

int

MaxSubkeyLen

Maximum length of a derived subkey (64).

public const int MaxSubkeyLen = 64

Field Value

int

MinSubkeyLen

Minimum length of a derived subkey (16).

public const int MinSubkeyLen = 16

Field Value

int

Methods

DeriveSubkey(SecureMemory<byte>, SecureMemory<byte>, ulong, ReadOnlySpan<byte>)

Deterministically derives a subkey from a master key, context, and subkey ID. Uses the BLAKE2b hash function internally.

public static void DeriveSubkey(SecureMemory<byte> masterKey, SecureMemory<byte> subkey, ulong subkeyId, ReadOnlySpan<byte> context)

Parameters

masterKey SecureMemory<byte>

The master key (32 bytes).

subkey SecureMemory<byte>

The buffer where the derived subkey will be written. Its length must be between 16 and 64 bytes.

subkeyId ulong

The identifier for the subkey (application-defined).

context ReadOnlySpan<byte>

8-byte context describing the usage.

Exceptions

ArgumentException

Thrown when subkey is out of bounds, context is not 8 bytes, or masterKey is not 32 bytes.

LibSodiumException

Thrown if the native key derivation fails.

DeriveSubkey(SecureMemory<byte>, SecureMemory<byte>, ulong, string)

Deterministically derives a subkey from a master key, using a context string whose UTF-8 representation is at most 8 bytes, and a subkey ID. If the string is shorter, it is padded with zeros. Uses the BLAKE2b hash function internally.

public static void DeriveSubkey(SecureMemory<byte> masterKey, SecureMemory<byte> subkey, ulong subkeyId, string context)

Parameters

masterKey SecureMemory<byte>

The master key (32 bytes).

subkey SecureMemory<byte>

The buffer where the derived subkey will be written. Its length must be between 16 and 64 bytes.

subkeyId ulong

The identifier for the subkey (application-defined).

context string

A string whose UTF-8 representation must be at most 8 bytes and describes the usage context.

Exceptions

ArgumentNullException

Thrown when context is null.

ArgumentException

Thrown when context exceeds 8 UTF-8 bytes, or subkey or masterKey are of invalid length.

LibSodiumException

Thrown if the native key derivation fails.

DeriveSubkey(SecureMemory<byte>, ulong, ReadOnlySpan<byte>, SecureMemory<byte>)

Deterministically derives a subkey from a master key, context, and subkey ID. Uses the BLAKE2b hash function internally.

[Obsolete("Use the other overload instead. This will be removed in a future version.")]
public static void DeriveSubkey(SecureMemory<byte> subkey, ulong subkeyId, ReadOnlySpan<byte> context, SecureMemory<byte> masterKey)

Parameters

subkey SecureMemory<byte>

The buffer where the derived subkey will be written. Its length must be between 16 and 64 bytes.

subkeyId ulong

The identifier for the subkey (application-defined).

context ReadOnlySpan<byte>

8-byte context describing the usage.

masterKey SecureMemory<byte>

The master key (32 bytes).

Exceptions

ArgumentException

Thrown when subkey is out of bounds, context is not 8 bytes, or masterKey is not 32 bytes.

LibSodiumException

Thrown if the native key derivation fails.

DeriveSubkey(SecureMemory<byte>, ulong, string, SecureMemory<byte>)

Deterministically derives a subkey from a master key, using a context string whose UTF-8 representation is at most 8 bytes, and a subkey ID. If the string is shorter, it is padded with zeros. Uses the BLAKE2b hash function internally.

[Obsolete("Use the other overload instead. This will be removed in a future version.")]
public static void DeriveSubkey(SecureMemory<byte> subkey, ulong subkeyId, string context, SecureMemory<byte> masterKey)

Parameters

subkey SecureMemory<byte>

The buffer where the derived subkey will be written. Its length must be between 16 and 64 bytes.

subkeyId ulong

The identifier for the subkey (application-defined).

context string

A string whose UTF-8 representation must be at most 8 bytes and describes the usage context.

masterKey SecureMemory<byte>

The master key (32 bytes).

Exceptions

ArgumentNullException

Thrown when context is null.

ArgumentException

Thrown when context exceeds 8 UTF-8 bytes, or subkey or masterKey are of invalid length.

LibSodiumException

Thrown if the native key derivation fails.

DeriveSubkey(ReadOnlySpan<byte>, Span<byte>, ulong, ReadOnlySpan<byte>)

Deterministically derives a subkey from a master key, context, and subkey ID. Uses the BLAKE2b hash function internally.

public static void DeriveSubkey(ReadOnlySpan<byte> masterKey, Span<byte> subkey, ulong subkeyId, ReadOnlySpan<byte> context)

Parameters

masterKey ReadOnlySpan<byte>

The master key (32 bytes).

subkey Span<byte>

The buffer where the derived subkey will be written. Its length must be between 16 and 64 bytes.

subkeyId ulong

The identifier for the subkey (application-defined).

context ReadOnlySpan<byte>

8-byte context describing the usage.

Exceptions

ArgumentException

Thrown when subkey is out of bounds, context is not 8 bytes, or masterKey is not 32 bytes.

LibSodiumException

Thrown if the native key derivation fails.

DeriveSubkey(ReadOnlySpan<byte>, Span<byte>, ulong, string)

Deterministically derives a subkey from a master key, using a context string whose UTF-8 representation is at most 8 bytes, and a subkey ID. If the string is shorter, it is padded with zeros. Uses the BLAKE2b hash function internally.

public static void DeriveSubkey(ReadOnlySpan<byte> masterKey, Span<byte> subkey, ulong subkeyId, string context)

Parameters

masterKey ReadOnlySpan<byte>

The master key (32 bytes).

subkey Span<byte>

The buffer where the derived subkey will be written. Its length must be between 16 and 64 bytes.

subkeyId ulong

The identifier for the subkey (application-defined).

context string

A string whose UTF-8 representation must be at most 8 bytes and describes the usage context.

Exceptions

ArgumentNullException

Thrown when context is null.

ArgumentException

Thrown when context exceeds 8 UTF-8 bytes, or subkey or masterKey are of invalid length.

LibSodiumException

Thrown if the native key derivation fails.

DeriveSubkey(Span<byte>, ulong, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Deterministically derives a subkey from a master key, context, and subkey ID. Uses the BLAKE2b hash function internally.

[Obsolete("Use the other overload instead. This will be removed in a future version.")]
public static void DeriveSubkey(Span<byte> subkey, ulong subkeyId, ReadOnlySpan<byte> context, ReadOnlySpan<byte> masterKey)

Parameters

subkey Span<byte>

The buffer where the derived subkey will be written. Its length must be between 16 and 64 bytes.

subkeyId ulong

The identifier for the subkey (application-defined).

context ReadOnlySpan<byte>

8-byte context describing the usage.

masterKey ReadOnlySpan<byte>

The master key (32 bytes).

Exceptions

ArgumentException

Thrown when subkey is out of bounds, context is not 8 bytes, or masterKey is not 32 bytes.

LibSodiumException

Thrown if the native key derivation fails.

DeriveSubkey(Span<byte>, ulong, string, ReadOnlySpan<byte>)

Deterministically derives a subkey from a master key, using a context string whose UTF-8 representation is at most 8 bytes, and a subkey ID. If the string is shorter, it is padded with zeros. Uses the BLAKE2b hash function internally.

[Obsolete("Use the other overload instead. This will be removed in a future version.")]
public static void DeriveSubkey(Span<byte> subkey, ulong subkeyId, string context, ReadOnlySpan<byte> masterKey)

Parameters

subkey Span<byte>

The buffer where the derived subkey will be written. Its length must be between 16 and 64 bytes.

subkeyId ulong

The identifier for the subkey (application-defined).

context string

A string whose UTF-8 representation must be at most 8 bytes and describes the usage context.

masterKey ReadOnlySpan<byte>

The master key (32 bytes).

Exceptions

ArgumentNullException

Thrown when context is null.

ArgumentException

Thrown when context exceeds 8 UTF-8 bytes, or subkey or masterKey are of invalid length.

LibSodiumException

Thrown if the native key derivation fails.

GenerateMasterKey(SecureMemory<byte>)

Fills the given buffer with a new random master key (32 bytes).

public static void GenerateMasterKey(SecureMemory<byte> masterKey)

Parameters

masterKey SecureMemory<byte>

The buffer to fill. Must be 32 bytes.

Exceptions

ArgumentException

Thrown when masterKey is not 32 bytes.

GenerateMasterKey(Span<byte>)

Fills the given buffer with a new random master key (32 bytes).

public static void GenerateMasterKey(Span<byte> masterKey)

Parameters

masterKey Span<byte>

The buffer to fill. Must be 32 bytes.

Exceptions

ArgumentException

Thrown when masterKey is not 32 bytes.