Keccak-f[1600]

Purpose

Keccak-f[1600] is the largest variant of the Keccak-f permutation, which is the building block for the SHA-3 family and KangarooTwelve family of constructions. It has a 1600-bit state and can be used to construct hash functions, XOFs, MACs, KDFs, stream ciphers, and AEAD schemes.

This API is more dangerous than the others. It should only be used by advanced users who want to create custom constructions.

If you don't meet this criteria, please use .NET's SHA-3/SHAKE implementations or wait for libsodium to implement KangarooTwelve (KT128/KT256), which should be favoured over all other hash functions/XOFs at the time of writing.

Usage

IncrementalKeccakf1600

Provides access to the Keccak-f[1600] permutation. Setting the state to all-zero, absorbing (XORing) data into the state, permuting the state (with 24 or 12 rounds), and squeezing output from the state are supported.

The entire state can be accessed, permuting the state is a separate function, and there's no concept of finalization. This enables flexibility for different custom constructions.

You MUST define a secure rate/capacity size. The minimum capacity should be 256 bits for unkeyed hashing/collision resistance scenarios but can be reduced to 192 bits for keyed scenarios (if you don't care about collision resistance). This is because the attacker has less control in keyed modes.

Also, you MUST implement proper padding (e.g., pad10*1 or pad10*) and domain separation (e.g., XORing a constant after absorbing associated data before absorbing plaintext).

It is possible to do full-state keyed absorbing/squeezing, but this is not recommended because it's brittle.

// Initialize the state to all-zero
using var keccak = new IncrementalKeccakf1600();

// IMPORTANT: Pad/domain separate the message (not shown here)
// Process the message in blocks
foreach (var messageBlock in messageBlocks) {
    // Absorb (XOR) data into the state at offset (default of 0)
    keccak.XorBytes(messageBlock, offset);
    // Permute the state (full or half rounds)
    if (fullRounds) {
        keccak.Permute24(); // Like SHA-3/SHAKE
    }
    else {
        keccak.Permute12(); // Like TurboSHAKE
    }
}

// Squeeze output from the state (once or multiple blocks)
foreach (var outputBlock in output) {
    keccak.ExtractBytes(outputBlock, offset);
    // Permute the state (full or half rounds)
    if (fullRounds) {
        keccak.Permute24(); // Like SHA-3/SHAKE
    }
    else {
        keccak.Permute12(); // Like TurboSHAKE
    }
}

// Reset the state to all-zero
keccak.Reinitialize();

Exceptions

ArgumentOutOfRangeException

offset is less than 0 or greater than StateSize - 1.

ArgumentOutOfRangeException

bytes.Length + offset is greater than StateSize.

InvalidOperationException

Methods cannot be called from multiple threads simultaneously.

ObjectDisposedException

The object has been disposed.

Constants

These are used for validation and/or save you defining your own constants.

public const int StateSize = 200;

Notes

Keccak's strengths are explained here, and a list of third-party cryptanalysis can be found here.