Table of Contents

AuthenticationTag Struct

Definition

Namespace
Bodu.Security.Cryptography
Assembly
Bodu.Security.Cryptography.dll
Package
Bodu.Security.Cryptography 1.2.0
Source
AuthenticationTag.cs

Represents the authentication tag produced by an authenticated-encryption (AEAD) operation.

public readonly struct AuthenticationTag : IEquatable<AuthenticationTag>
Implements
Inherited Members
Extension Methods

Examples

// Capture the tag emitted by an AEAD encryption and store or transmit it with the ciphertext.
AuthenticationTag tag = AuthenticationTag.FromBytes(producedTag);

// On the decrypt side, verify the recomputed tag in fixed time before trusting the plaintext.
if (!tag.FixedTimeEquals(recomputedTag))
    throw new CryptographicException("Authentication failed; the message was altered.");

Remarks

An authentication tag proves that ciphertext and associated data were produced under a specific key and have not been modified. Using a dedicated type keeps tags from being confused with nonces, keys, or digests in APIs that would otherwise accept several look-alike byte buffers.

AuthenticationTag carries its bytes by defensive copy, and the default instance ( default(AuthenticationTag)) is the empty value: Length is 0 and IsEmpty is true.

Tag verification is security-critical: always compare tags with FixedTimeEquals(AuthenticationTag) (or the span overload), never with Equals(AuthenticationTag), so an attacker cannot learn the position of the first mismatching byte from the comparison time.

Properties

IsEmpty

Gets a value indicating whether the tag is empty.

public bool IsEmpty { get; }

Property Value

bool

true if the tag contains no bytes; otherwise, false.

Length

Gets the number of bytes in the tag.

public int Length { get; }

Property Value

int

The tag length in bytes, or 0 for the empty value.

Methods

AsSpan()

Returns a read-only view over the tag bytes.

public ReadOnlySpan<byte> AsSpan()

Returns

ReadOnlySpan<byte>

A read-only span over the value; empty for the empty value.

Equals(AuthenticationTag)

Determines whether this tag equals another.

public bool Equals(AuthenticationTag other)

Parameters

other AuthenticationTag

The tag to compare against.

Returns

bool

true if both tags contain identical bytes; otherwise, false.

Remarks

The byte comparison is constant-time in content - it runs through FixedTimeEquals(ReadOnlySpan<byte>, ReadOnlySpan<byte>), so its duration depends only on the operand length, not on where the bytes first differ. A length mismatch returns false immediately (the length is not secret). The span-based FixedTimeEquals(ReadOnlySpan<byte>) overload remains available for verifying a received tag against a raw buffer.

Equals(object?)

Determines whether this tag equals the specified object.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare against.

Returns

bool

true if obj is an AuthenticationTag with identical bytes; otherwise, false.

FixedTimeEquals(AuthenticationTag)

Compares this tag to another in fixed time.

public bool FixedTimeEquals(AuthenticationTag other)

Parameters

other AuthenticationTag

The tag to compare against.

Returns

bool

true if both tags have the same length and identical bytes; otherwise, false.

Remarks

Built on FixedTimeEquals(ReadOnlySpan<byte>, ReadOnlySpan<byte>): the comparison time depends only on the length of the operands, not on their content. A length mismatch returns false immediately, so the lengths themselves are not concealed.

FixedTimeEquals(ReadOnlySpan<byte>)

Compares this tag to a raw byte sequence in fixed time.

public bool FixedTimeEquals(ReadOnlySpan<byte> other)

Parameters

other ReadOnlySpan<byte>

The bytes to compare against, typically the tag region of a transform's output buffer.

Returns

bool

true if other has the same length and identical bytes; otherwise, false.

FromBytes(ReadOnlySpan<byte>)

Creates an AuthenticationTag from the provided bytes.

public static AuthenticationTag FromBytes(ReadOnlySpan<byte> value)

Parameters

value ReadOnlySpan<byte>

The tag bytes to copy. An empty span yields the empty value.

Returns

AuthenticationTag

A new AuthenticationTag containing a defensive copy of value.

GetHashCode()

Returns a hash code computed over the tag bytes.

public override int GetHashCode()

Returns

int

A hash code consistent with Equals(AuthenticationTag).

ToArray()

Copies the tag bytes into a new array.

public byte[] ToArray()

Returns

byte[]

A new array containing the tag bytes; an empty array for the empty value.

ToString()

Returns the lowercase hexadecimal representation of the tag.

public override string ToString()

Returns

string

The tag bytes as lowercase hexadecimal text; Empty for the empty value.

Remarks

Authentication tags travel with the ciphertext and are not secrets, so the content is intentionally included in the string representation.

Operators

operator ==(AuthenticationTag, AuthenticationTag)

Determines whether two tags are equal.

public static bool operator ==(AuthenticationTag left, AuthenticationTag right)

Parameters

left AuthenticationTag

The first tag.

right AuthenticationTag

The second tag.

Returns

bool

true if the tags contain identical bytes; otherwise, false.

operator !=(AuthenticationTag, AuthenticationTag)

Determines whether two tags are not equal.

public static bool operator !=(AuthenticationTag left, AuthenticationTag right)

Parameters

left AuthenticationTag

The first tag.

right AuthenticationTag

The second tag.

Returns

bool

true if the tags differ; otherwise, false.

Applies to

ProductVersions
.NET8, 10