Nonce Struct

Represents a nonce for authenticated encryption.

public readonly struct Nonce : IEquatable<Nonce>

A Nonce value consists of two fields: a fixed field and a counter field. The fixed field remains constant for all nonces that are generated for a given key. The counter fields of successive nonces form a monotonically increasing sequence, when those fields are regarded as unsigned integers in big-endian byte order.

In case nonces need to be generated in a different way, the fixed field can be set to a new value for each encryption operation, and the size of the counter field to zero.

See How to: Generate Nonces for additional information on generating nonces.

Static Fields

MaxSize

Represents the largest possible size of a nonce, in bytes.

public static readonly int MaxSize = 24;

This field is constant and read-only.

Constructors

Nonce()

Initializes a new instance of Nonce with a zero-length fixed field and a zero-length counter field.

public Nonce()

Nonce(int, int)

Initializes a new instance of Nonce with a fixed field and a counter field of the specified sizes. Both fields are initialized to zeros.

public Nonce(
    int fixedFieldSize,
    int counterFieldSize)

Parameters

fixedFieldSize
The size of the fixed field.
counterFieldSize
The size of the counter field.

Exceptions

ArgumentOutOfRangeException
fixedFieldSize or counterFieldSize is less than 0.
ArgumentOutOfRangeException
fixedFieldSize + counterFieldSize is greater than MaxSize.

Nonce(ReadOnlySpan<byte>, int)

Initializes a new instance of Nonce with the specified fixed field and a counter field of the specified size. The counter field is initialized to zero.

public Nonce(
    ReadOnlySpan<byte> fixedField,
    int counterFieldSize)

Parameters

fixedField
The fixed field.
counterFieldSize
The size of the counter field.

Exceptions

ArgumentException
fixedField.Length is greater than MaxSize.
ArgumentOutOfRangeException
counterFieldSize is less than 0.
ArgumentOutOfRangeException
fixedField.Length + counterFieldSize is greater than MaxSize.

Nonce(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Initializes a new instance of Nonce with the specified fixed field and and the specified counter field.

public Nonce(
    ReadOnlySpan<byte> fixedField,
    ReadOnlySpan<byte> counterField)

Parameters

fixedField
The fixed field.
counterField
The counter field.

Exceptions

ArgumentException
fixedField.Length + counterField.Length is greater than MaxSize.

Properties

CounterFieldSize

Gets the size of the counter field, in bytes.

public int CounterFieldSize { get; }

Property Value

The size of the counter field, in bytes.

FixedFieldSize

Gets the size of the fixed field, in bytes.

public int FixedFieldSize { get; }

Property Value

The size of the fixed field, in bytes.

Size

Gets the total size of the nonce, in bytes.

public int Size { get; }

Property Value

The total size of the nonce, in bytes.

Static Methods

Equals(in Nonce, in Nonce)

Returns a value indicating whether two specified instances of Nonce represent the same value.

public static bool Equals(
    in Nonce left,
    in Nonce right)

Parameters

left
The first value to compare.
right
The second value to compare.

Return Value

true if left and right are equal; otherwise, false.

Remarks

This method is equivalent to left.Equals(right) but faster.

TryAdd(ref Nonce, int)

Attempts to add the specified value to the counter field of the specified Nonce.

public static bool TryAdd(
    ref Nonce nonce,
    int value)

Parameters

nonce
The nonce with the counter field to add the value to.
value
The value to add to the counter field of the nonce. The value must be greater than or equal to 0.

Return Value

false if the addition of the value overflows the counter field of the nonce; otherwise, true.

Exceptions

ArgumentOutOfRangeException
value is negative.

Remarks

This method is equivalent to nonce += value; but faster.

TryIncrement(ref Nonce)

Attempts to increment the counter field of the specified Nonce by 1.

public static bool TryIncrement(
    ref Nonce nonce)

Parameters

nonce
The nonce with the counter field to increment.

Return Value

false if the increment overflows the counter field of the nonce; otherwise, true.

Remarks

This method is equivalent to nonce++; but faster.

Xor(ref Nonce, in Nonce)

Performs a bitwise exclusive Or (XOr) operation on the specified Nonce values and stores the result in the first parameter.

public static void Xor(
    ref Nonce nonce,
    in Nonce other)

Parameters

nonce
A nonce to perform the XOr operation on.
other
A nonce to perform the XOr operation on.

Exceptions

ArgumentException
The sizes of the two nonces are not the same.

Remarks

This method is equivalent to nonce ^= other; but faster.

Methods

CopyTo(Span<byte>)

Copies the current Nonce to the specified span of bytes.

public void CopyTo(
    Span<byte> destination)

Parameters

destination
The span of bytes that is the destination of the elements copied from the current nonce.

Exceptions

ArgumentException
The size of the current nonce is greater than the available number of bytes in destination.

Equals(Nonce)

Returns a value indicating whether the current Nonce and the specified Nonce represent the same value.

public bool Equals(
    Nonce other)

Parameters

other
A nonce to compare to the current nonce.

Return Value

true if other is equal to the current nonce; otherwise, false.

ToArray()

Copies the current Nonce to a new array of bytes.

public byte[] ToArray()

Return Value

A new array of bytes containing a copy of the current nonce.

Operators

Addition(Nonce, int)

Returns a new Nonce by adding the specified value to the counter field of the specified Nonce.

public static Nonce operator +(
    Nonce nonce,
    int value)

Parameters

nonce
The nonce with the counter field to add the value to.
value
The value to add to the counter field of the nonce. The value must be greater than or equal to 0.

Return Value

The nonce with value added to the counter field.

Exceptions

OverflowException
The addition of the value overflows the counter field of the nonce.

Equality(Nonce, Nonce)

Returns a value that indicates whether two Nonce values are equal.

public static bool operator ==(
    Nonce left,
    Nonce right)

Parameters

left
The first value to compare.
right
The second value to compare.

Return Value

true if left and right are equal; otherwise, false.

Increment(Nonce)

Returns a new Nonce by incrementing the counter field of the specified Nonce by 1.

public static Nonce operator ++(
    Nonce nonce)

Parameters

nonce
The nonce with the counter field to increment.

Return Value

The nonce with the counter field incremented by 1.

Exceptions

OverflowException
The increment overflows the counter field of the nonce.

Inequality(Nonce, Nonce)

Returns a value that indicates whether two Nonce values are not equal.

public static bool operator !=(
    Nonce left,
    Nonce right)

Parameters

left
The first value to compare.
right
The second value to compare.

Return Value

true if left and right are not equal; otherwise, false.

Xor(Nonce, Nonce)

Returns a new Nonce by performing a bitwise exclusive Or (XOr) operation on the specified Nonce values.

public static Nonce operator ^(
    Nonce left,
    Nonce right)

Parameters

left
A nonce to perform the XOr operation on.
right
A nonce to perform the XOr operation on.

Return Value

The result of the the XOr operation.

Exceptions

ArgumentException
The sizes of the two nonces are not the same.

Thread Safety

All members of this type are thread safe. Members that appear to modify instance state actually return a new instance initialized with the new value. 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