Table of Contents

AeadBlockCipherModeTransformExtensions Class

Definition

Namespace
Bodu.Security.Cryptography.Extensions
Assembly
Bodu.Security.Cryptography.dll
Package
Bodu.Security.Cryptography 1.2.0
Source
AeadBlockCipherModeTransformExtensions.Detached.cs

Extends IAeadBlockCipherModeTransform with one-shot encrypt/decrypt overloads that handle the associated-data step, size the output buffer correctly, and return the ciphertext + tag (or recovered plaintext) as a single freshly allocated array.

public static class AeadBlockCipherModeTransformExtensions
Inheritance
AeadBlockCipherModeTransformExtensions
Inherited Members

Remarks

AEAD ("authenticated encryption with associated data") modes - GCM, CCM, EAX, GCM-SIV, AES-SIV, Ascon - encrypt confidential plaintext while simultaneously authenticating the ciphertext together with a separate stream of associated data that travels in the clear (packet headers, message metadata, …). The IAeadBlockCipherModeTransform contract gives callers maximum control: invoke ProcessAssociatedData(ReadOnlySpan<byte>), size the output buffer to plaintext.Length + (TagSize / 8) (or ciphertextWithTag.Length - (TagSize / 8)), call Encrypt(ReadOnlySpan<byte>, Span<byte>) or Decrypt(ReadOnlySpan<byte>, Span<byte>), and interpret the return value. This class collapses that fixed sequence into a single call that returns a correctly sized array, matching the shape of AesGcm.Encrypt / AesGcm.Decrypt in the BCL but parameterized over any AEAD transform implementation.

The API surface is symmetric and intentionally small:

  • Encrypt(transform, plaintext) One-shot encrypt with no associated data - equivalent to passing Empty.
  • Encrypt(transform, plaintext, associatedData) One-shot encrypt with associated data; returns ciphertext concatenated with the TagSize / 8 byte authentication tag.
  • Decrypt(transform, ciphertextWithTag)One-shot decrypt with no associated data; throws on tag mismatch.
  • Decrypt(transform, ciphertextWithTag, associatedData) One-shot decrypt and tag-verify; returns the recovered plaintext, or throws CryptographicException on a failed tag check.

AEAD transforms are stateful and single-use within a message: instantiate a new transform per message, call exactly one of these helpers, and dispose. The associated-data argument must match byte-for-byte between the encrypt and decrypt calls - even a single-bit difference will cause the tag check to fail. Tag verification is constant-time inside the transform implementation, so timing leaks are not a concern. Output arrays are always sized exactly: plaintext.Length + (TagSize / 8) on encrypt, ciphertextWithTag.Length - (TagSize / 8) on decrypt. 

using System.Security.Cryptography;
using System.Text;
using Bodu.Security.Cryptography;
using Bodu.Security.Cryptography.Extensions;

byte[] key = RandomNumberGenerator.GetBytes(32);
byte[] nonce = RandomNumberGenerator.GetBytes(12);
byte[] header = Encoding.UTF8.GetBytes("v=1;msg=42");

// 1. Encrypt with associated data; receive ciphertext + tag in a single buffer.
using IAeadBlockCipherModeTransform enc = new GcmModeTransform(key, nonce);
byte[] sealed_ = enc.Encrypt(plaintext, associatedData: header);

// 2. Decrypt and verify in one call. A tampered tag or header throws CryptographicException.
using IAeadBlockCipherModeTransform dec = new GcmModeTransform(key, nonce);
byte[] recovered = dec.Decrypt(sealed_, associatedData: header);

// 3. Same shape with a different mode - Ascon, EAX, GCM-SIV all interchange behind IAeadBlockCipherModeTransform.
using IAeadBlockCipherModeTransform enc2 = new AsconAead128(key, nonce);
byte[] sealedAscon = enc2.Encrypt(plaintext);

Methods

Decrypt(IAeadBlockCipherModeTransform, ReadOnlySpan<byte>)

Verifies ciphertextWithTag with an empty associated-data stream, decrypts it, and returns the recovered plaintext.

public static byte[] Decrypt(this IAeadBlockCipherModeTransform transform, ReadOnlySpan<byte> ciphertextWithTag)

Parameters

transform IAeadBlockCipherModeTransform

The AEAD transform. Must not be null.

ciphertextWithTag ReadOnlySpan<byte>

The ciphertext followed immediately by the TagSize / 8 byte tag.

Returns

byte[]

A newly allocated byte array containing the recovered plaintext.

Exceptions

ArgumentNullException

transform is null.

CryptographicException

The authentication tag did not verify.

InvalidOperationException

The transform has already encrypted or decrypted a message, including after a previous tag-mismatch failure. AEAD transforms are single-use per message - construct a fresh instance.

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

Verifies ciphertextWithTag against associatedData, decrypts the ciphertext, and returns the recovered plaintext.

public static byte[] Decrypt(this IAeadBlockCipherModeTransform transform, ReadOnlySpan<byte> ciphertextWithTag, ReadOnlySpan<byte> associatedData)

Parameters

transform IAeadBlockCipherModeTransform

The AEAD transform. Must not be null.

ciphertextWithTag ReadOnlySpan<byte>

The ciphertext followed immediately by the TagSize / 8 byte tag. Must be at least transform.TagSize / 8 bytes long.

associatedData ReadOnlySpan<byte>

The data authenticated alongside the ciphertext. Must match what was supplied at encryption time.

Returns

byte[]

A newly allocated byte array of length ciphertextWithTag.Length - (transform.TagSize / 8) containing the recovered plaintext.

Exceptions

ArgumentNullException

transform is null.

ArgumentException

ciphertextWithTag is shorter than transform.TagSize / 8 bytes.

CryptographicException

The authentication tag did not verify. The returned buffer is not written in this case.

InvalidOperationException

The transform has already encrypted or decrypted a message, including after a previous tag-mismatch failure. AEAD transforms are single-use per message - construct a fresh instance.

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

Verifies the detached tag over ciphertext and associatedData, decrypts the ciphertext, and returns the recovered plaintext.

public static byte[] DecryptDetached(this IAeadBlockCipherModeTransform transform, ReadOnlySpan<byte> ciphertext, AuthenticationTag tag, ReadOnlySpan<byte> associatedData = default)

Parameters

transform IAeadBlockCipherModeTransform

The AEAD transform. Must not be null.

ciphertext ReadOnlySpan<byte>

The ciphertext, without a trailing tag.

tag AuthenticationTag

The detached authentication tag produced at encryption time.

associatedData ReadOnlySpan<byte>

The data authenticated alongside the ciphertext. Must match what was supplied at encryption time.

Returns

byte[]

A newly allocated byte array of the same length as ciphertext.

Exceptions

ArgumentNullException

transform is null.

ArgumentException

tag is not TagSize / 8 bytes long.

CryptographicException

The authentication tag did not verify.

InvalidOperationException

The transform has already encrypted or decrypted a message, including after a previous tag-mismatch failure. AEAD transforms are single-use per message - construct a fresh instance.

Encrypt(IAeadBlockCipherModeTransform, ReadOnlySpan<byte>)

Encrypts plaintext with an empty associated-data stream and returns a new byte array containing the ciphertext concatenated with the authentication tag.

public static byte[] Encrypt(this IAeadBlockCipherModeTransform transform, ReadOnlySpan<byte> plaintext)

Parameters

transform IAeadBlockCipherModeTransform

The AEAD transform. Must not be null.

plaintext ReadOnlySpan<byte>

The data to encrypt.

Returns

byte[]

A newly allocated byte array of length plaintext.Length + (transform.TagSize / 8).

Exceptions

ArgumentNullException

transform is null.

InvalidOperationException

The transform has already encrypted or decrypted a message. AEAD transforms are single-use per message - construct a fresh instance.

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

Encrypts plaintext and returns a new byte array containing the ciphertext concatenated with the authentication tag.

public static byte[] Encrypt(this IAeadBlockCipherModeTransform transform, ReadOnlySpan<byte> plaintext, ReadOnlySpan<byte> associatedData)

Parameters

transform IAeadBlockCipherModeTransform

The AEAD transform. Must not be null.

plaintext ReadOnlySpan<byte>

The data to encrypt.

associatedData ReadOnlySpan<byte>

The data to authenticate but not encrypt. May be empty when no associated data is required.

Returns

byte[]

A newly allocated byte array of length plaintext.Length + (transform.TagSize / 8), containing the ciphertext followed by the TagSize / 8 byte tag.

Exceptions

ArgumentNullException

transform is null.

InvalidOperationException

The transform has already had its associated data processed or its plaintext / ciphertext consumed.

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

Encrypts plaintext and returns the ciphertext and the authentication tag as separate values (detached-tag layout).

public static (byte[] Ciphertext, AuthenticationTag Tag) EncryptDetached(this IAeadBlockCipherModeTransform transform, ReadOnlySpan<byte> plaintext, ReadOnlySpan<byte> associatedData = default)

Parameters

transform IAeadBlockCipherModeTransform

The AEAD transform. Must not be null.

plaintext ReadOnlySpan<byte>

The data to encrypt.

associatedData ReadOnlySpan<byte>

The data to authenticate but not encrypt. May be empty when no associated data is required.

Returns

(byte[] Ciphertext, AuthenticationTag Tag)

A tuple of the newly allocated ciphertext (the same length as plaintext) and the AuthenticationTag of TagSize / 8 bytes.

Exceptions

ArgumentNullException

transform is null.

InvalidOperationException

The transform has already encrypted or decrypted a message. AEAD transforms are single-use per message - construct a fresh instance.

Applies to

ProductVersions
.NET8, 10

See Also

Using AEAD modes (guide with full encrypt / decrypt examples)