Class XChaCha20Poly1305

Namespace

LibSodium

Assembly

LibSodium.Net.dll

Provides high-level access to the XChaCha20-Poly1305 AEAD construction from Libsodium.

public static class XChaCha20Poly1305

Inheritance

object

XChaCha20Poly1305

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This class supports both combined and detached modes of authenticated encryption. It also supports automatic nonce generation when not provided explicitly.

Properties

KeyLen

Key length in bytes (32).

public static int KeyLen { get; }

Property Value

int

MacLen

MAC length in bytes (16).

public static int MacLen { get; }

Property Value

int

NonceLen

Nonce length in bytes (24).

public static int NonceLen { get; }

Property Value

int

Methods

Decrypt(Span<byte>, ReadOnlySpan<byte>, SecureMemory<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Decrypts a message using XChaCha20-Poly1305. Supports combined and detached modes, with optional AAD and nonce.

public static Span<byte> Decrypt(Span<byte> plaintext, ReadOnlySpan<byte> ciphertext, SecureMemory<byte> key, ReadOnlySpan<byte> mac = default, ReadOnlySpan<byte> aad = default, ReadOnlySpan<byte> nonce = default)

Parameters

plaintext Span<byte>

The buffer where the decrypted message will be written.

ciphertext ReadOnlySpan<byte>

The encrypted message. May include MAC and nonce (combined) or exclude them (detached).

key SecureMemory<byte>

The secret decryption key (32 bytes).

mac ReadOnlySpan<byte>

Optional. If provided, decryption is done in detached mode. Otherwise, combined mode is used..

aad ReadOnlySpan<byte>

Optional additional authenticated data. Must match what was used for encryption.

nonce ReadOnlySpan<byte>

Optional nonce (24 bytes). Required for manual nonce mode.

Returns

Span<byte>

The span representing the decrypted plaintext.

Exceptions

ArgumentException

Thrown when buffer sizes are incorrect or parameters are invalid.

LibSodiumException

Thrown when MAC verification fails or decryption fails.

Decrypt(Span<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Decrypts a message using XChaCha20-Poly1305. Supports combined and detached modes, with optional AAD and nonce.

public static Span<byte> Decrypt(Span<byte> plaintext, ReadOnlySpan<byte> ciphertext, ReadOnlySpan<byte> key, ReadOnlySpan<byte> mac = default, ReadOnlySpan<byte> aad = default, ReadOnlySpan<byte> nonce = default)

Parameters

plaintext Span<byte>

The buffer where the decrypted message will be written.

ciphertext ReadOnlySpan<byte>

The encrypted message. May include MAC and nonce (combined) or exclude them (detached).

key ReadOnlySpan<byte>

The secret decryption key (32 bytes).

mac ReadOnlySpan<byte>

Optional. If provided, decryption is done in detached mode. Otherwise, combined mode is used..

aad ReadOnlySpan<byte>

Optional additional authenticated data. Must match what was used for encryption.

nonce ReadOnlySpan<byte>

Optional nonce (24 bytes). Required for manual nonce mode.

Returns

Span<byte>

The span representing the decrypted plaintext.

Exceptions

ArgumentException

Thrown when buffer sizes are incorrect or parameters are invalid.

LibSodiumException

Thrown when MAC verification fails or decryption fails.

Encrypt(Span<byte>, ReadOnlySpan<byte>, SecureMemory<byte>, Span<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Encrypts a message using XChaCha20-Poly1305. Supports combined and detached modes, with optional AAD and nonce.

public static Span<byte> Encrypt(Span<byte> ciphertext, ReadOnlySpan<byte> plaintext, SecureMemory<byte> key, Span<byte> mac = default, ReadOnlySpan<byte> aad = default, ReadOnlySpan<byte> nonce = default)

Parameters

ciphertext Span<byte>

The buffer where the ciphertext will be written. It can be longer than needed.

plaintext ReadOnlySpan<byte>

The message to encrypt.

key SecureMemory<byte>

The secret encryption key (32 bytes).

mac Span<byte>

Optional. If provided, the encryption is done in detached mode and the MAC (16 bytes) is written here. Otherwise, combined mode is used.

aad ReadOnlySpan<byte>

Optional additional authenticated data. Not encrypted, but authenticated.

nonce ReadOnlySpan<byte>

Optional nonce (24 bytes). If not provided, a random nonce is generated and prepended.

Returns

Span<byte>

The span representing the full ciphertext, including MAC and possibly nonce.

Exceptions

ArgumentException

Thrown when buffer sizes are incorrect or parameters are invalid.

LibSodiumException

Thrown when encryption fails.

Encrypt(Span<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, Span<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Encrypts a message using XChaCha20-Poly1305. Supports combined and detached modes, with optional AAD and nonce.

public static Span<byte> Encrypt(Span<byte> ciphertext, ReadOnlySpan<byte> plaintext, ReadOnlySpan<byte> key, Span<byte> mac = default, ReadOnlySpan<byte> aad = default, ReadOnlySpan<byte> nonce = default)

Parameters

ciphertext Span<byte>

The buffer where the ciphertext will be written. It can be longer than needed.

plaintext ReadOnlySpan<byte>

The message to encrypt.

key ReadOnlySpan<byte>

The secret encryption key (32 bytes).

mac Span<byte>

Optional. If provided, the encryption is done in detached mode and the MAC (16 bytes) is written here. Otherwise, combined mode is used.

aad ReadOnlySpan<byte>

Optional additional authenticated data. Not encrypted, but authenticated.

nonce ReadOnlySpan<byte>

Optional nonce (24 bytes). If not provided, a random nonce is generated and prepended.

Returns

Span<byte>

The span representing the full ciphertext, including MAC and possibly nonce.

Exceptions

ArgumentException

Thrown when buffer sizes are incorrect or parameters are invalid.

LibSodiumException

Thrown when encryption fails.