IAeadBlockCipherModeTransform Interface

Definition

Namespace

Bodu.Security.Cryptography

Assembly

Bodu.Security.Cryptography.dll

Package

Bodu.Security.Cryptography 1.2.0

Source

IAeadBlockCipherModeTransform.cs

Represents an authenticated encryption with associated data (AEAD) block cipher mode transform that encrypts or decrypts data and produces or verifies an integrity tag.

public interface IAeadBlockCipherModeTransform : IAeadTransform, IDisposable

Inherited Members

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

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

IAeadTransform.TagSize

IDisposable.Dispose()

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

Remarks

Unlike IBlockCipherModeTransform, which only encrypts or decrypts, AEAD transforms combine confidentiality with data integrity. The caller supplies optional associated data (AAD) that is authenticated but not encrypted, plus plaintext or ciphertext to be transformed. The output includes an authentication tag that binds the ciphertext and AAD together.

Usage pattern for encryption:

transform.ProcessAssociatedData(aad);
int written = transform.Encrypt(plaintext, output); // output = ciphertext || tag

Usage pattern for decryption:

transform.ProcessAssociatedData(aad);
int written = transform.Decrypt(ciphertextWithTag, output); // throws if tag invalid

All implementations are stateful, not thread-safe, and single-use per message. A second call to Encrypt(ReadOnlySpan<byte>, Span<byte>) or Decrypt(ReadOnlySpan<byte>, Span<byte>) on the same instance - including after a tag-mismatch failure - throws InvalidOperationException. Construct a fresh transform for every message and dispose it when finished.

API surface. The library ships several implementations clustered by trade-off:

• Default high-throughput AEAD GcmModeTransform - single-pass, hardware-accelerated, fragile under nonce reuse.
• Constrained-environment AEAD CcmModeTransform - two-pass, no Galois-field arithmetic, used by Zigbee / Bluetooth Mesh.
• Two-pass alternativesEaxModeTransform - flexible nonce length, OMAC-based authentication.
• Misuse-resistant GcmSivModeTransform (RFC 8452) and SivModeTransform (RFC 5297) - nonce reuse only leaks message-equality.
• Single-pass without GCM's failure profileOcbModeTransform - RFC 7253, single-pass, graceful nonce-reuse failure.

Most callers should reach for the helper methods on AeadBlockCipherModeTransformExtensions instead of calling ProcessAssociatedData(ReadOnlySpan<byte>) + Encrypt(ReadOnlySpan<byte>, Span<byte>)/Decrypt(ReadOnlySpan<byte>, Span<byte>) directly - those wrappers size the output buffer correctly and return a single freshly allocated array.

API surface. The library ships several implementations clustered by trade-off:

• Default high-throughput AEAD GcmModeTransform - single-pass, hardware-accelerated, fragile under nonce reuse.
• Constrained-environment AEAD CcmModeTransform - two-pass, no Galois-field arithmetic, used by Zigbee / Bluetooth Mesh.
• Two-pass alternativesEaxModeTransform - flexible nonce length, OMAC-based authentication.
• Misuse-resistant GcmSivModeTransform (RFC 8452) and SivModeTransform (RFC 5297) - nonce reuse only leaks message-equality.
• Single-pass without GCM's failure profileOcbModeTransform - RFC 7253, single-pass, graceful nonce-reuse failure.

Most callers should reach for the helper methods on AeadBlockCipherModeTransformExtensions instead of calling ProcessAssociatedData(ReadOnlySpan<byte>) + Encrypt(ReadOnlySpan<byte>, Span<byte>)/Decrypt(ReadOnlySpan<byte>, Span<byte>) directly - those wrappers size the output buffer correctly and return a single freshly allocated array.

Methods

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

Decrypts ciphertextWithTag and verifies the authentication tag.

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

Parameters

ciphertextWithTag ReadOnlySpan<byte>

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

output Span<byte>

Receives the decrypted plaintext. Must be at least ciphertextWithTag.Length - (TagSize / 8) bytes long.

Returns

int

Bytes written: ciphertextWithTag.Length - (TagSize / 8).

Remarks

Authentication failure contract. All implementations honour the same observable guarantee on tag mismatch: CryptographicException is thrown and no plaintext is released to the caller. Implementations achieve this in one of two ways:

• Verify-before-release. The tag is compared in constant time before any plaintext byte is written to output. Used by GCM, CCM, EAX, and OCB.
• Write-then-clear. The candidate plaintext is streamed into output first because the algorithm's structure requires the transform to complete before the tag can be computed. The tag is then compared in constant time; on mismatch output is zeroed via ZeroMemory(Span<byte>) before the exception is thrown. Used by Ascon-AEAD-128 and GCM-SIV.

In both cases the API is strictly one-shot: a failed decryption invalidates the instance, and subsequent calls throw InvalidOperationException. Construct a fresh instance per message.

Exceptions

CryptographicException

The authentication tag did not match.

ArgumentException

ciphertextWithTag is shorter than TagSize / 8 bytes, or output is too small.

InvalidOperationException

The instance 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(ReadOnlySpan<byte>, Span<byte>)

Encrypts plaintext and appends the authentication tag to output.

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 TagSize / 8 byte tag. Must be at least plaintext.Length + (TagSize / 8) bytes long.

Returns

int

Total bytes written: plaintext.Length + (TagSize / 8).

Exceptions

ArgumentException

output is too small.

InvalidOperationException

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

ProcessAssociatedData(ReadOnlySpan<byte>)

Processes associated data (AAD) that will be authenticated but not encrypted. Must be called before Encrypt(ReadOnlySpan<byte>, Span<byte>) or Decrypt(ReadOnlySpan<byte>, Span<byte>).

void ProcessAssociatedData(ReadOnlySpan<byte> associatedData)

Parameters

associatedData ReadOnlySpan<byte>

The bytes to authenticate. May be empty to indicate no associated data.

Exceptions

InvalidOperationException

Associated data has already been processed on this instance, or the instance has already completed an Encrypt(ReadOnlySpan<byte>, Span<byte>) or Decrypt(ReadOnlySpan<byte>, Span<byte>) operation.

Explicit Interface Implementations

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

Bridges the construction-neutral Decrypt(ReadOnlySpan<byte>, Span<byte>, ReadOnlySpan<byte>) to the block-cipher AEAD shape by processing associatedData and then decrypting in a single call.

int IAeadTransform.Decrypt(ReadOnlySpan<byte> ciphertextWithTag, Span<byte> output, ReadOnlySpan<byte> associatedData)

Parameters

ciphertextWithTag ReadOnlySpan<byte>

The ciphertext followed by its authentication tag.

output Span<byte>

Receives the recovered plaintext.

associatedData ReadOnlySpan<byte>

The data that must match what was supplied at encryption time.

Returns

int

Bytes written.

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

Bridges the construction-neutral Encrypt(ReadOnlySpan<byte>, Span<byte>, ReadOnlySpan<byte>) to the block-cipher AEAD shape by processing associatedData and then encrypting in a single call.

int IAeadTransform.Encrypt(ReadOnlySpan<byte> plaintext, Span<byte> output, ReadOnlySpan<byte> associatedData)

Parameters

plaintext ReadOnlySpan<byte>

The data to encrypt.

output Span<byte>

Receives the ciphertext followed by the authentication tag.

associatedData ReadOnlySpan<byte>

The data authenticated but not encrypted.

Returns

int

Total bytes written.

Applies to

Product	Versions
.NET	8, 10

See Also

Using AEAD modes (guide with GCM, CCM, OCB3, SIV, and GCM-SIV examples)

AesBlockCipher

AeadBlockCipherModeTransformExtensions