[API Proposal]: XxHash128

[xoofx]

Background and motivation

Followup of the previous API proposal for XX3 64 bit #75948

The current XxHash3 implementation provides a 64 bit hash. But XXH3 128 is also quite useful for e.g fast content adressable storage scenarios.

This proposal is about adding a XxHash128 API and implementation.

API Proposal

namespace System.IO.Hashing;

public sealed partial class XxHash128 : NonCryptographicHashAlgorithm
{
    public XxHash128();
    public XxHash128(long seed);

    public static byte[] Hash(byte[] source);
    public static byte[] Hash(byte[] source, long seed);
    public static byte[] Hash(ReadOnlySpan<byte> source, long seed = 0);
    public static int Hash(ReadOnlySpan<byte> source, Span<byte> destination, long seed = 0);
    public static bool TryHash(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten, long seed = 0);

    // .NET 7+
    public static UInt128 HashToIntU128(ReadOnlySpan<byte> source, long seed = 0);
    public UInt128 GetCurrentHashAsIntU128();
}

API Usage

int bytesWritten = XxHash128.Hash(source, destination);

Alternative Designs

No response

Risks

No response

[ghost]

Tagging subscribers to this area: @dotnet/area-system-security, @vcsjones
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

Followup of the previous API proposal for XX3 64 bit #75948

The current XxHash3 implementation provides a 64 bit hash. But XXH3 128 is also quite useful for e.g fast content adressable storage scenarios.

This proposal is about adding a XxHash128 API and implementation.

API Proposal

namespace System.IO.Hashing;

public sealed partial class XxHash128 : NonCryptographicHashAlgorithm
{
    public XxHash128();
    public XxHash128(int seed);

    public static byte[] Hash(byte[] source);
    public static byte[] Hash(byte[] source, int seed);
    public static byte[] Hash(ReadOnlySpan<byte> source, int seed = 0);
    public static int Hash(ReadOnlySpan<byte> source, Span<byte> destination, int seed = 0);
    public static bool TryHash(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten, int seed = 0);
}

API Usage

int bytesWritten = XxHash128.Hash(source, destination);

Alternative Designs

No response

Risks

No response

Author:	xoofx
Assignees:	-
Labels:	api-suggestion, area-System.Security
Milestone:	-

[stephentoub]

Is it correct that the seeds are ints instead of longs?

[xoofx]

Is it correct that the seeds are ints instead of longs?

Indeed, it should be long, I have updated.

[stephentoub]

I've marked this as api-ready-for-review. I believe this is just a formality: we basically rubber-stamped this when reviewing XxHash3, saying we'd add XxHash128 if there was a demonstrated need, and the proposed API follows the same shape/pattern as all the other algorithms in the library.
cc: @bartonjs

[MihaZupan]

Moving this to 8.0 given that that is what XxHash3 was aimed at

[terrajobst]

Video

namespace System.IO.Hashing;

public sealed partial class XxHash128 : NonCryptographicHashAlgorithm
{
    public XxHash128();
    public XxHash128(long seed);

    public static byte[] Hash(byte[] source);
    public static byte[] Hash(byte[] source, long seed);
    public static byte[] Hash(ReadOnlySpan<byte> source, long seed = 0);
    public static int Hash(ReadOnlySpan<byte> source, Span<byte> destination, long seed = 0);
    public static bool TryHash(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten, long seed = 0);
}