Class AesGcm

Namespace

CryptoHives.Foundation.Security.Cryptography.Cipher

Assembly

CryptoHives.Foundation.Security.Cryptography.dll

AES-GCM (Galois/Counter Mode) authenticated encryption implementation.

public abstract class AesGcm : IAeadCipher, IDisposable

Inheritance

object

AesGcm

Implements

IAeadCipher

IDisposable

Derived

AesGcm128

AesGcm192

AesGcm256

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Remarks

AES-GCM provides authenticated encryption with associated data (AEAD). It is widely used in TLS 1.3, IPsec, and other security protocols.

Security properties:

• Confidentiality via AES-CTR mode
• Authenticity via GHASH universal hash
• Support for additional authenticated data (AAD)

Important: Never reuse a (key, nonce) pair. Each encryption must use a unique nonce. For random nonces, 96-bit (12-byte) nonces are recommended.

Example usage:

using var aesGcm = AesGcm256.Create(key);
// Encrypt
byte[] ciphertext = aesGcm.Encrypt(nonce, plaintext, associatedData);
// Decrypt
byte[] plaintext = aesGcm.Decrypt(nonce, ciphertext, associatedData);

Constructors

AesGcm(ReadOnlySpan<byte>)

Initializes a new instance of the AesGcm class.

protected AesGcm(ReadOnlySpan<byte> key)

Parameters

key ReadOnlySpan<byte>

The AES key (16, 24, or 32 bytes).

Properties

AlgorithmName

Gets the algorithm name.

public abstract string AlgorithmName { get; }

Property Value

string

KeySizeBytes

Gets the key size in bytes.

public int KeySizeBytes { get; }

Property Value

int

NonceSizeBytes

Gets the nonce size in bytes.

public int NonceSizeBytes { get; }

Property Value

int

TagSizeBytes

Gets the authentication tag size in bytes.

public int TagSizeBytes { get; }

Property Value

int

Methods

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

Decrypts the ciphertext (with appended tag) and verifies authenticity.

public byte[] Decrypt(ReadOnlySpan<byte> nonce, ReadOnlySpan<byte> ciphertextWithTag, ReadOnlySpan<byte> associatedData = default)

Parameters

nonce ReadOnlySpan<byte>

The nonce used during encryption.

ciphertextWithTag ReadOnlySpan<byte>

The ciphertext with appended authentication tag.

associatedData ReadOnlySpan<byte>

Additional authenticated data (must match encryption).

Returns

byte[]

The decrypted plaintext.

Exceptions

CryptographicException

Authentication failed - the data has been tampered with or the wrong key/nonce was used.

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

Decrypts the ciphertext and verifies the authentication tag.

public bool Decrypt(ReadOnlySpan<byte> nonce, ReadOnlySpan<byte> ciphertext, ReadOnlySpan<byte> tag, Span<byte> plaintext, ReadOnlySpan<byte> associatedData = default)

Parameters

nonce ReadOnlySpan<byte>

The nonce used during encryption.

ciphertext ReadOnlySpan<byte>

The encrypted data.

tag ReadOnlySpan<byte>

The authentication tag to verify.

plaintext Span<byte>

The output buffer for decrypted data (same size as ciphertext).

associatedData ReadOnlySpan<byte>

Additional authenticated data (must match encryption).

Returns

bool

True if decryption and authentication succeeded; false if authentication failed.

Exceptions

ArgumentException

nonce or tag is not the correct size, or plaintext buffer is too small.

ObjectDisposedException

Thrown when the instance has been disposed.

Dispose()

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

public void Dispose()

Dispose(bool)

Releases resources used by this instance.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

True if called from Dispose(), false if from finalizer.

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

Encrypts the plaintext and returns ciphertext with appended tag.

public byte[] Encrypt(ReadOnlySpan<byte> nonce, ReadOnlySpan<byte> plaintext, ReadOnlySpan<byte> associatedData = default)

Parameters

nonce ReadOnlySpan<byte>

The unique nonce for this encryption.

plaintext ReadOnlySpan<byte>

The data to encrypt.

associatedData ReadOnlySpan<byte>

Additional data to authenticate (optional).

Returns

byte[]

The ciphertext with authentication tag appended.

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

Encrypts the plaintext and computes the authentication tag.

public void Encrypt(ReadOnlySpan<byte> nonce, ReadOnlySpan<byte> plaintext, Span<byte> ciphertext, Span<byte> tag, ReadOnlySpan<byte> associatedData = default)

Parameters

nonce ReadOnlySpan<byte>

The unique nonce for this encryption.

plaintext ReadOnlySpan<byte>

The data to encrypt.

ciphertext Span<byte>

The output buffer for ciphertext (same size as plaintext).

tag Span<byte>

The output buffer for the authentication tag.

associatedData ReadOnlySpan<byte>

Additional data to authenticate (optional).

Exceptions

ArgumentException

nonce is not the correct size, or ciphertext or tag buffers are too small.

ObjectDisposedException

Thrown when the instance has been disposed.