Class CryptoSettings

Configuration settings for cryptographic encryption and decryption operations performed by ScyllaCrypto. Controls the choice of algorithm, key size, and password-based key derivation parameters (PBKDF2 iteration count, salt size, and hash).

Inheritance

object

CryptoSettings

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 CryptoSettings

Remarks

Three ready-made presets are available as static properties:

• Default - Uses AES-GCM with a 256-bit key and 600,000 PBKDF2 iterations. Suitable for the vast majority of game data protection scenarios. Balances security and performance on modern hardware.
• Fast - Uses AES-GCM with a 256-bit key and 100,000 PBKDF2 iterations. Suitable for non-sensitive data or situations where encryption latency is a concern and the protected data has low value (e.g., cached assets, ephemeral session state). Not recommended for passwords or long-term secrets.
• Secure - Uses AES-GCM with a 256-bit key and 1,000,000 PBKDF2 iterations. Suitable for high-value data such as account credentials or licence keys. Noticeably slower on mobile devices; consider running key derivation asynchronously via DeriveKeyAsync(string, byte[], KeyDerivationSettings, CancellationToken).

When creating custom settings, call Validate() before passing the instance to any ScyllaCrypto method. Validation enforces a minimum iteration count of MIN_ITERATIONS (10,000) and a minimum salt size of 16 bytes.

/* Custom settings: ChaCha20-Poly1305 with maximum security iteration count. */
var settings = new CryptoSettings
{
    Algorithm    = CryptoAlgorithm.CHACHA20POLY1305,
    KeySizeBits  = 256,          // Only value supported by ChaCha20.
    Iterations   = 500_000,
    SaltSizeBytes = 32,
    HashAlgorithm = KeyDerivationHash.SHA512
};
settings.Validate();
var ciphertext = ScyllaCrypto.Encrypt(data, password, settings);

Constructors

CryptoSettings()

Initializes a new instance of CryptoSettings with default values.

Declaration

public CryptoSettings()

CryptoSettings(CryptoSettings)

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

Declaration

public CryptoSettings(CryptoSettings other)

Parameters

Type	Name	Description
CryptoSettings	other	The settings to copy from.

Fields

DEFAULT_ITERATIONS

Default PBKDF2 iteration count used by Default (600,000 iterations). Matches NIST SP 800-132 recommendations for SHA-256-based PBKDF2 as of 2024 and provides a good balance between key-derivation latency and brute-force resistance on modern hardware.

Declaration

public const int DEFAULT_ITERATIONS = 600000

Field Value

Type	Description
int

DEFAULT_KEY_SIZE_BITS

Default AES key size in bits (256 bits). Provides full AES-256 strength. Valid alternative values for AES are 128 and 192; CHACHA20POLY1305 requires exactly 256.

Declaration

public const int DEFAULT_KEY_SIZE_BITS = 256

Field Value

Type	Description
int

DEFAULT_SALT_SIZE

Default cryptographic salt size in bytes (32 bytes = 256 bits). A fresh random salt of this size is generated per-encryption via GenerateSalt(int) and prepended to the wire format so that identical plaintexts encrypted with the same password always produce unique ciphertexts.

Declaration

public const int DEFAULT_SALT_SIZE = 32

Field Value

Type	Description
int

FAST_ITERATIONS

Reduced PBKDF2 iteration count used by Fast (100,000 iterations). Offers significantly shorter key-derivation time at the cost of a lower work factor. Use only for non-sensitive or ephemeral data where latency is a priority.

Declaration

public const int FAST_ITERATIONS = 100000

Field Value

Type	Description
int

MIN_ITERATIONS

Absolute minimum PBKDF2 iteration count enforced by Validate() (10,000). Values below this threshold are rejected with CryptoException (InvalidIterationCount) because they provide insufficient resistance to dictionary attacks.

Declaration

public const int MIN_ITERATIONS = 10000

Field Value

Type	Description
int

SECURE_ITERATIONS

High PBKDF2 iteration count used by Secure (1,000,000 iterations). Maximises brute-force resistance for high-value secrets such as account credentials or long-lived licence keys. Consider running key derivation asynchronously with DeriveKeyAsync(string, byte[], KeyDerivationSettings, CancellationToken) when using this count on mobile targets.

Declaration

public const int SECURE_ITERATIONS = 1000000

Field Value

Type	Description
int

Properties

Algorithm

Gets or sets the authenticated encryption algorithm to use for all encryption and decryption operations when these settings are passed to ScyllaCrypto. Defaults to AESGCM, which is the recommended choice on all platforms that support it.

Declaration

public CryptoAlgorithm Algorithm { get; set; }

Property Value

Type	Description
CryptoAlgorithm	A CryptoAlgorithm value. If the chosen algorithm is not available on the current platform, ScyllaCrypto will throw CryptoException with UnsupportedAlgorithm. Use GetBestAvailableAlgorithm() to select a platform-safe value automatically.

See Also

IsAlgorithmSupported(CryptoAlgorithm)

GetBestAvailableAlgorithm()

Default

Gets a pre-built CryptoSettings instance with recommended values for the majority of game data protection use cases: AES-GCM, 256-bit key, DEFAULT_ITERATIONS PBKDF2 iterations, 32-byte salt, SHA-256 PBKDF2 hash.

Declaration

public static CryptoSettings Default { get; }

Property Value

Type	Description
CryptoSettings	A shared, immutable CryptoSettings instance. Do not mutate this instance; use Clone() to obtain a modifiable copy.

Fast

Gets a pre-built CryptoSettings instance optimised for lower latency at the cost of reduced brute-force resistance: AES-GCM, 256-bit key, FAST_ITERATIONS PBKDF2 iterations, 32-byte salt, SHA-256 PBKDF2 hash. Suitable for ephemeral or low-value data where key-derivation speed matters.

Declaration

public static CryptoSettings Fast { get; }

Property Value

Type	Description
CryptoSettings	A shared, immutable CryptoSettings instance. Do not mutate this instance; use Clone() to obtain a modifiable copy.

HashAlgorithm

Gets or sets the hash function used internally by the PBKDF2 key derivation step when encrypting or deriving keys from a password. Defaults to SHA256.

Declaration

public KeyDerivationHash HashAlgorithm { get; set; }

Property Value

Type	Description
KeyDerivationHash	A KeyDerivationHash value. SHA512 provides a wider internal state and may be faster on 64-bit platforms due to its native 64-bit arithmetic. Both choices produce output that is cryptographically indistinguishable in practice when used with adequate iteration counts.

See Also

KeyDerivationHash

Iterations

Gets or sets the number of PBKDF2 iterations used to derive a symmetric key from a password. Higher iteration counts increase brute-force cost for attackers at the expense of longer key-derivation time on the application side. 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); lower values are rejected by Validate() with InvalidIterationCount. This setting has no effect on key-based encryption overloads that accept a raw key byte array directly (e.g., EncryptWithKey(byte[], byte[])).

KeySizeBits

Gets or sets the symmetric key size in bits. Controls the key length used by the underlying cipher and, for password-based operations, the length of the key derived from the password via PBKDF2. Defaults to DEFAULT_KEY_SIZE_BITS (256 bits).

Declaration

public int KeySizeBits { get; set; }

Property Value

Type	Description
int	Must be 128, 192, or 256 for AES-based algorithms. For CHACHA20POLY1305, only 256 is accepted; if a smaller value is set and ChaCha20-Poly1305 is selected, ScyllaCrypto automatically promotes the key size to 256 bits before key derivation to satisfy the algorithm's constraint. Validate() accepts all three standard AES values regardless of the algorithm setting.

Remarks

Larger key sizes provide greater security margin but do not measurably affect throughput on modern hardware with hardware AES acceleration. Prefer 256 bits unless you have a specific interoperability constraint requiring 128 or 192.

SaltSizeBytes

Gets or sets the random salt size in bytes for PBKDF2 key derivation. A cryptographic salt of this size is generated fresh for each password-based encryption operation and prepended to the wire format. Defaults to DEFAULT_SALT_SIZE (32 bytes = 256 bits).

Declaration

public int SaltSizeBytes { get; set; }

Property Value

Type	Description
int	Must be at least 16 bytes; values below this threshold are rejected by Validate() with InvalidKeySize. Larger salts increase the entropy of the derived key but have negligible performance impact; 32 bytes is strongly recommended.

Secure

Gets a pre-built CryptoSettings instance optimised for maximum brute-force resistance: AES-GCM, 256-bit key, SECURE_ITERATIONS PBKDF2 iterations, 32-byte salt, SHA-256 PBKDF2 hash. Intended for protecting high-value secrets such as account credentials or long-lived licence keys. Key derivation at this iteration count is noticeably slow on mobile devices; prefer the async APIs.

Declaration

public static CryptoSettings Secure { get; }

Property Value

Type	Description
CryptoSettings	A shared, immutable CryptoSettings instance. Do not mutate this instance; use Clone() to obtain a modifiable copy.

Methods

Clone()

Creates an independent shallow copy of this CryptoSettings instance. Use this when you need to derive a modified configuration from one of the shared preset instances (Default, Fast, Secure) without altering the original.

Declaration

public CryptoSettings Clone()

Returns

Type	Description
CryptoSettings	A new CryptoSettings instance with all property values copied from this instance. The returned instance is fully independent; mutating it does not affect the source.

Validate()

Validates all settings fields and throws CryptoException on the first invalid value. Call this method before passing a custom CryptoSettings instance to any ScyllaCrypto API to get an early, descriptive error rather than a cryptic failure deeper in the provider layer.

Declaration

public void Validate()

Remarks

The following conditions are checked, in order:

1. KeySizeBits must be exactly 128, 192, or 256. Any other value throws with InvalidKeySize.
2. Iterations must be at least MIN_ITERATIONS (currently 10,000). Lower values throw with InvalidIterationCount.
3. SaltSizeBytes must be at least 16 bytes. Lower values throw with InvalidKeySize.

The pre-built presets (Default, Fast, Secure) always pass validation.

Exceptions

Type	Condition
CryptoException	Thrown with InvalidKeySize if KeySizeBits or SaltSizeBytes is out of range; with InvalidIterationCount if Iterations is below MIN_ITERATIONS.

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

ScyllaCrypto

CryptoAlgorithm

KeyDerivationSettings