AsconXof<T> Class

Definition

Namespace

Bodu.Security.Cryptography

Assembly

Bodu.Security.Cryptography.dll

Package

Bodu.Security.Cryptography 1.2.0

Source

AsconXof{T}.cs

Abstract base class for ASCON extendable output functions (XOFs) as defined in NIST SP 800-232. Implements the shared sponge construction, residual-buffer management, padding, and Ascon-p permutation used by AsconXof128 and AsconCxof128.

public abstract class AsconXof<T> : IDisposable where T : AsconXof<T>, new()

Type Parameters

T

The concrete XOF type derived from this class.

Inheritance

object

AsconXof<T>

Implements

IDisposable

Derived

AsconCxof128

AsconXof128

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

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

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

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

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

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

Examples

// Consume through a concrete derivative - produce a 32-byte digest from "hello".
using var xof = new AsconXof128();
xof.Absorb("hello"u8);

byte[] digest = new byte[32];
xof.Squeeze(digest);

// Squeeze additional output of any length - the XOF can produce as many bytes as needed.
byte[] more = new byte[64];
xof.Squeeze(more);

// Reuse the instance for a new message via Initialize.
xof.Initialize();
xof.Absorb("world"u8);
xof.Squeeze(digest);

Remarks

All ASCON XOF algorithms share a 320-bit internal state of five 64-bit words, a 64-bit (8-byte) rate, and a variable-length output. They differ in their pre-computed initialization state, in the number of absorption rounds (pb), and in whether a customization string may be supplied before absorption.

The lifecycle of an instance is:

1. Optionally customize (only AsconCxof128).
2. Call Absorb(ReadOnlySpan<byte>) zero or more times to supply input data.
3. Call Squeeze(Span<byte>) one or more times to produce output of any length. Once squeezing has begun, no further data may be absorbed.
4. Call Initialize() to reset the instance and reuse it for a new message.

Padding follows the Ascon convention: the byte immediately after the last absorbed byte is XORed with 0x01, and the remaining rate bytes retain their current state values. The transition from absorption to squeezing always applies the full 12-round permutation (Ascon-p12). Subsequent squeeze blocks use pb rounds between extractions.

Don't derive from this class directly. Use one of the two concrete XOFs that extend it:

• AsconXof128Plain Ascon XOF - variable-length output without a customization string.
• AsconCxof128 Customizable Ascon XOF - accepts a customization string before absorption to domain-separate output families.

For fixed-length Ascon hashing use AsconHash256 or AsconHashA256; for the AEAD member of the Ascon suite use AsconAead128.

The concrete type T must expose a public parameterless constructor to satisfy the base class's new() constraint.

Constructors

AsconXof(ulong, ulong, ulong, ulong, ulong, int, string)

Initializes a new instance of the AsconXof<T> class with the specified algorithm parameters.

protected AsconXof(ulong iv0, ulong iv1, ulong iv2, ulong iv3, ulong iv4, int absorptionRounds, string algorithmName)

Parameters

iv0 ulong

Pre-computed initial state word 0 (result of applying Ascon-p12 to the raw IV).

iv1 ulong

Pre-computed initial state word 1.

iv2 ulong

Pre-computed initial state word 2.

iv3 ulong

Pre-computed initial state word 3.

iv4 ulong

Pre-computed initial state word 4.

absorptionRounds int

Number of Ascon-p rounds applied after each absorbed block and between squeeze blocks. Must be between 1 and 12.

algorithmName string

The canonical algorithm identifier string as defined in NIST SP 800-232. Must not be null.

Exceptions

ArgumentNullException

algorithmName is null.

ArgumentOutOfRangeException

absorptionRounds is less than 1 or greater than 12.

Properties

AlgorithmName

Gets the canonical algorithm name for this XOF variant as defined in NIST SP 800-232.

public string AlgorithmName { get; }

Property Value

string

A string such as "ASCON-XOF128" or "ASCON-CXOF128".

Exceptions

ObjectDisposedException

The instance has been disposed.

Methods

Absorb(ReadOnlySpan<byte>)

Absorbs data into the sponge state. May be called multiple times before the first Squeeze(Span<byte>).

public virtual void Absorb(ReadOnlySpan<byte> data)

Parameters

data ReadOnlySpan<byte>

The input data to absorb. May be empty.

Exceptions

ObjectDisposedException

The instance has been disposed.

InvalidOperationException

Squeeze(Span<byte>) has already been called; call Initialize() to reset and start over.

Create()

Creates a new instance of T using its public parameterless constructor.

public static T Create()

Returns

T

A new, uninitialized T instance.

Dispose()

Releases the resources used by this instance and clears the internal sponge state.

public void Dispose()

Dispose(bool)

Releases managed resources and clears the sponge state.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

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

FinalizeAbsorptionPhase()

Finalizes a sponge absorption phase by padding the residual buffer with 0x01 at the next unused byte position, absorbing the padded block, and applying Bodu.Security.Cryptography.AsconXof`1._absorptionRounds Ascon-p rounds. Resets the residual counter to zero so that the next call to Absorb(ReadOnlySpan<byte>) starts from a clean state.

protected void FinalizeAbsorptionPhase()

Remarks

Derived classes (specifically AsconCxof128) call this to close the customization phase before injecting a domain-separation constant.

GetHash(int)

Squeezes exactly outputLength bytes and returns them as a new array.

public byte[] GetHash(int outputLength)

Parameters

outputLength int

The number of bytes to produce. Must be greater than zero.

Returns

byte[]

A new byte array of length outputLength containing the squeezed output.

Exceptions

ObjectDisposedException

The instance has been disposed.

ArgumentOutOfRangeException

outputLength is less than or equal to zero.

HashData(ReadOnlySpan<byte>, int)

Hashes source in a single pass and returns outputLength bytes.

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

Parameters

source ReadOnlySpan<byte>

The input data to hash.

outputLength int

The number of output bytes to produce. Must be greater than zero.

Returns

byte[]

A byte array of length outputLength containing the XOF output.

Exceptions

ArgumentOutOfRangeException

outputLength is less than or equal to zero.

Initialize()

Resets the instance to its initial state, discarding any absorbed data or squeezed output, so that it is ready to accept a new message.

public virtual void Initialize()

Exceptions

ObjectDisposedException

The instance has been disposed.

Squeeze(Span<byte>)

Squeezes output.Length bytes from the sponge into output. May be called multiple times to produce an unbounded output stream.

public void Squeeze(Span<byte> output)

Parameters

output Span<byte>

Destination for the squeezed bytes. May be empty.

Exceptions

ObjectDisposedException

The instance has been disposed.

ThrowIfDisposed()

Throws an ObjectDisposedException if the algorithm instance has been disposed.

protected void ThrowIfDisposed()

Exceptions

ObjectDisposedException

Thrown when any public method or property is accessed after the instance has been disposed.

Applies to

Product	Versions
.NET	8, 10

See Also

AsconXof128

AsconCxof128

AsconHash

NIST SP 800-232 (ASCON)