Class ChaCha20Poly1305

Namespace

CryptoHives.Foundation.Security.Cryptography.Cipher

Assembly

CryptoHives.Foundation.Security.Cryptography.dll

ChaCha20-Poly1305 authenticated encryption as specified in RFC 8439.

public sealed class ChaCha20Poly1305 : IAeadCipher, IDisposable

Inheritance

object

ChaCha20Poly1305

Implements

IAeadCipher

IDisposable

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

Remarks

ChaCha20-Poly1305 is an AEAD construction that combines ChaCha20 stream cipher with Poly1305 message authentication code. It is widely used in TLS 1.3, WireGuard, and other modern protocols.

Security properties:

• 256-bit security level
• 128-bit authentication tag
• Resistant to timing attacks
• High performance on all platforms

Important: Never reuse a (key, nonce) pair. Each encryption must use a unique 96-bit (12-byte) nonce.

Example usage:

using var aead = ChaCha20Poly1305.Create(key);
// Encrypt with associated data
byte[] ciphertext = aead.Encrypt(nonce, plaintext, associatedData);
// Decrypt and verify
byte[] plaintext = aead.Decrypt(nonce, ciphertext, associatedData);

Constructors

ChaCha20Poly1305(byte[])

Initializes a new instance of the ChaCha20Poly1305 class.

public ChaCha20Poly1305(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 (96 bits).

public const int NonceSizeBytesConst = 12

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 ChaCha20-Poly1305 instance.

public static ChaCha20Poly1305 Create(byte[] key)

Parameters

key byte[]

The 32-byte key.

Returns

ChaCha20Poly1305

A new ChaCha20-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.