Class MagmaMgm

Namespace

CryptoHives.Foundation.Security.Cryptography.Cipher

Assembly

CryptoHives.Foundation.Security.Cryptography.dll

Magma-MGM authenticated encryption: the Multilinear Galois Mode of RFC 9058 (R 1323565.1.026-2019) over GOST R 34.12-2015 Magma, as used by GOST TLS 1.3 (RFC 9367).

public sealed class MagmaMgm : IAeadCipher, IDisposable

Inheritance

object

MagmaMgm

Implements

IAeadCipher

IDisposable

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

Remarks

The nonce is 8 bytes with the most significant bit clear (a 63-bit ICN). The tag is 4 to 8 bytes, chosen by the length of the tag buffer passed to the span overloads; the byte[] overloads use an 8-byte tag. At least one of the plaintext and the associated data must be non-empty, and together they must stay below 2^32 bits (512 MiB).

Important: Never reuse a (key, nonce) pair.

Constructors

MagmaMgm(ReadOnlySpan<byte>)

Initializes a new instance of the MagmaMgm class.

public MagmaMgm(ReadOnlySpan<byte> key)

Parameters

key ReadOnlySpan<byte>

The 32-byte Magma key.

Exceptions

ArgumentException

The key has the wrong length.

Properties

AlgorithmName

Gets the algorithm name.

public 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

Create(ReadOnlySpan<byte>)

Creates a new Magma-MGM instance.

public static MagmaMgm Create(ReadOnlySpan<byte> key)

Parameters

key ReadOnlySpan<byte>

The 32-byte Magma key.

Returns

MagmaMgm

A new Magma-MGM instance.

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

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.