Class KeyDerivationSettings

Configuration settings for the PBKDF2 key derivation function (KDF) used by DeriveKey(string, byte[], KeyDerivationSettings) and the async equivalent DeriveKeyAsync(string, byte[], KeyDerivationSettings, CancellationToken). Controls iteration count, hash algorithm, and the size of the derived key.

Inheritance

object

KeyDerivationSettings

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Scylla.Core.Util.Crypto

Assembly: ScyllaCore.dll

Syntax

public sealed class KeyDerivationSettings

Remarks

KeyDerivationSettings is a focused counterpart to CryptoSettings for scenarios where only key derivation is needed (e.g., deriving a key to pass to EncryptWithKey(byte[], byte[])) without bundling the full encryption algorithm choice.

The three settings interact as follows:

• Iterations controls the PBKDF2 work factor. Higher values make brute-force attacks more expensive but increase derivation time linearly. Must be at least MIN_ITERATIONS (10,000) as enforced by Validate().
• HashAlgorithm selects the PRF (pseudo-random function) used by PBKDF2 internally. SHA512 may be faster on 64-bit native platforms; SHA256 is preferable on 32-bit or WebGL targets.
• KeySizeBytes determines how many bytes of key material PBKDF2 produces. Match this to the key size required by the target cipher (e.g., 32 bytes for AES-256 or ChaCha20-Poly1305, 16 bytes for AES-128).

Constructors

KeyDerivationSettings()

Initializes a new instance of KeyDerivationSettings with default values.

Declaration

public KeyDerivationSettings()

KeyDerivationSettings(KeyDerivationSettings)

Initializes a new instance of KeyDerivationSettings by copying values from another instance.

Declaration

public KeyDerivationSettings(KeyDerivationSettings other)

Parameters

Type	Name	Description
KeyDerivationSettings	other	The settings to copy from.

Properties

Default

Gets a pre-built KeyDerivationSettings instance with recommended defaults: SHA256, DEFAULT_ITERATIONS iterations (600,000), and a 32-byte (256-bit) output key.

Declaration

public static KeyDerivationSettings Default { get; }

Property Value

Type	Description
KeyDerivationSettings	A shared, immutable KeyDerivationSettings instance. Do not mutate this instance; call Clone() to obtain an independent modifiable copy.

See Also

Default

HashAlgorithm

Gets or sets the hash function used as the PBKDF2 pseudo-random function. Defaults to SHA256.

Declaration

public KeyDerivationHash HashAlgorithm { get; set; }

Property Value

Type	Description
KeyDerivationHash	A KeyDerivationHash value. SHA512 may provide higher throughput on 64-bit native platforms but is slower on 32-bit and WebGL targets. The derived key material is cryptographically equivalent in strength for both choices given sufficient iterations.

See Also

KeyDerivationHash

Iterations

Gets or sets the number of PBKDF2 iterations applied during key derivation. Each additional iteration increases the cost of a brute-force attack by a proportional amount, at the expense of linear increase in derivation time. Defaults to DEFAULT_ITERATIONS (600,000).

Declaration

public int Iterations { get; set; }

Property Value

Type	Description
int	Must be at least MIN_ITERATIONS (10,000) as enforced by Validate(). For interactive use cases on mobile, consider running derivation asynchronously via DeriveKeyAsync(string, byte[], KeyDerivationSettings, CancellationToken) to avoid blocking the main thread.

KeySizeBytes

Gets or sets the number of bytes to produce from the PBKDF2 output. This must match the key size expected by the target cipher. Defaults to 32 bytes (256 bits), appropriate for AES-256 and ChaCha20-Poly1305.

Declaration

public int KeySizeBytes { get; set; }

Property Value

Type	Description
int	Must be between 16 and 64 bytes inclusive as enforced by Validate(). Common values: 16 for AES-128, 24 for AES-192, 32 for AES-256 or ChaCha20-Poly1305.

Methods

Clone()

Creates an independent copy of this KeyDerivationSettings instance. Use this to derive a modified configuration from Default without altering the shared preset.

Declaration

public KeyDerivationSettings Clone()

Returns

Type	Description
KeyDerivationSettings	A new KeyDerivationSettings instance with all property values copied from this instance. The returned instance is fully independent of the source.

Validate()

Validates all settings fields and throws CryptoException on the first invalid value. Call this before passing a custom KeyDerivationSettings to any key derivation API.

Declaration

public void Validate()

Remarks

The following conditions are checked, in order:

1. Iterations must be at least MIN_ITERATIONS (currently 10,000). Lower values throw with InvalidIterationCount.
2. KeySizeBytes must be between 16 and 64 bytes inclusive. Values outside this range throw with InvalidKeySize.

Exceptions

Type	Condition
CryptoException	Thrown with InvalidIterationCount if Iterations is below MIN_ITERATIONS; with InvalidKeySize if KeySizeBytes is outside the range [16, 64].

Extension Methods

FileExtensions.SaveSecureToFileAsync<T>(T, string, string, CancellationToken)

FileExtensions.SaveSecureToFile<T>(T, string, string)

FileExtensions.SaveToFileAsync<T>(T, string, CancellationToken)

FileExtensions.SaveToFile<T>(T, string)

FileExtensions.SaveToFile<T>(T, string, SerializationSettings)

See Also

DeriveKey(string, byte[], KeyDerivationSettings)

DeriveKeyAsync(string, byte[], KeyDerivationSettings, CancellationToken)

CryptoSettings

KeyDerivationHash