XChaCha20Poly1305 Class

Definition

Namespace

Bodu.Security.Cryptography

Assembly

Bodu.Security.Cryptography.dll

Package

Bodu.Security.Cryptography 1.2.0

Source

XChaCha20Poly1305.cs

Provides authenticated encryption with associated data (AEAD) using the extended-nonce XChaCha20-Poly1305 construction. Accepts a 256-bit key and a 192-bit nonce and produces a 128-bit authentication tag. This class cannot be inherited.

public sealed class XChaCha20Poly1305 : Poly1305AeadTransform, IStreamAeadTransform, IAeadTransform, IDisposable

Inheritance

object

Poly1305AeadTransform

XChaCha20Poly1305

Implements

IStreamAeadTransform

IAeadTransform

IDisposable

Inherited Members

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

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

Poly1305AeadTransform.Dispose()

Poly1305AeadTransform.TagSize

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

AeadTransformExtensions.Decrypt(IAeadTransform, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

AeadTransformExtensions.Encrypt(IAeadTransform, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Examples

using Bodu.Security.Cryptography;
using Bodu.Security.Cryptography.Extensions;

using var enc = new XChaCha20Poly1305(key, nonce);
byte[] sealed_ = enc.Encrypt(plaintext, associatedData: header); // ciphertext || tag
using var dec = new XChaCha20Poly1305(key, nonce);
byte[] recovered = dec.Decrypt(sealed_, associatedData: header);

Remarks

XChaCha20-Poly1305 composes the extended-nonce XChaCha20 stream cipher with the one-time Poly1305 MAC under the RFC 8439 AEAD framing, as specified by draft-irtf-cfrg-xchacha and implemented by libsodium's crypto_aead_xchacha20poly1305_ietf. A 256-bit subkey is derived from the key and the first 128 bits of the nonce via HChaCha20; the remaining 64 bits of the nonce, prefixed with four zero bytes, form the 96-bit ChaCha20 nonce. The counter-0 keystream block yields the one-time Poly1305 key, the message is encrypted from counter 1 onward, and the tag authenticates AAD ‖ pad16(AAD) ‖ ciphertext ‖ pad16(ciphertext) ‖ le64(|AAD|) ‖ le64(|ciphertext|).

The 192-bit nonce is large enough to be chosen at random per message without meaningful collision risk, which makes XChaCha20-Poly1305 the safer choice for protocols that cannot guarantee a unique 96-bit nonce - the gap left by the BCL's 96-bit-nonce ChaCha20Poly1305.

Each instance is single-use. A new instance must be created for every message. Reusing a nonce under the same key destroys confidentiality and authenticity. Associated data is passed directly to Encrypt(ReadOnlySpan<byte>, Span<byte>, ReadOnlySpan<byte>) or Decrypt(ReadOnlySpan<byte>, Span<byte>, ReadOnlySpan<byte>) and defaults to empty; the emitted wire format is ciphertext ‖ tag.

Key separation. Do not reuse a key across this construction, the raw XChaCha20 stream cipher, or a different AEAD construction unless an external protocol-level key-separation scheme (for example HKDF with distinct info labels) derives an independent key for each use.

Constructors

XChaCha20Poly1305(byte[], byte[])

Initializes a new instance of the XChaCha20Poly1305 class with the specified key and nonce.

public XChaCha20Poly1305(byte[] key, byte[] nonce)

Parameters

key byte[]

The 256-bit (32-byte) secret key. Must not be null.

nonce byte[]

The 192-bit (24-byte) nonce. Must be unique for every message encrypted under the same key. Must not be null.

Exceptions

ArgumentNullException

key or nonce is null.

ArgumentException

key is not exactly 32 bytes, or nonce is not exactly 24 bytes.

XChaCha20Poly1305(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Initializes a new instance of the XChaCha20Poly1305 class with the specified key and nonce spans.

public XChaCha20Poly1305(ReadOnlySpan<byte> key, ReadOnlySpan<byte> nonce)

Parameters

key ReadOnlySpan<byte>

The 256-bit (32-byte) secret key.

nonce ReadOnlySpan<byte>

The 192-bit (24-byte) nonce. Must be unique for every message encrypted under the same key.

Exceptions

ArgumentException

key is not exactly 32 bytes, or nonce is not exactly 24 bytes.

Fields

KeySize

Length of the XChaCha20-Poly1305 key is 256 bits (32 bytes).

public const int KeySize = 256

Field Value

int

NonceSize

Length of the XChaCha20-Poly1305 nonce is 192 bits (24 bytes).

public const int NonceSize = 192

Field Value

int

Methods

CreateEngine()

Creates the keystream engine for a single message, positioned at block counter 0.

protected override IStreamCipher CreateEngine()

Returns

IStreamCipher

A freshly constructed IStreamCipher bound to Key and Nonce.

Remarks

The caller owns the returned engine and disposes it after the message completes.

Applies to

Product	Versions
.NET	8, 10

See Also

draft-irtf-cfrg-xchacha - XChaCha: eXtended-nonce ChaCha and AEAD_XChaCha20_Poly1305

XChaCha20

Poly1305

IStreamAeadTransform