Class AesGmac

Namespace

CryptoHives.Foundation.Security.Cryptography.Mac

Assembly

CryptoHives.Foundation.Security.Cryptography.dll

Computes AES-GMAC (Galois Message Authentication Code) as defined in NIST SP 800-38D, Section 4.

public sealed class AesGmac : IDisposable

Inheritance

object

AesGmac

Implements

IDisposable

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

Examples

byte[] key = new byte[16]; // AES-128 key
byte[] nonce = new byte[12]; // unique 96-bit nonce
byte[] data = Encoding.UTF8.GetBytes("authenticated data");

using var gmac = AesGmac.Create(key);
byte[] tag = gmac.ComputeTag(nonce, data);

Remarks

GMAC is a special case of GCM where the plaintext is empty. It produces a 128-bit (16-byte) authentication tag over the associated data (AAD).

This implementation wraps the CryptoHives AES-GCM implementation, benefiting from its hardware-accelerated AES-NI and PCLMULQDQ GHASH when available.

Important: GMAC requires a unique nonce for every invocation with the same key. Nonce reuse completely compromises authenticity. The nonce is 12 bytes (96 bits).

Constructors

AesGmac(ReadOnlySpan<byte>)

Initializes a new instance of the AesGmac class.

public AesGmac(ReadOnlySpan<byte> key)

Parameters

key ReadOnlySpan<byte>

The secret key. Must be 16, 24, or 32 bytes.

Exceptions

ArgumentException

The key length is invalid.

Fields

NonceSizeBytes

The required nonce size in bytes.

public const int NonceSizeBytes = 12

Field Value

int

TagSizeBytes

The MAC output size in bytes.

public const int TagSizeBytes = 16

Field Value

int

Properties

AlgorithmName

Gets the name of the MAC algorithm.

public string AlgorithmName { get; }

Property Value

string

MacSize

Gets the MAC output size in bytes.

public int MacSize { get; }

Property Value

int

Methods

ComputeTag(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Computes the GMAC authentication tag for the specified nonce and data.

public byte[] ComputeTag(ReadOnlySpan<byte> nonce, ReadOnlySpan<byte> associatedData)

Parameters

nonce ReadOnlySpan<byte>

The 12-byte nonce. Must be unique per invocation.

associatedData ReadOnlySpan<byte>

The data to authenticate.

Returns

byte[]

The 16-byte authentication tag.

Exceptions

ArgumentException

nonce is not 12 bytes.

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

Computes the GMAC authentication tag for the specified nonce and data.

public void ComputeTag(ReadOnlySpan<byte> nonce, ReadOnlySpan<byte> associatedData, Span<byte> tag)

Parameters

nonce ReadOnlySpan<byte>

The 12-byte nonce. Must be unique per invocation.

associatedData ReadOnlySpan<byte>

The data to authenticate.

tag Span<byte>

The buffer to receive the 16-byte authentication tag.

Exceptions

ArgumentException

nonce is not 12 bytes, or tag is too small.

ObjectDisposedException

Thrown when the instance has been disposed.

Create(byte[])

Creates a new instance of the AesGmac class.

public static AesGmac Create(byte[] key)

Parameters

key byte[]

The secret key.

Returns

AesGmac

A new AES-GMAC instance.

Create(ReadOnlySpan<byte>)

Creates a new instance of the AesGmac class.

public static AesGmac Create(ReadOnlySpan<byte> key)

Parameters

key ReadOnlySpan<byte>

The secret key.

Returns

AesGmac

A new AES-GMAC instance.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

VerifyTag(ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Verifies a GMAC authentication tag.

public bool VerifyTag(ReadOnlySpan<byte> nonce, ReadOnlySpan<byte> associatedData, ReadOnlySpan<byte> expectedTag)

Parameters

nonce ReadOnlySpan<byte>

The 12-byte nonce used to produce the tag.

associatedData ReadOnlySpan<byte>

The data to verify.

expectedTag ReadOnlySpan<byte>

The expected authentication tag.

Returns

bool

True if the tag is valid; otherwise false.