AsconAead128 Class

Definition

Namespace

Bodu.Security.Cryptography

Assembly

Bodu.Security.Cryptography.dll

Package

Bodu.Security.Cryptography 1.2.0

Source

AsconAead128.cs

Provides authenticated encryption with associated data (AEAD) using the Ascon-AEAD128 algorithm as defined in NIST SP 800-232. Accepts a 128-bit key and a 128-bit nonce and produces a 128-bit authentication tag. This class cannot be inherited.

public sealed class AsconAead128 : IAeadBlockCipherModeTransform, IAeadTransform, IDisposable

Inheritance

object

AsconAead128

Implements

IAeadBlockCipherModeTransform

IAeadTransform

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

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>)

AeadBlockCipherModeTransformExtensions.Decrypt(IAeadBlockCipherModeTransform, ReadOnlySpan<byte>)

AeadBlockCipherModeTransformExtensions.Decrypt(IAeadBlockCipherModeTransform, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

AeadBlockCipherModeTransformExtensions.DecryptDetached(IAeadBlockCipherModeTransform, ReadOnlySpan<byte>, AuthenticationTag, ReadOnlySpan<byte>)

AeadBlockCipherModeTransformExtensions.Encrypt(IAeadBlockCipherModeTransform, ReadOnlySpan<byte>)

AeadBlockCipherModeTransformExtensions.Encrypt(IAeadBlockCipherModeTransform, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

AeadBlockCipherModeTransformExtensions.EncryptDetached(IAeadBlockCipherModeTransform, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

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

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

Examples

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

// Most callers should reach for the AeadBlockCipherModeTransformExtensions helpers,
// which size the output buffer and return a single freshly allocated array.
using IAeadBlockCipherModeTransform enc = new AsconAead128(key, nonce);
byte[] sealed_ = enc.Encrypt(plaintext, associatedData: header);
using IAeadBlockCipherModeTransform dec = new AsconAead128(key, nonce);
byte[] recovered = dec.Decrypt(sealed_, associatedData: header);

Remarks

Ascon-AEAD128 is a permutation-based AEAD scheme built on the 320-bit ASCON sponge. It uses a 128-bit (16-byte) rate, Ascon-p12 for initialization and finalization, and Ascon-p8 during associated-data and ciphertext processing.

The algorithm proceeds through four phases:

1. Initialization: the state is loaded as [IV ‖ K₀ ‖ K₁ ‖ N₀ ‖ N₁], Ascon-p12 is applied, and the key is XORed into state words 3 and 4.
2. Associated-data processing: each 16-byte block is absorbed with Ascon-p8 between blocks. A domain-separation constant (XOR of 1 into state word 4) is always applied after the AD phase, even when AD is empty.
3. Encryption / decryption: plaintext or ciphertext is processed in 16-byte blocks, with Ascon-p8 applied between blocks. The final (possibly partial) block is absorbed without a trailing permutation.
4. Finalization: the key is injected into the state, Ascon-p12 is applied, and the 128-bit tag is extracted by XORing the key into state words 3 and 4.

Each instance is single-use. A new instance must be created for every message. Reusing a nonce under the same key completely breaks confidentiality and authenticity.

Call ProcessAssociatedData(ReadOnlySpan<byte>) before Encrypt(ReadOnlySpan<byte>, Span<byte>) or Decrypt(ReadOnlySpan<byte>, Span<byte>). Pass an empty span if there is no associated data.

Parameters at a glance.

• Key size: 128 bits (16 bytes).
• Nonce size: 128 bits (16 bytes), must be unique per key.
• Tag size: 128 bits (16 bytes).
• State: 320-bit sponge; rate: 16 bytes; permutation Ascon-p12 (init/finalize) + Ascon-p8 (absorb).
• Specification: NIST SP 800-232 (ASCON family).

When to choose Ascon-AEAD128. The right pick when NIST's lightweight-cryptography selection is required, or for resource-constrained targets (microcontrollers, IoT) where the Ascon permutation's small state and short round count are an advantage over GCM's GHASH multiplications. For general-purpose AEAD on commodity x86/ARM hardware GcmModeTransform remains faster thanks to AES-NI/PCLMULQDQ; for nonce-misuse resistance prefer GcmSivModeTransform or SivModeTransform. Unlike the AES-based AEAD modes, Ascon does not depend on a separate block cipher - pair it with the related AsconHash256 / AsconHashA256 hashes or AsconXof128 XOF when building a fully Ascon-based protocol.

Constructors

AsconAead128(byte[], byte[])

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

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

Parameters

key byte[]

The 128-bit (16-byte) secret key. The key is read during construction and retained internally as key words until the instance is disposed. Must not be null.

nonce byte[]

The 128-bit (16-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 Bodu.Security.Cryptography.AsconAead128.KeyBytes bytes, or nonce is not exactly Bodu.Security.Cryptography.AsconAead128.NonceBytes bytes.

AsconAead128(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

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

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

Parameters

key ReadOnlySpan<byte>

The 128-bit (16-byte) secret key.

nonce ReadOnlySpan<byte>

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

Exceptions

ArgumentException

key is not exactly Bodu.Security.Cryptography.AsconAead128.KeyBytes bytes, or nonce is not exactly Bodu.Security.Cryptography.AsconAead128.NonceBytes bytes.

Fields

KeySize

Length of the Ascon-AEAD128 key is 128 bits (16 bytes).

public const int KeySize = 128

Field Value

int

NonceSize

Length of the Ascon-AEAD128 nonce is 128 bits (16 bytes).

public const int NonceSize = 128

Field Value

int

Properties

TagSize

Gets the authentication-tag size, in bits.

public int TagSize { get; }

Property Value

int

The authentication-tag size, in bits.

Methods

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

Decrypts ciphertextWithTag and verifies the 16-byte authentication tag.

public int Decrypt(ReadOnlySpan<byte> ciphertextWithTag, Span<byte> output)

Parameters

ciphertextWithTag ReadOnlySpan<byte>

The ciphertext followed immediately by the 16-byte authentication tag. Must be at least Bodu.Security.Cryptography.AsconAead128.TagBytes bytes long.

output Span<byte>

Receives the decrypted plaintext. Must be at least ciphertextWithTag.Length - Bodu.Security.Cryptography.AsconAead128.TagBytes bytes long.

Returns

int

Bytes written: ciphertextWithTag.Length - Bodu.Security.Cryptography.AsconAead128.TagBytes.

Remarks

Authentication pattern: write-then-clear. Ascon-AEAD-128 streams plaintext into output as it processes the ciphertext because the duplex sponge derives the tag from the final state; the tag is then compared in constant time, and on mismatch ZeroMemory(Span<byte>) clears the plaintext-length region of output and the keyed sponge state is reset before CryptographicException is thrown - no plaintext is observable to the caller, and the rejected message's permutation state does not outlive the call.

Exceptions

ObjectDisposedException

The instance has been disposed.

InvalidOperationException

ProcessAssociatedData(ReadOnlySpan<byte>) has not been called.

ArgumentException

ciphertextWithTag is shorter than Bodu.Security.Cryptography.AsconAead128.TagBytes bytes, or output is too small.

CryptographicException

The authentication tag did not match.

Dispose()

Releases the resources used by this instance and clears retained key material and sponge state from memory.

public void Dispose()

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

Encrypts plaintext and appends the 16-byte authentication tag to output.

public int Encrypt(ReadOnlySpan<byte> plaintext, Span<byte> output)

Parameters

plaintext ReadOnlySpan<byte>

The data to encrypt.

output Span<byte>

Receives the ciphertext followed immediately by the 16-byte tag. Must be at least plaintext.Length + Bodu.Security.Cryptography.AsconAead128.TagBytes bytes long.

Returns

int

Total bytes written: plaintext.Length + Bodu.Security.Cryptography.AsconAead128.TagBytes.

Exceptions

ObjectDisposedException

The instance has been disposed.

InvalidOperationException

ProcessAssociatedData(ReadOnlySpan<byte>) has not been called.

ArgumentException

output is too small.

ProcessAssociatedData(ReadOnlySpan<byte>)

Absorbs associated data that will be authenticated but not encrypted.

public void ProcessAssociatedData(ReadOnlySpan<byte> associatedData)

Parameters

associatedData ReadOnlySpan<byte>

The bytes to authenticate. May be empty to indicate no associated data. Must be called exactly once before Encrypt(ReadOnlySpan<byte>, Span<byte>) or Decrypt(ReadOnlySpan<byte>, Span<byte>).

Exceptions

ObjectDisposedException

The instance has been disposed.

InvalidOperationException

This method has already been called on this instance.

Applies to

Product	Versions
.NET	8, 10

See Also

NIST SP 800-232 (ASCON)

IAeadBlockCipherModeTransform

AeadBlockCipherModeTransformExtensions