Class AesCmac

Namespace

Dorssel.Security.Cryptography

Assembly

Dorssel.Security.Cryptography.AesExtra.dll

Computes a Cipher-based Message Authentication Code (CMAC) by using the symmetric key AES block cipher.

public sealed class AesCmac : KeyedHashAlgorithm, ICryptoTransform, IDisposable

Inheritance

object

HashAlgorithm

KeyedHashAlgorithm

AesCmac

Implements

ICryptoTransform

IDisposable

Inherited Members

HashAlgorithm.Clear()

HashAlgorithm.ComputeHash(byte[])

HashAlgorithm.ComputeHash(byte[], int, int)

HashAlgorithm.ComputeHash(Stream)

HashAlgorithm.ComputeHashAsync(Stream, CancellationToken)

HashAlgorithm.Dispose()

HashAlgorithm.TransformBlock(byte[], int, int, byte[], int)

HashAlgorithm.TransformFinalBlock(byte[], int, int)

HashAlgorithm.TryComputeHash(ReadOnlySpan<byte>, Span<byte>, out int)

HashAlgorithm.CanReuseTransform

HashAlgorithm.CanTransformMultipleBlocks

HashAlgorithm.Hash

HashAlgorithm.HashSize

HashAlgorithm.InputBlockSize

HashAlgorithm.OutputBlockSize

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

AesCmac()

Initializes a new instance of the AesCmac class with a randomly generated 256-bit key.

public AesCmac()

AesCmac(byte[])

Initializes a new instance of the AesCmac class with the specified key data.

public AesCmac(byte[] key)

Parameters

key byte[]

The secret key for AES-CMAC algorithm.

Exceptions

ArgumentNullException

key is null.

CryptographicException

The key length is other than 16, 24, or 32 bytes (128, 192, or 256 bits).

AesCmac(int)

Initializes a new instance of the AesCmac class with a randomly generated key.

public AesCmac(int keySize)

Parameters

keySize int

The size, in bits, of the randomly generated key.

Exceptions

CryptographicException

keySize is other than 128, 192, or 256 bits.

AesCmac(ReadOnlySpan<byte>)

Initializes a new instance of the AesCmac class with the specified key data.

public AesCmac(ReadOnlySpan<byte> key)

Parameters

key ReadOnlySpan<byte>

The secret key for AES-CMAC algorithm.

Exceptions

CryptographicException

The key length is other than 16, 24, or 32 bytes (128, 192, or 256 bits).

Properties

Key

Gets or sets the key to use in the hash algorithm.

public override byte[] Key { get; set; }

Property Value

byte[]

The key to use in the hash algorithm.

Exceptions

CryptographicException

An attempt was made to change the Key property after hashing has begun.

ArgumentNullException

key is null.

CryptographicException

The key length is other than 16, 24, or 32 bytes (128, 192, or 256 bits).

ObjectDisposedException

The AesCmac instance has been disposed.

InvalidOperationException

An attempt was made to change the Key during a computation.

Methods

Create()

Creates an instance of the default implementation of a keyed hash algorithm.

[Obsolete("Use one of the constructors instead.")]
public static AesCmac Create()

Returns

AesCmac

A new AesCmac instance.

Create(string)

Creates an instance of the specified implementation of a keyed hash algorithm.

[Obsolete("Cryptographic factory methods accepting an algorithm name are obsolete. Use the parameterless Create factory method on the algorithm type instead.")]
public static AesCmac? Create(string algorithmName)

Parameters

algorithmName string

Returns

AesCmac

A new instance of the specified keyed hash algorithm.

Exceptions

PlatformNotSupportedException

.NET Core 2.0 - 3.1 and .NET 5 and later: In all cases.

Dispose(bool)

Releases the unmanaged resources used by the KeyedHashAlgorithm and optionally releases the managed resources.

protected override void Dispose(bool disposing)

Parameters

disposing bool

true to release both managed and unmanaged resources; false to release only unmanaged resources.

HashCore(byte[], int, int)

When overridden in a derived class, routes data written to the object into the hash algorithm for computing the hash.

protected override void HashCore(byte[] array, int ibStart, int cbSize)

Parameters

array byte[]

The input to compute the hash code for.

ibStart int

The offset into the byte array from which to begin using data.

cbSize int

The number of bytes in the byte array to use as data.

HashCore(ReadOnlySpan<byte>)

Routes data written to the object into the hash algorithm for computing the hash.

protected override void HashCore(ReadOnlySpan<byte> source)

Parameters

source ReadOnlySpan<byte>

The input to compute the hash code for.

HashData(byte[], byte[])

Computes the CMAC of data using the AES-CMAC algorithm.

public static byte[] HashData(byte[] key, byte[] source)

Parameters

key byte[]

The CMAC key.

source byte[]

The data to CMAC.

Returns

byte[]

The CMAC of the data.

Exceptions

ArgumentNullException

key is null.

CryptographicException

The key length is other than 16, 24, or 32 bytes (128, 192, or 256 bits).

ArgumentNullException

source is null.

HashData(byte[], Stream)

Computes the CMAC of a stream using the AES-CMAC algorithm.

public static byte[] HashData(byte[] key, Stream source)

Parameters

key byte[]

The CMAC key.

source Stream

The stream to CMAC.

Returns

byte[]

The CMAC of the data.

Exceptions

ArgumentNullException

key is null.

CryptographicException

The key length is other than 16, 24, or 32 bytes (128, 192, or 256 bits).

ArgumentNullException

source is null.

ArgumentException

source does not support reading.

HashData(ReadOnlySpan<byte>, Stream)

Computes the CMAC of a stream using the AES-CMAC algorithm.

public static byte[] HashData(ReadOnlySpan<byte> key, Stream source)

Parameters

key ReadOnlySpan<byte>

The CMAC key.

source Stream

The stream to CMAC.

Returns

byte[]

The CMAC of the data.

Exceptions

CryptographicException

The key length is other than 16, 24, or 32 bytes (128, 192, or 256 bits).

ArgumentNullException

source is null.

ArgumentException

source does not support reading.

HashData(ReadOnlySpan<byte>, Stream, Span<byte>)

Computes the CMAC of a stream using the AES-CMAC algorithm.

public static int HashData(ReadOnlySpan<byte> key, Stream source, Span<byte> destination)

Parameters

key ReadOnlySpan<byte>

The CMAC key.

source Stream

The stream to CMAC.

destination Span<byte>

The buffer to receive the CMAC value.

Returns

int

The total number of bytes written to destination.

Exceptions

CryptographicException

The key length is other than 16, 24, or 32 bytes (128, 192, or 256 bits).

ArgumentNullException

source is null.

ArgumentException

source does not support reading.

ArgumentException

The buffer in destination is too small to hold the calculated CMAC. The AES-CMAC algorithm always produces a 128-bit CMAC, or 16 bytes.

HashData(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Computes the CMAC of data using the AES-CMAC algorithm.

public static byte[] HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source)

Parameters

key ReadOnlySpan<byte>

The CMAC key.

source ReadOnlySpan<byte>

The data to CMAC.

Returns

byte[]

The CMAC of the data.

Exceptions

CryptographicException

The key length is other than 16, 24, or 32 bytes (128, 192, or 256 bits).

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

Computes the CMAC of data using the AES-CMAC algorithm.

public static int HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination)

Parameters

key ReadOnlySpan<byte>

The CMAC key.

source ReadOnlySpan<byte>

The data to CMAC.

destination Span<byte>

The buffer to receive the CMAC value.

Returns

int

The total number of bytes written to destination.

Exceptions

CryptographicException

The key length is other than 16, 24, or 32 bytes (128, 192, or 256 bits).

ArgumentException

The buffer in destination is too small to hold the calculated CMAC. The AES-CMAC algorithm always produces a 128-bit CMAC, or 16 bytes.

HashDataAsync(byte[], Stream, CancellationToken)

Asynchronously computes the CMAC of a stream using the AES-CMAC algorithm.

public static ValueTask<byte[]> HashDataAsync(byte[] key, Stream source, CancellationToken cancellationToken = default)

Parameters

key byte[]

The CMAC key.

source Stream

The stream to CMAC.

cancellationToken CancellationToken

The token to monitor for cancellation requests. The default value is None.

Returns

ValueTask<byte[]>

The HMAC of the data.

Remarks

This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as ArgumentException, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by HashData(byte[], Stream).

Exceptions

ArgumentNullException

key is null.

CryptographicException

The key length is other than 16, 24, or 32 bytes (128, 192, or 256 bits).

ArgumentNullException

source is null.

ArgumentException

source does not support reading.

OperationCanceledException

The cancellation token was canceled. This exception is stored into the returned task.

HashDataAsync(ReadOnlyMemory<byte>, Stream, Memory<byte>, CancellationToken)

Asynchronously computes the CMAC of a stream using the AES-CMAC algorithm.

public static ValueTask<int> HashDataAsync(ReadOnlyMemory<byte> key, Stream source, Memory<byte> destination, CancellationToken cancellationToken = default)

Parameters

key ReadOnlyMemory<byte>

The CMAC key.

source Stream

The stream to CMAC.

destination Memory<byte>

The buffer to receive the CMAC value.

cancellationToken CancellationToken

The token to monitor for cancellation requests. The default value is None.

Returns

ValueTask<int>

The total number of bytes written to destination.

Remarks

This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as ArgumentException, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by HashData(ReadOnlySpan<byte>, ReadOnlySpan<byte>, Span<byte>).

Exceptions

CryptographicException

The key length is other than 16, 24, or 32 bytes (128, 192, or 256 bits).

ArgumentNullException

source is null.

ArgumentException

source does not support reading.

ArgumentException

The buffer in destination is too small to hold the calculated CMAC. The AES-CMAC algorithm always produces a 128-bit CMAC, or 16 bytes.

OperationCanceledException

The cancellation token was canceled. This exception is stored into the returned task.

HashDataAsync(ReadOnlyMemory<byte>, Stream, CancellationToken)

Asynchronously computes the CMAC of a stream using the AES-CMAC algorithm.

public static ValueTask<byte[]> HashDataAsync(ReadOnlyMemory<byte> key, Stream source, CancellationToken cancellationToken = default)

Parameters

key ReadOnlyMemory<byte>

The CMAC key.

source Stream

The stream to CMAC.

cancellationToken CancellationToken

The token to monitor for cancellation requests. The default value is None.

Returns

ValueTask<byte[]>

The HMAC of the data.

Remarks

This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as ArgumentException, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by HashData(ReadOnlySpan<byte>, Stream).

Exceptions

CryptographicException

The key length is other than 16, 24, or 32 bytes (128, 192, or 256 bits).

ArgumentNullException

source is null.

ArgumentException

source does not support reading.

OperationCanceledException

The cancellation token was canceled. This exception is stored into the returned task.

HashFinal()

When overridden in a derived class, finalizes the hash computation after the last data is processed by the cryptographic hash algorithm.

protected override byte[] HashFinal()

Returns

byte[]

The computed hash code.

Initialize()

Resets the hash algorithm to its initial state.

public override void Initialize()

Exceptions

ObjectDisposedException

The AesCmac instance has been disposed.

RegisterWithCryptoConfig()

Registers the AesCmac class with CryptoConfig, such that it can be created by name.

public static void RegisterWithCryptoConfig()

Remarks

CryptoConfig is not supported in browsers.

See Also

CreateFromName(string)

TryHashData(ReadOnlySpan<byte>, ReadOnlySpan<byte>, Span<byte>, out int)

Attempts to compute the CMAC of data using the AES-CMAC algorithm.

public static bool TryHashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten)

Parameters

key ReadOnlySpan<byte>

The CMAC key.

source ReadOnlySpan<byte>

The data to CMAC.

destination Span<byte>

The buffer to receive the CMAC value.

bytesWritten int

When this method returns, the total number of bytes written into destination.

Returns

bool

true if destination was large enough to receive the calculated CMAC; otherwise, false.

Exceptions

CryptographicException

The key length is other than 16, 24, or 32 bytes (128, 192, or 256 bits).

TryHashFinal(Span<byte>, out int)

Attempts to finalize the hash computation after the last data is processed by the hash algorithm.

protected override bool TryHashFinal(Span<byte> destination, out int bytesWritten)

Parameters

destination Span<byte>

The buffer to receive the hash value.

bytesWritten int

When this method returns, the total number of bytes written into destination. This parameter is treated as uninitialized.

Returns

bool

true if destination is long enough to receive the hash value; otherwise, false.

See Also

https://csrc.nist.gov/publications/detail/sp/800-38b/final

https://www.rfc-editor.org/rfc/rfc4493.html