Nonce Struct

Definition

Namespace

Bodu.Security.Cryptography

Assembly

Bodu.Security.Cryptography.dll

Package

Bodu.Security.Cryptography 1.2.0

Source

Nonce.cs

Represents a number-used-once supplied to an authenticated-encryption or stream-cipher operation.

public readonly struct Nonce : IEquatable<Nonce>

Implements

IEquatable<Nonce>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.Clamp<T>(T, T?, T?, IComparer<T>)

ComparableExtensions.IsBetween<T>(T, T?, T?, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.IsGreaterThanOrEqual<T>(T, T?, IComparer<T>)

ComparableExtensions.IsGreaterThan<T>(T, T?, IComparer<T>)

ComparableExtensions.IsLessThanOrEqual<T>(T, T?, IComparer<T>)

ComparableExtensions.IsLessThan<T>(T, T?, IComparer<T>)

ComparableExtensions.IsOutside<T>(T, T?, T?, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Examples

// Generate a fresh 12-byte nonce for an AES-GCM operation; it is unique per message, not secret.
Nonce nonce = Nonce.Random(12);
using var aes = new AesGcm(key, tagSizeInBytes: 16);
aes.Encrypt(nonce.AsSpan(), plaintext, ciphertext, tag);

// The nonce travels with the ciphertext; reconstruct it on the receiving side to decrypt.
Nonce received = Nonce.FromBytes(wireNonceBytes);

Remarks

A nonce is unique per operation under a given key but is not secret; it typically travels alongside the ciphertext. Using a dedicated type keeps nonces from being confused with keys, salts, or authentication tags in APIs that would otherwise accept several look-alike byte buffers.

Nonce carries its bytes by defensive copy, and the default instance (default(Nonce)) is the empty value: Length is 0 and IsEmpty is true.

This type does not enforce uniqueness; callers remain responsible for never reusing a nonce with the same key. Random(int) draws from a cryptographically secure generator, which is appropriate for nonce sizes where random collision is negligible (for example the 24-byte XChaCha20 nonce).

Properties

IsEmpty

Gets a value indicating whether the nonce is empty.

public bool IsEmpty { get; }

Property Value

bool

true if the nonce contains no bytes; otherwise, false.

Length

Gets the number of bytes in the nonce.

public int Length { get; }

Property Value

int

The nonce length in bytes, or 0 for the empty value.

Methods

AsSpan()

Returns a read-only view over the nonce bytes.

public ReadOnlySpan<byte> AsSpan()

Returns

ReadOnlySpan<byte>

A read-only span over the value; empty for the empty value.

Equals(Nonce)

Determines whether this nonce equals another.

public bool Equals(Nonce other)

Parameters

other Nonce

The nonce to compare against.

Returns

bool

true if both values contain identical bytes; otherwise, false.

Remarks

The comparison runs through FixedTimeEquals(ReadOnlySpan<byte>, ReadOnlySpan<byte>) for a uniform, content-independent duration across the secret-bearing value types, though a nonce is not itself a secret. A length mismatch returns false immediately. No dedicated FixedTimeEquals member is offered: a nonce is a public, non-repeating value and is not verified against attacker-supplied input, so exposing one would wrongly imply a secret-comparison contract.

Equals(object?)

Determines whether this nonce equals the specified object.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare against.

Returns

bool

true if obj is a Nonce with identical bytes; otherwise, false.

FromBytes(ReadOnlySpan<byte>)

Creates a Nonce from the provided bytes.

public static Nonce FromBytes(ReadOnlySpan<byte> value)

Parameters

value ReadOnlySpan<byte>

The nonce bytes to copy. An empty span yields the empty value.

Returns

Nonce

A new Nonce containing a defensive copy of value.

GetHashCode()

Returns a hash code computed over the nonce bytes.

public override int GetHashCode()

Returns

int

A hash code consistent with Equals(Nonce).

Random(int)

Creates a Nonce of the specified length filled with cryptographically secure random bytes.

public static Nonce Random(int length)

Parameters

length int

The number of random bytes to generate.

Returns

Nonce

A new Nonce of length random bytes.

Exceptions

ArgumentOutOfRangeException

length ≤ 0.

ToArray()

Copies the nonce bytes into a new array.

public byte[] ToArray()

Returns

byte[]

A new array containing the nonce bytes; an empty array for the empty value.

ToString()

Returns the lowercase hexadecimal representation of the nonce.

public override string ToString()

Returns

string

The nonce bytes as lowercase hexadecimal text; Empty for the empty value.

Remarks

Nonces are not secrets, so the content is intentionally included in the string representation.

Operators

operator ==(Nonce, Nonce)

Determines whether two nonces are equal.

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

Parameters

left Nonce

The first nonce.

right Nonce

The second nonce.

Returns

bool

true if the values contain identical bytes; otherwise, false.

operator !=(Nonce, Nonce)

Determines whether two nonces are not equal.

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

Parameters

left Nonce

The first nonce.

right Nonce

The second nonce.

Returns

bool

true if the values differ; otherwise, false.

Applies to

Product	Versions
.NET	8, 10