Interface ICryptoProvider

Defines the contract for all cryptographic algorithm providers used internally by ScyllaCrypto. Each provider encapsulates a single authenticated encryption algorithm and is responsible for generating nonces, computing authentication tags, and producing a self-contained wire format that embeds all metadata required for decryption.

Namespace: Scylla.Core.Util.Crypto
Assembly: ScyllaCore.dll
Syntax
public interface ICryptoProvider
Remarks

Providers follow a singleton pattern. Each implementation exposes a static Instance property that returns the single shared instance of that provider. Providers are stateless with respect to individual operations, so sharing the singleton across threads is safe.

ScyllaCrypto selects a provider at runtime based on the algorithm specified in Algorithm and the platform availability reported by each provider's IsSupported property. Callers should use IsAlgorithmSupported(CryptoAlgorithm) and GetBestAvailableAlgorithm() rather than interacting with providers directly.

All provider implementations produce a self-contained wire format. Decryption reads every piece of metadata (nonce, IV, salt, tag) from the ciphertext bytes, so the same byte array produced by Encrypt can be passed directly to Decrypt without any out-of-band state.

Properties

Algorithm

Gets the CryptoAlgorithm value that identifies the algorithm implemented by this provider. Used by ScyllaCrypto to select the correct provider when routing encryption and decryption calls.

Declaration
CryptoAlgorithm Algorithm { get; }
Property Value
Type Description
CryptoAlgorithm

The algorithm constant corresponding to this provider's implementation (e.g., AESGCM, AESCBCHMAC, or CHACHA20POLY1305).

IsSupported

Gets a value indicating whether this provider is available on the current platform and runtime environment.

Declaration
bool IsSupported { get; }
Property Value
Type Description
bool

true if the underlying .NET cryptographic primitives required by this provider are present and functional on the current platform; false otherwise. For example, AES-GCM is unavailable on some WebGL builds. The result is cached at startup to avoid repeated detection overhead.
See Also

Methods

Decrypt(byte[], byte[], int)

Decrypts a ciphertext buffer produced by this provider's Encrypt(byte[], byte[], int) method and returns the original plaintext bytes.

Declaration
byte[] Decrypt(byte[] ciphertext, byte[] key, int keySizeBits)
Parameters
Type Name Description
byte[] ciphertext

The encrypted buffer, including the provider-specific metadata header (nonce/IV, authentication tag, etc.). Must not be null. Must have been produced by the same provider type and the same key size. Passing a buffer produced by a different provider will result in a CryptoException.
byte[] key

The raw decryption key bytes. Must be identical to the key used during encryption. The array length must equal keySizeBits divided by 8.
int keySizeBits

The key size in bits that was used during encryption. Valid values are 128, 192, or 256.
Returns
Type Description
byte[]

The original plaintext bytes as they were passed to Encrypt(byte[], byte[], int).
Exceptions
Type Condition
CryptoException

Thrown with NullData if ciphertext or key is null; with CorruptedData if the buffer is too short to contain the required header; with AuthenticationFailed if the AEAD authentication tag does not match (wrong key, tampered data, or truncated ciphertext); with InvalidKeySize if keySizeBits is invalid.

DecryptAsync(byte[], byte[], int, CancellationToken)

Asynchronously decrypts a ciphertext buffer on a background thread and returns the original plaintext bytes. Useful for decrypting large payloads without blocking the main Unity thread.

Declaration
Task<byte[]> DecryptAsync(byte[] ciphertext, byte[] key, int keySizeBits, CancellationToken cancellationToken = default)
Parameters
Type Name Description
byte[] ciphertext

The encrypted buffer as produced by Encrypt(byte[], byte[], int) or EncryptAsync(byte[], byte[], int, CancellationToken). Must not be null.
byte[] key

The raw decryption key bytes. Length must equal keySizeBits divided by 8.
int keySizeBits

The key size in bits used during encryption. Valid values are 128, 192, or 256.
CancellationToken cancellationToken

An optional token for cancelling the background operation. When cancelled, the returned task faults with CryptoException carrying OperationCancelled.
Returns
Type Description
Task<byte[]>

A Task<TResult> that resolves to the decrypted plaintext bytes.
Exceptions
Type Condition
CryptoException

Thrown with OperationCancelled if cancellationToken is signalled; with other CryptoErrorCode values for the same reasons as Decrypt(byte[], byte[], int).

Encrypt(byte[], byte[], int)

Encrypts the given plaintext using the supplied raw key bytes and returns a self-contained ciphertext buffer. The returned buffer includes all metadata required for decryption (e.g., nonce/IV, authentication tag) prepended in a provider-specific layout.

Declaration
byte[] Encrypt(byte[] plaintext, byte[] key, int keySizeBits)
Parameters
Type Name Description
byte[] plaintext

The raw bytes to encrypt. Must not be null. An empty array is valid and results in a ciphertext that contains only the metadata header.
byte[] key

The raw encryption key bytes. The array length must equal keySizeBits divided by 8. Use GenerateKey(int) or DeriveKey(string, byte[], int) to produce a suitable key.
int keySizeBits

The key size in bits. Valid values are 128, 192, or 256. Note that CHACHA20POLY1305 only accepts 256; passing a smaller value for that algorithm will throw CryptoException with InvalidKeySize.
Returns
Type Description
byte[]

A byte array containing the provider-specific metadata header followed by the encrypted payload. This buffer is entirely self-contained and can be persisted or transmitted, then passed directly to Decrypt(byte[], byte[], int) or DecryptAsync(byte[], byte[], int, CancellationToken) without additional state.
Exceptions
Type Condition
CryptoException

Thrown with NullData if plaintext or key is null; with InvalidKeySize if keySizeBits is not a supported value or does not match the actual length of key; with UnsupportedAlgorithm if the provider is not available on this platform.

EncryptAsync(byte[], byte[], int, CancellationToken)

Asynchronously encrypts the given plaintext on a background thread and returns the resulting self-contained ciphertext buffer. Useful for encrypting large payloads without blocking the main Unity thread.

Declaration
Task<byte[]> EncryptAsync(byte[] plaintext, byte[] key, int keySizeBits, CancellationToken cancellationToken = default)
Parameters
Type Name Description
byte[] plaintext

The raw bytes to encrypt. Must not be null.
byte[] key

The raw encryption key bytes. Length must equal keySizeBits divided by 8.
int keySizeBits

The key size in bits. Valid values are 128, 192, or 256.
CancellationToken cancellationToken

An optional token for cancelling the background operation. When cancelled, the returned task faults with CryptoException carrying OperationCancelled.
Returns
Type Description
Task<byte[]>

A Task<TResult> that resolves to the encrypted ciphertext buffer, identical in format to the buffer returned by Encrypt(byte[], byte[], int).
Exceptions
Type Condition
CryptoException

Thrown with OperationCancelled if cancellationToken is signalled; with other CryptoErrorCode values for the same reasons as Encrypt(byte[], byte[], int).

TryDecrypt(byte[], byte[], int, out byte[])

Attempts to decrypt a ciphertext buffer without throwing on failure. This is the non-throwing counterpart of Decrypt(byte[], byte[], int) and is useful in scenarios where authentication failure is an expected outcome (e.g., probing multiple passwords without try/catch overhead).

Declaration
bool TryDecrypt(byte[] ciphertext, byte[] key, int keySizeBits, out byte[] plaintext)
Parameters
Type Name Description
byte[] ciphertext

The encrypted buffer as produced by Encrypt(byte[], byte[], int). Must not be null.
byte[] key

The raw decryption key bytes. Must not be null.
int keySizeBits

The key size in bits used during encryption. Valid values are 128, 192, or 256.
byte[] plaintext

When this method returns true, contains the decrypted plaintext. When this method returns false, this parameter is set to null.
Returns
Type Description
bool

true if decryption and authentication succeeded; false if any validation or authentication step failed.

Extension Methods

See Also