Class CryptoExtensions

Provides extension methods for cryptographic operations on byte arrays and strings, enabling a fluent API for encryption, decryption, and Base64 encoding.

Inheritance
object
CryptoExtensions
Inherited Members
Namespace: Scylla.Core.Util.Crypto
Assembly: ScyllaCore.dll
Syntax
public static class CryptoExtensions
Remarks

All methods in this class are convenience wrappers that delegate directly to ScyllaCrypto. They exist to allow natural, chainable call syntax on byte arrays and strings without having to reference ScyllaCrypto explicitly at every call site. There is no behavioural difference between calling an extension method here and calling the corresponding static method on ScyllaCrypto directly.

Two encryption modes are available throughout this class:

  • Password-based - The supplied password is processed through PBKDF2 key derivation before encryption. Iteration count, salt size, key size, and algorithm are controlled via CryptoSettings. All parameters required for decryption are embedded in the ciphertext header, so the caller only needs the password to decrypt.
  • Key-based - A raw cryptographic key is supplied directly. Key derivation is skipped entirely, which improves performance at the cost of requiring the caller to manage key material. The key length (16, 24, or 32 bytes) determines the AES key size (128, 192, or 256 bits respectively).

Async variants offload the encryption and PBKDF2 key derivation to a background thread via Task.Run, preventing the Unity main thread from blocking during cryptographic operations on large payloads or with high iteration counts.

Methods

Decrypt(byte[], string)

Decrypts a byte array that was previously encrypted with Encrypt(byte[], string) or Encrypt(byte[], string), using the supplied password. All decryption parameters (algorithm, key size, salt, and PBKDF2 iteration count) are read from the ciphertext header; no external metadata is required.

Declaration
public static byte[] Decrypt(this byte[] data, string password)
Parameters
Type Name Description
byte[] data

The ciphertext byte array produced by a prior call to Encrypt(byte[], string). Must not be null and must contain a valid embedded header followed by at least 16 bytes of encrypted payload.
string password

The password that was used during encryption. Must not be null or empty. Supplying a wrong password results in a CryptoException with an authentication failure code rather than silently returning garbage plaintext.
Returns
Type Description
byte[]

The original plaintext byte array. The returned array is a new allocation; the caller is responsible for zeroing it when it contains sensitive data (use SecureClear(byte[])).
Remarks

This method is a convenience wrapper around Decrypt(byte[], string). PBKDF2 key derivation is repeated during decryption using the iteration count and salt stored in the header, so the computational cost matches that of the original encryption call.

Exceptions
Type Condition
CryptoException

Thrown when data is null, too short, or has a corrupted header; when password is null or empty; or when authentication fails (wrong password or tampered ciphertext).
See Also

Decrypt(byte[], string, CryptoSettings)

Decrypts a byte array that was previously encrypted with a password, applying custom decryption settings.

Declaration
public static byte[] Decrypt(this byte[] data, string password, CryptoSettings settings)
Parameters
Type Name Description
byte[] data

The ciphertext byte array produced by a prior call to Encrypt(byte[], string, CryptoSettings). Must not be null.
string password

The password that was used during encryption. Must not be null or empty.
CryptoSettings settings

Optional CryptoSettings to override decryption parameters. When provided, the algorithm and key size are still taken from the ciphertext header (to ensure compatibility), but the PBKDF2 iteration count from settings may be respected. Pass null to use parameters embedded in the ciphertext header without any override.
Returns
Type Description
byte[]

The original plaintext byte array.
Remarks

This method is a convenience wrapper around Decrypt(byte[], string, CryptoSettings).

Exceptions
Type Condition
CryptoException

Thrown when data is null, corrupted, or when authentication fails.
See Also

DecryptAsync(byte[], string, CryptoSettings, CancellationToken)

Asynchronously decrypts a byte array that was encrypted with a password, applying custom decryption settings and offloading the operation to a background thread.

Declaration
public static Task<byte[]> DecryptAsync(this byte[] data, string password, CryptoSettings settings, CancellationToken cancellationToken = default)
Parameters
Type Name Description
byte[] data

The ciphertext byte array to decrypt. Must not be null.
string password

The password that was used during encryption. Must not be null or empty.
CryptoSettings settings

Optional CryptoSettings. The algorithm and key size are read from the ciphertext header. Pass null to use embedded parameters exclusively.
CancellationToken cancellationToken

An optional CancellationToken to cancel the operation. Defaults to None.
Returns
Type Description
Task<byte[]>

A Task<TResult> that yields the decrypted plaintext byte array.
Remarks

This method is a convenience wrapper around DecryptAsync(byte[], string, CryptoSettings, CancellationToken).

Exceptions
Type Condition
CryptoException

Thrown (via the returned task) when parameters are invalid, the operation is cancelled, or authentication fails.
See Also

DecryptAsync(byte[], string, CancellationToken)

Asynchronously decrypts a byte array that was previously encrypted with a password, offloading PBKDF2 key derivation and decryption to a background thread.

Declaration
public static Task<byte[]> DecryptAsync(this byte[] data, string password, CancellationToken cancellationToken = default)
Parameters
Type Name Description
byte[] data

The ciphertext byte array produced by a prior call to Encrypt(byte[], string) or EncryptAsync(byte[], string, CancellationToken). Must not be null.
string password

The password that was used during encryption. Must not be null or empty.
CancellationToken cancellationToken

An optional CancellationToken to cancel the operation. Defaults to None.
Returns
Type Description
Task<byte[]>

A Task<TResult> that yields the decrypted plaintext byte array.
Remarks

This method is a convenience wrapper around DecryptAsync(byte[], string, CancellationToken). PBKDF2 key derivation is performed asynchronously using the iteration count and salt stored in the ciphertext header.

Exceptions
Type Condition
CryptoException

Thrown (via the returned task) when data is null, corrupted, or too short; when password is null or empty; when the operation is cancelled; or when authentication fails.
See Also

DecryptFromBase64(string, string)

Decrypts a Base64-encoded ciphertext string that was produced by EncryptToBase64(string, string) or EncryptString(string, string), recovering the original plaintext string. The Base64 decoding and byte-to-string conversion (UTF-8) are handled automatically.

Declaration
public static string DecryptFromBase64(this string ciphertext, string password)
Parameters
Type Name Description
string ciphertext

The Base64-encoded encrypted string produced by a prior call to EncryptToBase64(string, string). Must not be null or empty, and must be valid Base64; a CryptoException is thrown otherwise.
string password

The password that was used during encryption. Must not be null or empty. An incorrect password causes a CryptoException with an authentication failure code.
Returns
Type Description
string

The original plaintext string, decoded from UTF-8.
Remarks

This method is a convenience wrapper around DecryptString(string, string).

The intermediate ciphertext byte array and the decrypted UTF-8 byte array are both cleared with SecureClear(byte[]) after use to limit sensitive data exposure in managed memory. The returned string itself cannot be zeroed because C# strings are immutable.

Exceptions
Type Condition
CryptoException

Thrown when ciphertext is null, empty, or not valid Base64; when password is null or empty; or when authentication fails (wrong password or tampered ciphertext).
See Also

DecryptFromBase64(string, string, CryptoSettings)

Decrypts a Base64-encoded ciphertext string using the specified password and custom decryption settings.

Declaration
public static string DecryptFromBase64(this string ciphertext, string password, CryptoSettings settings)
Parameters
Type Name Description
string ciphertext

The Base64-encoded encrypted string produced by a prior call to EncryptToBase64(string, string, CryptoSettings). Must not be null or empty.
string password

The password that was used during encryption. Must not be null or empty.
CryptoSettings settings

Optional CryptoSettings. The algorithm and key size are read from the ciphertext header and are not overridden by settings. Pass null to rely entirely on header-embedded parameters.
Returns
Type Description
string

The original plaintext string.
Remarks

This method is a convenience wrapper around DecryptString(string, string, CryptoSettings).

Exceptions
Type Condition
CryptoException

Thrown when ciphertext is invalid, password is null or empty, or authentication fails.
See Also

DecryptFromBase64Async(string, string, CryptoSettings, CancellationToken)

Asynchronously decrypts a Base64-encoded ciphertext string using the specified password and custom decryption settings, offloading the operation to a background thread.

Declaration
public static Task<string> DecryptFromBase64Async(this string ciphertext, string password, CryptoSettings settings, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string ciphertext

The Base64-encoded encrypted string to decrypt. Must not be null or empty.
string password

The password that was used during encryption. Must not be null or empty.
CryptoSettings settings

Optional CryptoSettings. The algorithm and key size are read from the ciphertext header and are not overridden by settings. Pass null to rely entirely on header-embedded parameters.
CancellationToken cancellationToken

An optional CancellationToken to cancel the operation. Defaults to None.
Returns
Type Description
Task<string>

A Task<TResult> that yields the original plaintext string.
Remarks

This method is a convenience wrapper around DecryptStringAsync(string, string, CryptoSettings, CancellationToken).

Exceptions
Type Condition
CryptoException

Thrown (via the returned task) when parameters are invalid, the ciphertext is corrupted, the operation is cancelled, or authentication fails.
See Also

DecryptFromBase64Async(string, string, CancellationToken)

Asynchronously decrypts a Base64-encoded ciphertext string that was produced by EncryptToBase64(string, string) or EncryptToBase64Async(string, string, CancellationToken), recovering the original plaintext. The operation is offloaded to a background thread.

Declaration
public static Task<string> DecryptFromBase64Async(this string ciphertext, string password, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string ciphertext

The Base64-encoded encrypted string to decrypt. Must not be null or empty, and must be valid Base64.
string password

The password that was used during encryption. Must not be null or empty.
CancellationToken cancellationToken

An optional CancellationToken to cancel the operation. Defaults to None.
Returns
Type Description
Task<string>

A Task<TResult> that yields the original plaintext string, decoded from UTF-8.
Remarks

This method is a convenience wrapper around DecryptStringAsync(string, string, CancellationToken).

The intermediate ciphertext byte array and the decrypted UTF-8 byte array are cleared with SecureClear(byte[]) after use. PBKDF2 key derivation runs asynchronously using the parameters embedded in the ciphertext header.

Exceptions
Type Condition
CryptoException

Thrown (via the returned task) when ciphertext is null, empty, not valid Base64, or has been tampered with; when password is null or empty; when the operation is cancelled; or when authentication fails.
See Also

DecryptWithKey(byte[], byte[])

Decrypts a byte array that was previously encrypted with EncryptWithKey(byte[], byte[]) or EncryptWithKey(byte[], byte[]), using the same raw key. No PBKDF2 derivation is performed; the key is used directly.

Declaration
public static byte[] DecryptWithKey(this byte[] data, byte[] key)
Parameters
Type Name Description
byte[] data

The ciphertext byte array produced by a prior key-based encryption call. Must not be null and must contain a valid 3-byte header followed by at least 16 bytes of payload.
byte[] key

The raw decryption key. Must be the same key (same bytes) that was supplied to the corresponding encryption call. Must not be null. Providing an incorrect key results in a CryptoException with an authentication failure code.
Returns
Type Description
byte[]

The original plaintext byte array. The caller is responsible for zeroing it when it contains sensitive data (use SecureClear(byte[])).
Remarks

This method is a convenience wrapper around DecryptWithKey(byte[], byte[]).

Because key derivation is skipped, this method is faster than its password-based counterpart Decrypt(byte[], string). The algorithm and key size used for decryption are read from the ciphertext header written during encryption, so the caller does not need to track these separately.

Exceptions
Type Condition
CryptoException

Thrown when data or key is null, when the ciphertext is too short or has a corrupted header, or when authentication fails.
See Also

DecryptWithKey(byte[], byte[], CryptoSettings)

Decrypts a byte array that was previously encrypted with a raw key, applying custom decryption settings.

Declaration
public static byte[] DecryptWithKey(this byte[] data, byte[] key, CryptoSettings settings)
Parameters
Type Name Description
byte[] data

The ciphertext byte array produced by a prior key-based encryption call. Must not be null.
byte[] key

The raw decryption key. Must be identical to the key used during encryption. Must not be null.
CryptoSettings settings

Optional CryptoSettings. In key-based decryption the algorithm is always read from the ciphertext header, so the Algorithm property of settings is not used. Pass null to rely entirely on header-embedded information.
Returns
Type Description
byte[]

The original plaintext byte array.
Remarks

This method is a convenience wrapper around DecryptWithKey(byte[], byte[], CryptoSettings).

Exceptions
Type Condition
CryptoException

Thrown when data or key is null, when the ciphertext is corrupted, or when authentication fails.
See Also

DecryptWithKeyAsync(byte[], byte[], CryptoSettings, CancellationToken)

Asynchronously decrypts a byte array that was encrypted with a raw key, applying custom decryption settings and offloading the operation to a background thread.

Declaration
public static Task<byte[]> DecryptWithKeyAsync(this byte[] data, byte[] key, CryptoSettings settings, CancellationToken cancellationToken = default)
Parameters
Type Name Description
byte[] data

The ciphertext byte array to decrypt. Must not be null.
byte[] key

The raw decryption key. Must be identical to the key used during encryption. Must not be null.
CryptoSettings settings

Optional CryptoSettings. In key-based decryption the algorithm is read from the ciphertext header and is not overridden by settings. Pass null to rely entirely on header-embedded information.
CancellationToken cancellationToken

An optional CancellationToken to cancel the operation. Defaults to None.
Returns
Type Description
Task<byte[]>

A Task<TResult> that yields the decrypted plaintext byte array.
Remarks

This method is a convenience wrapper around DecryptWithKeyAsync(byte[], byte[], CryptoSettings, CancellationToken).

Exceptions
Type Condition
CryptoException

Thrown (via the returned task) when data or key is null, the ciphertext is corrupted, the operation is cancelled, or authentication fails.
See Also

DecryptWithKeyAsync(byte[], byte[], CancellationToken)

Asynchronously decrypts a byte array that was previously encrypted with a raw key, offloading the operation to a background thread.

Declaration
public static Task<byte[]> DecryptWithKeyAsync(this byte[] data, byte[] key, CancellationToken cancellationToken = default)
Parameters
Type Name Description
byte[] data

The ciphertext byte array produced by a prior call to EncryptWithKey(byte[], byte[]) or EncryptWithKeyAsync(byte[], byte[], CancellationToken). Must not be null.
byte[] key

The raw decryption key. Must be identical to the key used during encryption. Must not be null.
CancellationToken cancellationToken

An optional CancellationToken to cancel the operation. Defaults to None.
Returns
Type Description
Task<byte[]>

A Task<TResult> that yields the decrypted plaintext byte array.
Remarks

This method is a convenience wrapper around DecryptWithKeyAsync(byte[], byte[], CancellationToken). Because no PBKDF2 derivation is required, the async benefit here comes solely from moving the decryption computation off the Unity main thread.

Exceptions
Type Condition
CryptoException

Thrown (via the returned task) when data or key is null, the ciphertext is corrupted, the operation is cancelled, or authentication fails.
See Also

Encrypt(byte[], string)

Encrypts the byte array using the specified password and authenticated encryption. The encryption parameters (algorithm, key size, salt, and PBKDF2 iteration count) are chosen from DefaultAlgorithm, DefaultKeySize, and DefaultIterations and are embedded in the returned ciphertext, so no additional metadata needs to be stored by the caller.

Declaration
public static byte[] Encrypt(this byte[] data, string password)
Parameters
Type Name Description
byte[] data

The plaintext byte array to encrypt. Must not be null; a CryptoException is thrown otherwise.
string password

The password from which the encryption key is derived via PBKDF2. Must not be null or empty; a CryptoException is thrown otherwise.
Returns
Type Description
byte[]

A new byte array containing the ciphertext with an embedded header that records the algorithm, key size, PBKDF2 iteration count, and salt. Pass this array together with the same password to Decrypt(byte[], string) to recover the original data.
Remarks

This method is a convenience wrapper around Encrypt(byte[], string). Internally, the password is processed through PBKDF2 with the configured number of iterations (default 600,000) before being used as the encryption key. To customise the algorithm, key size, salt size, or iteration count, use the overload that accepts a CryptoSettings argument.

Exceptions
Type Condition
CryptoException

Thrown when data is null, password is null or empty, or an internal encryption error occurs.
See Also

Encrypt(byte[], string, CryptoSettings)

Encrypts the byte array using the specified password and authenticated encryption, applying custom cryptographic settings.

Declaration
public static byte[] Encrypt(this byte[] data, string password, CryptoSettings settings)
Parameters
Type Name Description
byte[] data

The plaintext byte array to encrypt. Must not be null.
string password

The password from which the encryption key is derived via PBKDF2. Must not be null or empty.
CryptoSettings settings

A CryptoSettings instance that controls the encryption algorithm, AES key size in bits, PBKDF2 iteration count, salt size, and the HMAC hash algorithm. Use Default for balanced security, Fast for reduced iteration count, or Secure for maximum security. When null, global defaults from ScyllaCrypto are used.
Returns
Type Description
byte[]

A new byte array containing the ciphertext with an embedded header. Pass this array and the same password to Decrypt(byte[], string, CryptoSettings) to recover the original data. The algorithm and key size are always read from the embedded header during decryption; providing a CryptoSettings with a different algorithm to Decrypt will not change the algorithm used.
Remarks

This method is a convenience wrapper around Encrypt(byte[], string, CryptoSettings).

Exceptions
Type Condition
CryptoException

Thrown when data is null, password is null or empty, the settings fail validation, or an internal encryption error occurs.
See Also

EncryptAsync(byte[], string, CryptoSettings, CancellationToken)

Asynchronously encrypts the byte array using the specified password and custom encryption settings, offloading the operation to a background thread.

Declaration
public static Task<byte[]> EncryptAsync(this byte[] data, string password, CryptoSettings settings, CancellationToken cancellationToken = default)
Parameters
Type Name Description
byte[] data

The plaintext byte array to encrypt. Must not be null.
string password

The password from which the encryption key is derived via PBKDF2. Must not be null or empty.
CryptoSettings settings

A CryptoSettings instance that controls the encryption algorithm, AES key size, PBKDF2 iteration count, and salt size. Pass null to use the global defaults from ScyllaCrypto.
CancellationToken cancellationToken

An optional CancellationToken to cancel the operation. Defaults to None.
Returns
Type Description
Task<byte[]>

A Task<TResult> that yields the encrypted byte array on completion.
Remarks

This method is a convenience wrapper around EncryptAsync(byte[], string, CryptoSettings, CancellationToken). The async variant is particularly beneficial when using Secure (1,000,000 PBKDF2 iterations), where the synchronous overload would block the main thread for several seconds.

Exceptions
Type Condition
CryptoException

Thrown (via the returned task) when parameters are invalid, the operation is cancelled, or encryption fails.
See Also

EncryptAsync(byte[], string, CancellationToken)

Asynchronously encrypts the byte array using the specified password and authenticated encryption, offloading both PBKDF2 key derivation and the encryption itself to a background thread to avoid blocking the Unity main thread.

Declaration
public static Task<byte[]> EncryptAsync(this byte[] data, string password, CancellationToken cancellationToken = default)
Parameters
Type Name Description
byte[] data

The plaintext byte array to encrypt. Must not be null.
string password

The password from which the encryption key is derived via PBKDF2. Must not be null or empty.
CancellationToken cancellationToken

An optional CancellationToken that can be used to cancel the operation before it completes. When the token is cancelled, the returned task transitions to a cancelled state and a CryptoException may be thrown. Defaults to None.
Returns
Type Description
Task<byte[]>

A Task<TResult> that, when awaited, yields a byte array containing the ciphertext with an embedded header. The result is identical to calling the synchronous Encrypt(byte[], string) on a background thread.
Remarks

This method is a convenience wrapper around EncryptAsync(byte[], string, CancellationToken).

The async variant is recommended when encrypting large payloads or when using high PBKDF2 iteration counts (such as SECURE_ITERATIONS), where the synchronous overload would stall the Unity main thread for a perceptible duration. For typical small payloads with default settings the synchronous Encrypt(byte[], string) is simpler and sufficient.

Exceptions
Type Condition
CryptoException

Thrown (via the returned task) when data is null, password is null or empty, the operation is cancelled, or an internal encryption error occurs.
See Also

EncryptToBase64(string, string)

Encrypts the string using the specified password and authenticated encryption, then returns the ciphertext as a Base64-encoded string ready for text-based storage. The string is encoded to UTF-8 bytes before encryption; Base64 encoding is applied to the ciphertext bytes before returning.

Declaration
public static string EncryptToBase64(this string plaintext, string password)
Parameters
Type Name Description
string plaintext

The string to encrypt. Must not be null; a CryptoException is thrown otherwise.
string password

The password from which the encryption key is derived via PBKDF2. Must not be null or empty.
Returns
Type Description
string

A Base64-encoded string containing the encrypted ciphertext with an embedded header. Pass this value and the same password to DecryptFromBase64(string, string) to recover the original string.
Remarks

This method is a convenience wrapper around EncryptString(string, string).

The resulting Base64 string is suitable for JSON values, Unity PlayerPrefs, and any other text-based storage medium. Base64 encoding and decoding are handled automatically by this method and its counterpart; the caller never needs to manage raw ciphertext bytes.

Internally the plaintext UTF-8 byte array is cleared with SecureClear(byte[]) after encryption to limit secret material exposure in managed memory.

Exceptions
Type Condition
CryptoException

Thrown when plaintext is null, password is null or empty, or when encryption fails internally.
See Also

EncryptToBase64(string, string, CryptoSettings)

Encrypts the string using the specified password and custom encryption settings, then returns the ciphertext as a Base64-encoded string.

Declaration
public static string EncryptToBase64(this string plaintext, string password, CryptoSettings settings)
Parameters
Type Name Description
string plaintext

The string to encrypt. Must not be null.
string password

The password from which the encryption key is derived via PBKDF2. Must not be null or empty.
CryptoSettings settings

A CryptoSettings instance that controls the encryption algorithm, AES key size, PBKDF2 iteration count, and salt size. Use Fast for lower-latency scenarios or Secure for maximum protection. Pass null to use the global defaults from ScyllaCrypto.
Returns
Type Description
string

A Base64-encoded string containing the encrypted ciphertext with an embedded header.
Remarks

This method is a convenience wrapper around EncryptString(string, string, CryptoSettings).

Exceptions
Type Condition
CryptoException

Thrown when plaintext is null, password is null or empty, the settings fail validation, or encryption fails.
See Also

EncryptToBase64Async(string, string, CryptoSettings, CancellationToken)

Asynchronously encrypts the string using the specified password and custom encryption settings, returning the ciphertext as a Base64-encoded string offloaded to a background thread.

Declaration
public static Task<string> EncryptToBase64Async(this string plaintext, string password, CryptoSettings settings, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string plaintext

The string to encrypt. Must not be null.
string password

The password from which the encryption key is derived via PBKDF2. Must not be null or empty.
CryptoSettings settings

A CryptoSettings instance that controls the encryption algorithm, AES key size, PBKDF2 iteration count, and salt size. Pass null to use the global defaults from ScyllaCrypto.
CancellationToken cancellationToken

An optional CancellationToken to cancel the operation. Defaults to None.
Returns
Type Description
Task<string>

A Task<TResult> that yields a Base64-encoded encrypted string.
Remarks

This method is a convenience wrapper around EncryptStringAsync(string, string, CryptoSettings, CancellationToken). The async variant is recommended when using high iteration counts (e.g. SECURE_ITERATIONS) to avoid main-thread stalls.

Exceptions
Type Condition
CryptoException

Thrown (via the returned task) when parameters are invalid, the settings fail validation, the operation is cancelled, or encryption fails.
See Also

EncryptToBase64Async(string, string, CancellationToken)

Asynchronously encrypts the string using the specified password, returning the ciphertext as a Base64-encoded string. The operation is offloaded to a background thread so the Unity main thread is not blocked during PBKDF2 key derivation or encryption.

Declaration
public static Task<string> EncryptToBase64Async(this string plaintext, string password, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string plaintext

The string to encrypt. Must not be null.
string password

The password from which the encryption key is derived via PBKDF2. Must not be null or empty.
CancellationToken cancellationToken

An optional CancellationToken to cancel the operation. Defaults to None.
Returns
Type Description
Task<string>

A Task<TResult> that yields a Base64-encoded string containing the encrypted ciphertext with an embedded header. Pass this value and the same password to DecryptFromBase64Async(string, string, CancellationToken) to recover the original string.
Remarks

This method is a convenience wrapper around EncryptStringAsync(string, string, CancellationToken).

The UTF-8 byte array converted from plaintext is zeroed with SecureClear(byte[]) after encryption. The returned Base64 string cannot be zeroed because C# strings are immutable.

Base64 encoding is applied automatically; the caller does not need to handle raw ciphertext bytes. Use DecryptFromBase64Async(string, string, CancellationToken) to reverse the operation.

Exceptions
Type Condition
CryptoException

Thrown (via the returned task) when plaintext is null, password is null or empty, the operation is cancelled, or encryption fails.
See Also

EncryptWithKey(byte[], byte[])

Encrypts the byte array using a raw cryptographic key, bypassing PBKDF2 key derivation entirely. This is faster than password-based encryption and is appropriate when key material is already available (e.g. from GenerateKey(int) or a prior DeriveKey(string, byte[], int) call).

Declaration
public static byte[] EncryptWithKey(this byte[] data, byte[] key)
Parameters
Type Name Description
byte[] data

The plaintext byte array to encrypt. Must not be null.
byte[] key

The raw encryption key. Must not be null. The key length determines the AES key size: 16 bytes = 128-bit, 24 bytes = 192-bit, 32 bytes = 256-bit. Using a 32-byte key provides the strongest encryption. The caller is responsible for generating and securely storing this key; use GenerateKey(int) to produce a cryptographically secure key.
Returns
Type Description
byte[]

A new byte array containing the ciphertext with a minimal 3-byte header that records the algorithm and key size. Pass this array and the same key to DecryptWithKey(byte[], byte[]) to recover the original data.
Remarks

This method is a convenience wrapper around EncryptWithKey(byte[], byte[]).

Because no key derivation is performed, this method is significantly faster than Encrypt(byte[], string) and is suitable for scenarios where throughput matters (e.g. encrypting many small payloads in a loop). The trade-off is that the caller must securely manage and store the key separately from the ciphertext.

Call SecureClear(byte[]) on the key array when it is no longer needed to prevent sensitive key material from remaining in managed memory.

Exceptions
Type Condition
CryptoException

Thrown when data or key is null, or when an internal encryption error occurs.
See Also

EncryptWithKey(byte[], byte[], CryptoSettings)

Encrypts the byte array using a raw cryptographic key with custom encryption settings, bypassing PBKDF2 key derivation.

Declaration
public static byte[] EncryptWithKey(this byte[] data, byte[] key, CryptoSettings settings)
Parameters
Type Name Description
byte[] data

The plaintext byte array to encrypt. Must not be null.
byte[] key

The raw encryption key. Must not be null. Length determines AES key size: 16 bytes = 128-bit, 24 bytes = 192-bit, 32 bytes = 256-bit.
CryptoSettings settings

Optional CryptoSettings to override the encryption algorithm. Note that the key size is derived from the actual key length and is not read from settings in key-based mode. Pass null to use the global defaults from ScyllaCrypto.
Returns
Type Description
byte[]

A new byte array containing the ciphertext with an embedded 3-byte header.
Remarks

This method is a convenience wrapper around EncryptWithKey(byte[], byte[], CryptoSettings).

Exceptions
Type Condition
CryptoException

Thrown when data or key is null, or when an internal encryption error occurs.
See Also

EncryptWithKeyAsync(byte[], byte[], CryptoSettings, CancellationToken)

Asynchronously encrypts the byte array using a raw cryptographic key with custom encryption settings, offloading the operation to a background thread.

Declaration
public static Task<byte[]> EncryptWithKeyAsync(this byte[] data, byte[] key, CryptoSettings settings, CancellationToken cancellationToken = default)
Parameters
Type Name Description
byte[] data

The plaintext byte array to encrypt. Must not be null.
byte[] key

The raw encryption key. Must not be null. Length determines AES key size: 16 bytes = 128-bit, 24 bytes = 192-bit, 32 bytes = 256-bit.
CryptoSettings settings

Optional CryptoSettings to override the encryption algorithm. Note that the key size is derived from the actual key length and is not read from settings in key-based mode. Pass null to use the global defaults from ScyllaCrypto.
CancellationToken cancellationToken

An optional CancellationToken to cancel the operation. Defaults to None.
Returns
Type Description
Task<byte[]>

A Task<TResult> that yields the encrypted byte array.
Remarks

This method is a convenience wrapper around EncryptWithKeyAsync(byte[], byte[], CryptoSettings, CancellationToken).

Exceptions
Type Condition
CryptoException

Thrown (via the returned task) when data or key is null, the operation is cancelled, or encryption fails.
See Also

EncryptWithKeyAsync(byte[], byte[], CancellationToken)

Asynchronously encrypts the byte array using a raw cryptographic key, bypassing PBKDF2 key derivation and offloading the encryption to a background thread.

Declaration
public static Task<byte[]> EncryptWithKeyAsync(this byte[] data, byte[] key, CancellationToken cancellationToken = default)
Parameters
Type Name Description
byte[] data

The plaintext byte array to encrypt. Must not be null.
byte[] key

The raw encryption key. Must not be null. Length determines AES key size: 16 bytes = 128-bit, 24 bytes = 192-bit, 32 bytes = 256-bit.
CancellationToken cancellationToken

An optional CancellationToken to cancel the operation. Defaults to None.
Returns
Type Description
Task<byte[]>

A Task<TResult> that yields the encrypted byte array with a minimal 3-byte header.
Remarks

This method is a convenience wrapper around EncryptWithKeyAsync(byte[], byte[], CancellationToken).

Because PBKDF2 derivation is skipped, this async variant is primarily useful for encrypting large payloads where the encryption itself (not key derivation) is the bottleneck. For small payloads, the synchronous EncryptWithKey(byte[], byte[]) is typically sufficient.

Exceptions
Type Condition
CryptoException

Thrown (via the returned task) when data or key is null, the operation is cancelled, or encryption fails.
See Also

FromBase64(string)

Decodes a Base64-encoded string back to the original byte array.

Declaration
public static byte[] FromBase64(this string base64)
Parameters
Type Name Description
string base64

The Base64 string to decode. When null or empty, the method returns null rather than throwing an exception, mirroring the null-safe behaviour of ToBase64(byte[]).
Returns
Type Description
byte[]

The decoded byte array, or null if base64 is null or empty.
Remarks

This method delegates to FromBase64String(string) and adds a null and empty guard. It is the inverse of ToBase64(byte[]).

Exceptions
Type Condition
FormatException

Thrown by FromBase64String(string) when base64 is not a valid Base64 string (contains invalid characters or incorrect padding).
See Also

SecureClear(byte[])

Overwrites every byte in the array with zero, then clears the managed reference, reducing the window of opportunity for sensitive data to be read from memory.

Declaration
public static void SecureClear(this byte[] data)
Parameters
Type Name Description
byte[] data

The byte array to clear. If null or empty, the call is a no-op and no exception is thrown.
Remarks

This method is a convenience wrapper around SecureClear(byte[]).

Managed memory may remain in the garbage-collected heap for an indeterminate period after an array is no longer referenced. Arrays that hold plaintext, derived keys, passwords converted to bytes, or any other secret material should be cleared with this method immediately after use so that a memory inspection or heap dump cannot recover the sensitive content.

Note that this method zeros the existing array in-place. It does not guarantee that the data was never copied to another location by the JIT compiler, the GC compactor, or any serialization path. It provides a best-effort mitigation, not an absolute guarantee.

See Also

ToBase64(byte[])

Converts the byte array to a Base64-encoded string suitable for text-based storage or transport (e.g. JSON fields, config files, clipboard).

Declaration
public static string ToBase64(this byte[] data)
Parameters
Type Name Description
byte[] data

The byte array to encode. When null, the method returns null rather than throwing an exception, so callers can safely chain this on nullable results.
Returns
Type Description
string

A standard Base64 string (using the +, /, and = characters) representing the bytes in data, or null if data is null.
Remarks

This method delegates to ToBase64String(byte[]) and adds only the null-safety guard. It is the inverse of FromBase64(string).

This is useful for storing the result of Encrypt(byte[], string) or EncryptWithKey(byte[], byte[]) in a text-based format. To encrypt a string directly and receive a Base64 result in one step, consider using EncryptToBase64(string, string) on the plaintext string.

See Also

See Also