AsconDigest.cs

using System;
using System.Runtime.CompilerServices;
using Algorithms.Crypto.Utils;

namespace Algorithms.Crypto.Digests;

/// <summary>
/// Implements the Ascon cryptographic hash algorithm, providing both the standard Ascon-Hash and the Ascon-HashA variants.
/// </summary>
/// <remarks>
/// The <see cref="AsconDigest"/> class implements the Ascon hash function, a lightweight cryptographic algorithm designed for
/// resource-constrained environments such as IoT devices. It provides two variants:
/// <list type="bullet">
/// <item>
/// <description>
/// <see cref="AsconParameters.AsconHash"/>: The standard Ascon-Hash variant with 12 rounds of the permutation function for enhanced security.
/// </description>
/// </item>
/// <item>
/// <description>
/// <see cref="AsconParameters.AsconHashA"/>: A performance-optimized variant with 8 rounds of the permutation function, offering a trade-off between security and performance.
/// </description>
/// </item>
/// </list>
/// <br />
/// The AsconDigest processes data in 8-byte blocks, accumulating input until a block is complete, at which point it applies
/// the permutation function to update the internal state. After all data has been processed, the hash value can be finalized
/// and retrieved.
/// <br />
/// Ascon was designed to meet the requirements of lightweight cryptography, making it ideal for devices with limited computational power.
/// </remarks>
public class AsconDigest : IDigest
{
    public enum AsconParameters
    {
        /// <summary>
        /// Represents the Ascon Hash variant, the standard cryptographic hashing function of the Ascon family.
        /// </summary>
        /// <remarks>
        /// AsconHash is the primary hashing algorithm in the Ascon family. It is designed for efficiency and security
        /// in resource-constrained environments, such as IoT devices, and provides high resistance to cryptanalytic attacks.
        /// This variant uses 12 rounds of the permutation function for increased security.
        /// </remarks>
        AsconHash,

        /// <summary>
        /// Represents the Ascon HashA variant, an alternative variant of the Ascon hashing function with fewer permutation rounds.
        /// </summary>
        /// <remarks>
        /// AsconHashA is a variant of the Ascon hashing function that uses fewer rounds (8 rounds) of the permutation function,
        /// trading off some security for improved performance in specific scenarios. It is still designed to be secure for many
        /// applications, but it operates faster in environments where computational resources are limited.
        /// </remarks>
        AsconHashA,
    }

    /// <summary>
    /// Specifies the Ascon variant being used (either Ascon-Hash or Ascon-HashA). This defines the cryptographic algorithm's behavior.
    /// </summary>
    private readonly AsconParameters asconParameters;

    /// <summary>
    /// The number of permutation rounds applied in the Ascon cryptographic process. This is determined by the selected Ascon variant.
    /// </summary>
    private readonly int asconPbRounds;

    /// <summary>
    /// Internal buffer that temporarily stores input data before it is processed in 8-byte blocks. The buffer is cleared after each block is processed.
    /// </summary>
    private readonly byte[] buffer = new byte[8];

    /// <summary>
    /// Internal state variable <c>x0</c> used in the cryptographic permutation function. This is updated continuously as input data is processed.
    /// </summary>
    private ulong x0;

    /// <summary>
    /// Internal state variable <c>x1</c> used in the cryptographic permutation function. This, along with other state variables, is updated during each round.
    /// </summary>
    private ulong x1;

    /// <summary>
    /// Internal state variable <c>x2</c> used in the cryptographic permutation function. It helps track the evolving state of the digest.
    /// </summary>
    private ulong x2;

    /// <summary>
    /// Internal state variable <c>x3</c> used in the cryptographic permutation function, contributing to the mixing and non-linearity of the state.
    /// </summary>
    private ulong x3;

    /// <summary>
    /// Internal state variable <c>x4</c> used in the cryptographic permutation function. This, along with <c>x0</c> to <c>x3</c>, ensures cryptographic security.
    /// </summary>
    private ulong x4;

    /// <summary>
    /// Tracks the current position within the <c>buffer</c> array. When <c>bufferPosition</c> reaches 8, the buffer is processed and reset.
    /// </summary>
    private int bufferPosition;

    /// <summary>
    /// Initializes a new instance of the <see cref="AsconDigest"/> class with the specified Ascon parameters.
    /// </summary>
    /// <param name="parameters">The Ascon variant to use, either <see cref="AsconParameters.AsconHash"/> or <see cref="AsconParameters.AsconHashA"/>.</param>
    /// <remarks>
    /// This constructor sets up the digest by selecting the appropriate number of permutation rounds based on the Ascon variant.
    /// <list type="bullet">
    /// <item><description>For <see cref="AsconParameters.AsconHash"/>, 12 permutation rounds are used.</description></item>
    /// <item><description>For <see cref="AsconParameters.AsconHashA"/>, 8 permutation rounds are used.</description></item>
    /// </list>
    /// If an unsupported parameter is provided, the constructor throws an <see cref="ArgumentException"/> to indicate that the parameter is invalid.
    /// The internal state of the digest is then reset to prepare for processing input data.
    /// </remarks>
    /// <exception cref="ArgumentException">Thrown when an invalid parameter setting is provided for Ascon Hash.</exception>
    public AsconDigest(AsconParameters parameters)
    {
        // Set the Ascon parameter (AsconHash or AsconHashA) for this instance.
        asconParameters = parameters;

        // Determine the number of permutation rounds based on the Ascon variant.
        asconPbRounds = parameters switch
        {
            AsconParameters.AsconHash => 12,  // 12 rounds for Ascon-Hash variant.
            AsconParameters.AsconHashA => 8,  // 8 rounds for Ascon-HashA variant.
            _ => throw new ArgumentException("Invalid parameter settings for Ascon Hash"), // Throw exception for invalid parameter.
        };

        // Reset the internal state to prepare for new input.
        Reset();
    }

    /// <summary>
    /// Gets the name of the cryptographic algorithm based on the selected Ascon parameter.
    /// </summary>
    /// <value>
    /// A string representing the name of the algorithm variant, either "Ascon-Hash" or "Ascon-HashA".
    /// </value>
    /// <remarks>
    /// This property determines the algorithm name based on the selected Ascon variant when the instance was initialized.
    /// It supports two variants:
    /// <list type="bullet">
    /// <item><description>"Ascon-Hash" for the <see cref="AsconParameters.AsconHash"/> variant.</description></item>
    /// <item><description>"Ascon-HashA" for the <see cref="AsconParameters.AsconHashA"/> variant.</description></item>
    /// </list>
    /// If an unsupported or unknown parameter is used, the property throws an <see cref="InvalidOperationException"/>.
    /// </remarks>
    /// <exception cref="InvalidOperationException">Thrown if an unknown Ascon parameter is encountered.</exception>
    public string AlgorithmName
    {
        get
        {
            return asconParameters switch
            {
                AsconParameters.AsconHash => "Ascon-Hash",  // Return "Ascon-Hash" for AsconHash variant.
                AsconParameters.AsconHashA => "Ascon-HashA", // Return "Ascon-HashA" for AsconHashA variant.
                _ => throw new InvalidOperationException(), // Throw an exception for unknown Ascon parameters.
            };
        }
    }

    /// <summary>
    /// Gets the size of the resulting hash produced by the digest, in bytes.
    /// </summary>
    /// <returns>The size of the hash, which is 32 bytes (256 bits) for this digest implementation.</returns>
    /// <remarks>
    /// This method returns the fixed size of the hash output produced by the digest algorithm. In this implementation,
    /// the digest produces a 256-bit hash, which corresponds to 32 bytes. This is typical for cryptographic hash functions
    /// that aim to provide a high level of security by generating a large output size.
    /// </remarks>
    public int GetDigestSize() => 32;

    /// <summary>
    /// Gets the internal block size of the digest in bytes.
    /// </summary>
    /// <returns>The internal block size of the digest, which is 8 bytes (64 bits).</returns>
    /// <remarks>
    /// This method returns the block size that the digest algorithm uses when processing input data. The input is processed
    /// in chunks (blocks) of 8 bytes at a time. This block size determines how the input data is split and processed in multiple
    /// steps before producing the final hash.
    /// </remarks>
    public int GetByteLength() => 8;

    /// <summary>
    /// Updates the cryptographic state by processing a single byte of input and adding it to the internal buffer.
    /// </summary>
    /// <param name="input">The byte to be added to the internal buffer and processed.</param>
    /// <remarks>
    /// This method collects input bytes in an internal buffer. Once the buffer is filled (reaching 8 bytes), the buffer is processed
    /// by converting it into a 64-bit unsigned integer in big-endian format and XORing it with the internal state variable <c>x0</c>.
    /// After processing the buffer, the permutation function <see cref="P(int)"/> is applied to mix the internal state, and the buffer position is reset to zero.
    /// <br/><br/>
    /// If the buffer has not yet reached 8 bytes, the method simply adds the input byte to the buffer and waits for further input.
    /// </remarks>
    public void Update(byte input)
    {
        // Add the input byte to the buffer.
        buffer[bufferPosition] = input;

        // If the buffer is not full (less than 8 bytes), increment the buffer position and return early.
        if (++bufferPosition != 8)
        {
            return; // Wait for more input to fill the buffer before processing.
        }

        // Once the buffer is full (8 bytes), convert the buffer to a 64-bit integer (big-endian) and XOR it with the state.
        x0 ^= ByteEncodingUtils.BigEndianToUint64(buffer, 0);

        // Apply the permutation function to mix the state.
        P(asconPbRounds);

        // Reset the buffer position for the next block of input.
        bufferPosition = 0;
    }

    /// <summary>
    /// Updates the cryptographic state by processing a segment of input data from a byte array, starting at a specified offset and length.
    /// </summary>
    /// <param name="input">The byte array containing the input data to be processed.</param>
    /// <param name="inOff">The offset in the input array where processing should begin.</param>
    /// <param name="inLen">The number of bytes from the input array to process.</param>
    /// <remarks>
    /// This method ensures that the input data is valid by checking the array length, starting from the provided offset,
    /// and making sure it is long enough to accommodate the specified length. It then processes the data by converting
    /// the relevant section of the byte array to a <see cref="ReadOnlySpan{T}"/> and delegating the actual block update to
    /// the <see cref="BlockUpdate(ReadOnlySpan{byte})"/> method for further processing.
    /// </remarks>
    /// <exception cref="ArgumentException">
    /// Thrown if the input data is too short, starting from <paramref name="inOff"/> and for the length <paramref name="inLen"/>.
    /// </exception>
    public void BlockUpdate(byte[] input, int inOff, int inLen)
    {
        // Validate the input data to ensure there is enough data to process from the specified offset and length.
        ValidationUtils.CheckDataLength(input, inOff, inLen, "input buffer too short");

        // Convert the input byte array into a ReadOnlySpan<byte> and delegate the processing to the span-based method.
        BlockUpdate(input.AsSpan(inOff, inLen));
    }

    /// <summary>
    /// Processes the input data by updating the internal cryptographic state, handling both partial and full blocks.
    /// </summary>
    /// <param name="input">A read-only span of bytes representing the input data to be processed.</param>
    /// <remarks>
    /// This method processes the input data in chunks of 8 bytes. It manages the internal buffer to accumulate data
    /// until there are enough bytes to process a full 8-byte block. When the buffer is full or enough input is provided,
    /// it XORs the buffered data with the internal state variable <c>x0</c> and applies the permutation function
    /// <see cref="P"/> to update the cryptographic state.
    /// <br/><br/>
    /// If the input contains more than 8 bytes, the method continues to process full 8-byte blocks in a loop until
    /// the input is exhausted. Any remaining bytes (less than 8) are stored in the internal buffer for future processing.
    /// </remarks>
    public void BlockUpdate(ReadOnlySpan<byte> input)
    {
        // Calculate the number of available bytes left in the buffer before it reaches 8 bytes.
        var available = 8 - bufferPosition;

        // If the input length is smaller than the remaining space in the buffer, copy the input into the buffer.
        if (input.Length < available)
        {
            input.CopyTo(buffer.AsSpan(bufferPosition)); // Copy the small input into the buffer.
            bufferPosition += input.Length; // Update the buffer position.
            return; // Return early since we don't have enough data to process a full block.
        }

        // If there is data in the buffer, but it isn't full, fill it and process the full 8-byte block.
        if (bufferPosition > 0)
        {
            // Copy enough bytes from the input to complete the buffer.
            input[..available].CopyTo(buffer.AsSpan(bufferPosition));

            // XOR the full buffer with the internal state (x0) and apply the permutation.
            x0 ^= ByteEncodingUtils.BigEndianToUint64(buffer);
            P(asconPbRounds); // Apply the permutation rounds.

            // Update the input to exclude the bytes we've already processed from the buffer.
            input = input[available..];
        }

        // Process full 8-byte blocks directly from the input.
        while (input.Length >= 8)
        {
            // XOR the next 8-byte block from the input with the internal state and apply the permutation.
            x0 ^= ByteEncodingUtils.BigEndianToUint64(input);
            P(asconPbRounds);

            // Move to the next 8-byte chunk in the input.
            input = input[8..];
        }

        // Copy any remaining bytes (less than 8) into the buffer to store for future processing.
        input.CopyTo(buffer);
        bufferPosition = input.Length; // Update the buffer position to reflect the remaining unprocessed data.
    }

    /// <summary>
    /// Finalizes the cryptographic hash computation, absorbing any remaining data, applying the final permutation,
    /// and writing the resulting hash to the specified position in the provided output byte array.
    /// </summary>
    /// <param name="output">The byte array where the final 32-byte hash will be written.</param>
    /// <param name="outOff">The offset in the output array at which to start writing the hash.</param>
    /// <returns>The size of the hash (32 bytes).</returns>
    /// <remarks>
    /// This method finalizes the hash computation by converting the output array to a <see cref="Span{T}"/> and
    /// calling the <see cref="DoFinal(Span{byte})"/> method. It provides flexibility in placing the result in an
    /// existing byte array with a specified offset.
    /// </remarks>
    /// <exception cref="ArgumentException">Thrown if the output buffer is too small to hold the resulting hash.</exception>
    public int DoFinal(byte[] output, int outOff)
    {
        // Call the Span-based DoFinal method with the output byte array and offset.
        return DoFinal(output.AsSpan(outOff));
    }

    /// <summary>
    /// Finalizes the cryptographic hash computation, absorbing any remaining data, applying the final permutation, and
    /// writing the resulting hash to the provided output buffer.
    /// </summary>
    /// <param name="output">A span of bytes where the final 32-byte hash will be written.</param>
    /// <returns>The size of the hash (32 bytes).</returns>
    /// <remarks>
    /// This method completes the hash computation by absorbing any remaining input data, applying the final permutation,
    /// and extracting the state variables to produce the final hash. The method processes the state in 8-byte chunks,
    /// writing the result into the output buffer in big-endian format. After the final permutation is applied, the internal
    /// state is reset to prepare for a new hashing session.
    /// </remarks>
    /// <exception cref="ArgumentException">Thrown if the output buffer is too small to hold the resulting hash.</exception>
    public int DoFinal(Span<byte> output)
    {
        // Validate that the output buffer is at least 32 bytes in length.
        ValidationUtils.CheckOutputLength(output, 32, "output buffer too short");

        // Absorb any remaining input and apply the final permutation.
        AbsorbAndFinish();

        // Convert the first part of the state (x0) to big-endian format and write it to the output.
        ByteEncodingUtils.UInt64ToBigEndian(x0, output);

        // Loop to process the remaining parts of the internal state (x1, x2, etc.).
        for (var i = 0; i < 3; ++i)
        {
            // Move to the next 8-byte segment in the output buffer.
            output = output[8..];

            // Apply the permutation rounds to mix the state.
            P(asconPbRounds);

            // Convert the updated state variable (x0) to big-endian format and write it to the output.
            ByteEncodingUtils.UInt64ToBigEndian(x0, output);
        }

        // Reset the internal state for the next hash computation.
        Reset();

        // Return the size of the hash (32 bytes).
        return 32;
    }

    /// <summary>
    /// Computes the cryptographic hash of the input byte array and returns the result as a lowercase hexadecimal string.
    /// </summary>
    /// <param name="input">The input byte array to be hashed.</param>
    /// <returns>A string containing the computed hash in lowercase hexadecimal format.</returns>
    /// <remarks>
    /// This method takes a byte array as input, processes it to compute the Ascon hash, and returns the result as a hexadecimal string.
    /// It internally converts the byte array to a <see cref="Span{T}"/> and delegates the actual hashing to the
    /// <see cref="Digest(Span{byte})"/> method.
    /// </remarks>
    public string Digest(byte[] input)
    {
        return Digest(input.AsSpan());
    }

    /// <summary>
    /// Computes the cryptographic hash of the input span of bytes and returns the result as a lowercase hexadecimal string.
    /// </summary>
    /// <param name="input">A span of bytes representing the input data to be hashed.</param>
    /// <returns>A string containing the computed hash in lowercase hexadecimal format.</returns>
    /// <remarks>
    /// This method processes the input span using the Ascon cryptographic algorithm to compute the hash. It accumulates
    /// the input, applies the necessary permutations and internal state updates, and finally produces a hash in the form
    /// of a 32-byte array. The result is then converted into a lowercase hexadecimal string using <see cref="BitConverter"/>.
    /// </remarks>
    public string Digest(Span<byte> input)
    {
        // Update the internal state with the input data.
        BlockUpdate(input);

        // Create an array to hold the final hash output (32 bytes).
        var output = new byte[GetDigestSize()];

        // Finalize the hash computation and store the result in the output array.
        DoFinal(output, 0);

        // Convert the hash (byte array) to a lowercase hexadecimal string.
        return BitConverter.ToString(output).Replace("-", string.Empty).ToLowerInvariant();
    }

    /// <summary>
    /// Resets the internal state of the Ascon cryptographic hash algorithm to its initial state based on the selected variant.
    /// </summary>
    /// <remarks>
    /// This method clears the internal buffer and resets the buffer position to zero. Depending on the specified
    /// Ascon variant (<see cref="AsconParameters.AsconHash"/> or <see cref="AsconParameters.AsconHashA"/>), it also reinitializes
    /// the internal state variables (<c>x0</c>, <c>x1</c>, <c>x2</c>, <c>x3</c>, <c>x4</c>) to their starting values.
    /// <br/><br/>
    /// The reset is necessary to prepare the hash function for a new message. It ensures that previous messages do not
    /// affect the new one and that the internal state is consistent with the algorithm’s specification for the selected variant.
    /// </remarks>
    public void Reset()
    {
        // Clear the buffer to remove any leftover data from previous operations.
        Array.Clear(buffer, 0, buffer.Length);

        // Reset the buffer position to zero to start processing fresh input.
        bufferPosition = 0;

        // Initialize the internal state variables (x0, x1, x2, x3, x4) based on the selected Ascon variant.
        switch (asconParameters)
        {
            // If using the AsconHashA variant, set the specific initial state values for x0 through x4.
            case AsconParameters.AsconHashA:
                x0 = 92044056785660070UL;
                x1 = 8326807761760157607UL;
                x2 = 3371194088139667532UL;
                x3 = 15489749720654559101UL;
                x4 = 11618234402860862855UL;
                break;

            // If using the AsconHash variant, set the specific initial state values for x0 through x4.
            case AsconParameters.AsconHash:
                x0 = 17191252062196199485UL;
                x1 = 10066134719181819906UL;
                x2 = 13009371945472744034UL;
                x3 = 4834782570098516968UL;
                x4 = 3787428097924915520UL;
                break;

            // If an unknown Ascon variant is encountered, throw an exception.
            default:
                throw new InvalidOperationException();
        }
    }

    /// <summary>
    /// Finalizes the absorption phase of the cryptographic hash by padding the buffer and applying the final permutation round.
    /// </summary>
    /// <remarks>
    /// This method is called when the input data has been fully absorbed into the internal state, and it needs to be finalized.
    /// The buffer is padded with a specific value (0x80) to signify the end of the data, and the remaining portion of the buffer is
    /// XORed with the internal state variable <c>x0</c>. After padding, the final permutation round is applied using 12 rounds of
    /// the permutation function <see cref="P(int)"/>. This ensures the internal state is fully mixed and the cryptographic hash
    /// is securely finalized.
    /// </remarks>
    private void AbsorbAndFinish()
    {
        // Pad the buffer with 0x80 to indicate the end of the data.
        buffer[bufferPosition] = 0x80;

        // XOR the buffer (after padding) with the internal state x0, but only the relevant portion of the buffer is considered.
        // The (56 - (bufferPosition << 3)) shifts ensure that only the unprocessed part of the buffer is XORed into x0.
        x0 ^= ByteEncodingUtils.BigEndianToUint64(buffer, 0) & (ulong.MaxValue << (56 - (bufferPosition << 3)));

        // Apply 12 rounds of the permutation function to fully mix and finalize the internal state.
        P(12);
    }

    /// <summary>
    /// Executes the cryptographic permutation function by applying a sequence of rounds that transform the internal state variables.
    /// </summary>
    /// <param name="numberOfRounds">
    /// The number of rounds to execute. If set to 12, additional rounds are performed with specific constants to enhance the security of the transformation.
    /// </param>
    /// <remarks>
    /// In the Ascon cryptographic algorithm, the permutation function <c>P</c> transforms the internal state over multiple rounds.
    /// This method applies a set of round constants, each of which alters the state variables (<c>x0</c>, <c>x1</c>, <c>x2</c>, <c>x3</c>, <c>x4</c>) differently,
    /// ensuring that the transformation introduces non-linearity and diffusion, which are essential for cryptographic security.
    /// <br/><br/>
    /// When <paramref name="numberOfRounds"/> is set to 12, the method first applies four unique round constants.
    /// Afterward, it applies a fixed set of six additional constants regardless of the number of rounds.
    /// </remarks>
    private void P(int numberOfRounds)
    {
        if (numberOfRounds == 12)
        {
            Round(0xf0UL);
            Round(0xe1UL);
            Round(0xd2UL);
            Round(0xc3UL);
        }

        Round(0xb4UL);
        Round(0xa5UL);

        Round(0x96UL);
        Round(0x87UL);
        Round(0x78UL);
        Round(0x69UL);
        Round(0x5aUL);
        Round(0x4bUL);
    }

    /// <summary>
    /// Executes a single round of the cryptographic permutation function, transforming the internal state
    /// variables <c>x0</c>, <c>x1</c>, <c>x2</c>, <c>x3</c>, and <c>x4</c> using XOR, AND, and NOT operations, along with circular bit rotations.
    /// This function is designed to introduce diffusion and non-linearity into the state for cryptographic security.
    /// </summary>
    /// <param name="circles">
    /// A 64-bit unsigned integer constant that influences the round's transformation. Each round uses a unique value of this constant
    /// to ensure that the transformation applied to the state differs for each round.
    /// </param>
    /// <remarks>
    /// The <c>Round</c> function uses a series of bitwise operations (XOR, AND, NOT) and circular bit rotations to mix
    /// the internal state. Each transformation step introduces non-linearity and ensures that small changes in the input or state
    /// variables propagate widely across the internal state, enhancing the security of the cryptographic process.
    /// <br/><br/>
    /// The round constant (<paramref name="circles"/>) plays a crucial role in altering the state at each round, ensuring
    /// that each round contributes uniquely to the overall cryptographic transformation. Circular rotations are applied using
    /// <see cref="LongUtils.RotateRight(ulong, int)"/> to spread bits throughout the 64-bit word.
    /// </remarks>
    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    private void Round(ulong circles)
    {
        // Step 1: Perform XOR and AND operations to mix inputs and state variables
        var t0 = x0 ^ x1 ^ x2 ^ x3 ^ circles ^ (x1 & (x0 ^ x2 ^ x4 ^ circles));
        var t1 = x0 ^ x2 ^ x3 ^ x4 ^ circles ^ ((x1 ^ x2 ^ circles) & (x1 ^ x3));
        var t2 = x1 ^ x2 ^ x4 ^ circles ^ (x3 & x4);
        var t3 = x0 ^ x1 ^ x2 ^ circles ^ (~x0 & (x3 ^ x4));
        var t4 = x1 ^ x3 ^ x4 ^ ((x0 ^ x4) & x1);

        // Step 2: Apply circular right shifts and update the internal state variables
        x0 = t0 ^ LongUtils.RotateRight(t0, 19) ^ LongUtils.RotateRight(t0, 28);
        x1 = t1 ^ LongUtils.RotateRight(t1, 39) ^ LongUtils.RotateRight(t1, 61);
        x2 = ~(t2 ^ LongUtils.RotateRight(t2, 1) ^ LongUtils.RotateRight(t2, 6));
        x3 = t3 ^ LongUtils.RotateRight(t3, 10) ^ LongUtils.RotateRight(t3, 17);
        x4 = t4 ^ LongUtils.RotateRight(t4, 7) ^ LongUtils.RotateRight(t4, 41);
    }
}