Poly1305

Purpose

Poly1305 is a fast one-time message authentication code (MAC). It takes a 256-bit key that can only be used once and produces a 128-bit tag.

You almost definitely want BLAKE2b instead. Poly1305 is easy to misuse and less secure due to the short tag length.

Usage

ComputeTag

Fills a span with a tag computed from a message and a one-time key.

Poly1305.ComputeTag(Span<byte> tag, ReadOnlySpan<byte> message, ReadOnlySpan<byte> oneTimeKey)

Exceptions

ArgumentOutOfRangeException

tag has a length not equal to TagSize.

ArgumentOutOfRangeException

oneTimeKey has a length not equal to KeySize.

CryptographicException

The tag could not be computed.

VerifyTag

Verifies that a tag is correct in constant time for a given message and one-time key. It returns true if the tag is valid and false otherwise.

Poly1305.VerifyTag(ReadOnlySpan<byte> tag, ReadOnlySpan<byte> message, ReadOnlySpan<byte> oneTimeKey)

Exceptions

ArgumentOutOfRangeException

tag has a length not equal to TagSize.

ArgumentOutOfRangeException

oneTimeKey has a length not equal to KeySize.

IncrementalPoly1305

Provides support for computing a tag from several messages and a one-time key.

using var poly1305 = new IncrementalPoly1305(ReadOnlySpan<byte> oneTimeKey);
poly1305.Update(ReadOnlySpan<byte> message1);
poly1305.Update(ReadOnlySpan<byte> message2);
// Compute
poly1305.Finalize(Span<byte> tag);
// Or verify
bool valid = poly1305.FinalizeAndVerify(ReadOnlySpan<byte> tag);

// Avoid another using statement
// WARNING: Do NOT reuse the same key
poly1305.Reinitialize(ReadOnlySpan<byte> differentOneTimeKey);
poly1305.Update(ReadOnlySpan<byte> message3);
poly1305.Finalize(Span<byte> tag);

Exceptions

ArgumentOutOfRangeException

oneTimeKey has a length not equal to KeySize.

ArgumentOutOfRangeException

tag has a length not equal to TagSize.

CryptographicException

The tag could not be computed.

InvalidOperationException

Cannot update after finalizing or finalize twice (without reinitializing).

Constants

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

public const int KeySize = 32;
public const int TagSize = 16;

Notes

Each key MUST be uniformly random, unpredictable, and unique. You MUST NOT reuse a key or use the same key for multiple purposes (e.g. encryption and Poly1305).

Do NOT use Poly1305 as a hash function or key derivation function (KDF). Use BLAKE2b.

Tags MUST be compared in constant time to avoid leaking information, so use the VerifyTag() or FinalizeAndVerify() function.​

Tags MUST NOT be truncated to minimise the opportunity for forgery.

BLAKE2b is strongly recommended over Poly1305 as a MAC because it has better security guarantees. Due to the 128-bit tag length, Poly1305 should only ever be used for online protocols and small messages.