IncrementalMac Struct

Represents the state of a message authentication code (MAC) algorithm that can be incrementally updated with segments of data.

public readonly struct IncrementalMac

This type provides an “init, update, final” interface for computing a MAC: First, a state needs to be initialized with a MAC key to be used. The state can then be updated zero or more times with segments of data. Finalizing the state yields a result that is identical to the MAC of the concatenated segments.

IncrementalMac instances have value-type semantics: Passing an instance to a method or assigning it to a variable creates a copy of the state.

Example

The following C# example shows how to compute a message authentication code from multiple segments of data:

// select the BLAKE2b-256 algorithm
var algorithm = MacAlgorithm.Blake2b_256;

// create a new key
using (var key = Key.Create(algorithm))
{
    // initialize the state with the key
    IncrementalMac.Initialize(key, out var state);

    // incrementally update the state with some data
    var lines = new[]
    {
        "It is a dark time for the\n",
        "Rebellion. Although the Death\n",
        "Star has been destroyed,\n",
        "Imperial troops have driven the\n",
        "Rebel forces from their hidden\n",
        "base and pursued them across\n",
        "the galaxy.\n"
    };
    foreach (var line in lines)
    {
        IncrementalMac.Update(ref state, Encoding.UTF8.GetBytes(line));
    }

    // finalize the computation and get the result
    var mac = IncrementalMac.Finalize(ref state);
}

Properties

Algorithm

Gets the algorithm that was used to initialize the state.

public MacAlgorithm Algorithm { get; }

Property Value

An instance of the MacAlgorithm class, or null if the current instance has not been initialized yet or has been finalized.

Static Methods

Initialize(Key, out IncrementalMac)

Initializes the IncrementalMac state with the specified key.

public static void Initialize(
    Key key,
    out IncrementalMac state)

Parameters

key
The key to use for computing the message authentication code.
state
When this method returns, contains the initialized state.

Exceptions

ArgumentNullException
key is null.
ArgumentException
key.Algorithm is not an instance of the MacAlgorithm class.
ObjectDisposedException
key has been disposed.

Update(ref IncrementalMac, ReadOnlySpan<byte>)

Updates the IncrementalMac state with the specified span of bytes.

public static void Update(
    ref IncrementalMac state,
    ReadOnlySpan<byte> data)

Parameters

state
The state to be updated with data.
data
A segment of the data to be authenticated.

Exceptions

InvalidOperationException
state has not been initialized yet or has already been finalized.

Finalize(ref IncrementalMac)

Completes the MAC computation and returns the result as an array of bytes.

public static byte[] Finalize(
    ref IncrementalMac state)

Parameters

state
The state to be finalized.

Return Value

The computed message authentication code.

Exceptions

InvalidOperationException
state has not been initialized yet or has already been finalized.

Finalize(ref IncrementalMac, Span<byte>)

Completes the MAC computation and fills the specified span of bytes with the result.

public static void Finalize(
    ref IncrementalMac state,
    Span<byte> mac)

Parameters

state
The state to be finalized.
mac
The span to fill with the computed message authentication code.

Exceptions

InvalidOperationException
state has not been initialized yet or has already been finalized.
ArgumentException
mac.Length is not equal to MacSize.

FinalizeAndVerify(ref IncrementalMac, ReadOnlySpan<byte>)

Completes the MAC computation and verifies the the specified message authentication code.

public static bool FinalizeAndVerify(
    ref IncrementalMac state,
    ReadOnlySpan<byte> mac)

Parameters

state
The state to be finalized.
mac
The message authentication code to be verified.

Return Value

true if verification succeeds; otherwise, false.

Exceptions

InvalidOperationException
state has not been initialized yet or has already been finalized.

Thread Safety

Any public static members of this type are thread safe. Any instance members are not guaranteed to be thread safe. As with any other type, reading and writing to a shared variable that contains an instance of this type must be protected by a lock to guarantee thread safety.

See Also