Table of Contents

SipHash Class

Definition

Namespace
Bodu.Security.Cryptography
Assembly
Bodu.Security.Cryptography.dll
Package
Bodu.Security.Cryptography 1.2.0
Source
SipHash.cs

Base class for the SipHash family of keyed pseudorandom functions, a fast keyed hash designed by Aumasson and Bernstein for short input messages. See the official SipHash specification for details.

public abstract class SipHash : KeyedBlockHashAlgorithm, ICryptoTransform, IDisposable
Inheritance
SipHash
Implements
Derived
Inherited Members
Extension Methods

Examples

using var sipHash = new SipHash64
{
    Key = myKey,
    CompressionRounds = 4,
    FinalizationRounds = 8,
};
byte[] tag = sipHash.ComputeHash(message);

Remarks

SipHash is a keyed hash function that requires a 128-bit (16-byte) secret key. It mixes each input block into four 64-bit state variables (v0 through v3) using Add-Rotate-XOR (ARX) steps, and is designed to resist hash-flooding attacks against hash tables.

This base class is extended by:

  • SipHash64 produces a 64-bit hash output suitable for compact keyed checksums.
  • SipHash128 produces a 128-bit hash output offering increased collision resistance.

Each 64-bit input block is absorbed during a compression phase consisting of CompressionRounds rounds. Once all input has been processed, FinalizationRounds rounds are applied to produce the final digest. The defaults (c = 2, d = 4) correspond to the standard SipHash-2-4 parameterization.

When to choose SipHash. SipHash is the de-facto standard for protecting hash tables and bloom filters against collision-based denial-of-service attacks - Python, Ruby, Rust, Perl, and OpenBSD's stdlib all use it for that purpose. Pick SipHash64 when 64 bits is enough; pick SipHash128 when collision pressure on the tag width matters. For protocol-level message authentication over long messages prefer HMAC-SHA-256 or Blake2b-MAC. Do not use SipHash where the key may be exposed - its security target is hash-flooding resistance, not generic MAC strength.

Constructors

SipHash(int)

Initializes a new instance of the SipHash class with a specified hash size.

protected SipHash(int hashSize)

Parameters

hashSize int

The desired size of the final hash in bits. Supported values are 64 or 128.

Exceptions

ArgumentException

Thrown if hashSize is not supported.

Fields

KeySize

Length of the SipHash key is 128 bits (16 bytes).

public const int KeySize = 128

Field Value

int

MinCompressionRounds

The minimum number of compression rounds required by SipHash.

public const int MinCompressionRounds = 2

Field Value

int

MinFinalizationRounds

The minimum number of finalization rounds required by SipHash.

public const int MinFinalizationRounds = 4

Field Value

int

Properties

AlgorithmName

Gets the fully qualified algorithm name, including the variant and hash output size.

public override string AlgorithmName { get; }

Property Value

string

Remarks

Follows the convention "SipHash-c-d-x", where:

  • c: compression rounds
  • d: finalization rounds
  • x: output hash size in bits

CanReuseTransform

Gets a value indicating whether the current transform can be reused.

public override bool CanReuseTransform { get; }

Property Value

bool

Always true.

CanTransformMultipleBlocks

When overridden in a derived class, gets a value indicating whether multiple blocks can be transformed.

public override bool CanTransformMultipleBlocks { get; }

Property Value

bool

true if multiple blocks can be transformed; otherwise, false.

CompressionRounds

Gets or sets the number of compression rounds applied to each input block during the SipHash computation.

public int CompressionRounds { get; set; }

Property Value

int

A positive integer greater than or equal to MinCompressionRounds. The default is 2.

Remarks

Compression rounds are performed for every 8-byte message block before finalization. Increasing this value improves diffusion and resistance to hash-flooding attacks, but also increases computation time.

Exceptions

ArgumentOutOfRangeException

Thrown when the assigned value is less than MinCompressionRounds.

ObjectDisposedException

Thrown if the algorithm instance has been disposed.

CryptographicUnexpectedOperationException

Thrown if the hash computation has already begun and the property is modified mid-operation.

FinalizationRounds

Gets or sets the number of finalization rounds executed after all message blocks have been absorbed.

public int FinalizationRounds { get; set; }

Property Value

int

A positive integer greater than or equal to MinFinalizationRounds. The default is 4.

Remarks

Finalization rounds strengthen the avalanche effect after all input is processed. Increasing this value improves security at the cost of additional computation during final hash derivation.

Exceptions

ArgumentOutOfRangeException

Thrown when the assigned value is less than MinFinalizationRounds.

ObjectDisposedException

Thrown if the algorithm instance has been disposed.

CryptographicUnexpectedOperationException

Thrown if the hash computation has already begun and the property is modified mid-operation.

Methods

Dispose(bool)

Releases the unmanaged resources used by the algorithm and clears the key from memory.

protected override void Dispose(bool disposing)

Parameters

disposing bool

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

Remarks

Ensures all internal secrets are overwritten with zeros before releasing resources.

OnKeyChanged()

Rebuilds the internal SipHash state vectors from the current key whenever the key is assigned or the instance is re-initialized.

protected override void OnKeyChanged()

Remarks

XORs the key halves with the SipHash initial constants, then applies the SipHash-128 finalization tweak if required.

PadBlock(ReadOnlySpan<byte>, ulong, Span<byte>)

Produces the SipHash final padding block: copies the residual 0-7 bytes into an 8-byte buffer and places the low byte of messageLength into the last slot.

protected override int PadBlock(ReadOnlySpan<byte> block, ulong messageLength, Span<byte> destination)

Parameters

block ReadOnlySpan<byte>

The residual input bytes; length must be in [0..7].

messageLength ulong

The total processed message length in bytes. Only the low byte is used per the SipHash specification.

destination Span<byte>

The span receiving the padded block or blocks; at least two blocks long.

Returns

int

The padded 8-byte block.

Exceptions

ArgumentOutOfRangeException

block is longer than 7 bytes.

ProcessBlock(ReadOnlySpan<byte>)

Processes a single 64-bit block of data using SipHash compression.

protected override void ProcessBlock(ReadOnlySpan<byte> block)

Parameters

block ReadOnlySpan<byte>

The 64-bit block to process.

Remarks

Updates internal state using Bodu.Security.Cryptography.SipHash.PerformSipRounds(System.Int32) and XOR operations.

ProcessFinalBlock()

Finalizes the hash computation and produces the output hash value.

protected override byte[] ProcessFinalBlock()

Returns

byte[]

A byte array containing the final hash value (8 or 16 bytes).

Remarks

Combines all partial input and applies the finalization round logic based on the configured output size.

Applies to

ProductVersions
.NET8, 10

See Also

SipHash64
SipHash128