Class XChaCha20Poly1305

Namespace

CryptoHives.Foundation.Security.Cryptography.Cipher

Assembly

CryptoHives.Foundation.Security.Cryptography.dll

XChaCha20-Poly1305 authenticated encryption with extended nonce.

public sealed class XChaCha20Poly1305 : IAeadCipher, IDisposable

Inheritance

object

XChaCha20Poly1305

Implements

IAeadCipher

IDisposable

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

Remarks

XChaCha20-Poly1305 extends ChaCha20-Poly1305 with a 192-bit (24-byte) nonce, providing better resistance to nonce misuse. It uses HChaCha20 to derive a subkey from the key and first 16 bytes of the nonce, then uses standard ChaCha20-Poly1305 with the subkey and remaining 8 bytes of the nonce.

Specification: draft-irtf-cfrg-xchacha-03

Security properties:

• 256-bit security level
• 192-bit nonce (safe for random nonces)
• 128-bit authentication tag
• Resistant to timing attacks

Nonce generation: The 24-byte nonce can be randomly generated for each message. The probability of collision is negligible (2^-32 after 2^80 messages).

Example usage:

using var aead = XChaCha20Poly1305.Create(key);
// Generate random 24-byte nonce
byte[] nonce = new byte[24];
RandomNumberGenerator.Fill(nonce);
// Encrypt with associated data
byte[] ciphertext = aead.Encrypt(nonce, plaintext, associatedData);
// Decrypt and verify
byte[] plaintext = aead.Decrypt(nonce, ciphertext, associatedData);

Constructors

XChaCha20Poly1305(byte[])

Initializes a new instance of the XChaCha20Poly1305 class.

public XChaCha20Poly1305(byte[] key)

Parameters

key byte[]

The 32-byte key.

Fields

KeySizeBytesConst

Key size in bytes (256 bits).

public const int KeySizeBytesConst = 32

Field Value

int

NonceSizeBytesConst

Nonce size in bytes (192 bits = 24 bytes).

public const int NonceSizeBytesConst = 24

Field Value

int

TagSizeBytesConst

Tag size in bytes (128 bits).

public const int TagSizeBytesConst = 16

Field Value

int

Properties

AlgorithmName

Gets the algorithm name.

public string AlgorithmName { get; }

Property Value

string

KeySizeBytes

Gets the key size in bytes.

public int KeySizeBytes { get; }

Property Value

int

NonceSizeBytes

Gets the nonce size in bytes.

public int NonceSizeBytes { get; }

Property Value

int

TagSizeBytes

Gets the authentication tag size in bytes.

public int TagSizeBytes { get; }

Property Value

int

Methods

Create(byte[])

Creates a new XChaCha20-Poly1305 instance.

public static XChaCha20Poly1305 Create(byte[] key)

Parameters

key byte[]

The 32-byte key.

Returns

XChaCha20Poly1305

A new XChaCha20-Poly1305 instance.

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

Decrypts the ciphertext (with appended tag) and verifies authenticity.

public byte[] Decrypt(ReadOnlySpan<byte> nonce, ReadOnlySpan<byte> ciphertextWithTag, ReadOnlySpan<byte> associatedData = default)

Parameters

nonce ReadOnlySpan<byte>

The nonce used during encryption.

ciphertextWithTag ReadOnlySpan<byte>

The ciphertext with appended authentication tag.

associatedData ReadOnlySpan<byte>

Additional authenticated data (must match encryption).

Returns

byte[]

The decrypted plaintext.

Exceptions

CryptographicException

Authentication failed - the data has been tampered with or the wrong key/nonce was used.

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

Decrypts the ciphertext and verifies the authentication tag.

public bool Decrypt(ReadOnlySpan<byte> nonce, ReadOnlySpan<byte> ciphertext, ReadOnlySpan<byte> tag, Span<byte> plaintext, ReadOnlySpan<byte> associatedData = default)

Parameters

nonce ReadOnlySpan<byte>

The nonce used during encryption.

ciphertext ReadOnlySpan<byte>

The encrypted data.

tag ReadOnlySpan<byte>

The authentication tag to verify.

plaintext Span<byte>

The output buffer for decrypted data (same size as ciphertext).

associatedData ReadOnlySpan<byte>

Additional authenticated data (must match encryption).

Returns

bool

True if decryption and authentication succeeded; false if authentication failed.

Exceptions

ArgumentException

nonce or tag is not the correct size, or plaintext buffer is too small.

ObjectDisposedException

Thrown when the instance has been disposed.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

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

Encrypts the plaintext and returns ciphertext with appended tag.

public byte[] Encrypt(ReadOnlySpan<byte> nonce, ReadOnlySpan<byte> plaintext, ReadOnlySpan<byte> associatedData = default)

Parameters

nonce ReadOnlySpan<byte>

The unique nonce for this encryption.

plaintext ReadOnlySpan<byte>

The data to encrypt.

associatedData ReadOnlySpan<byte>

Additional data to authenticate (optional).

Returns

byte[]

The ciphertext with authentication tag appended.

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

Encrypts the plaintext and computes the authentication tag.

public void Encrypt(ReadOnlySpan<byte> nonce, ReadOnlySpan<byte> plaintext, Span<byte> ciphertext, Span<byte> tag, ReadOnlySpan<byte> associatedData = default)

Parameters

nonce ReadOnlySpan<byte>

The unique nonce for this encryption.

plaintext ReadOnlySpan<byte>

The data to encrypt.

ciphertext Span<byte>

The output buffer for ciphertext (same size as plaintext).

tag Span<byte>

The output buffer for the authentication tag.

associatedData ReadOnlySpan<byte>

Additional data to authenticate (optional).

Exceptions

ArgumentException

nonce is not the correct size, or ciphertext or tag buffers are too small.

ObjectDisposedException

Thrown when the instance has been disposed.