Geralt
  • Introduction
  • Random data
  • Constant time
  • Secure memory
  • Encoding
  • Padding
  • Hashing
  • Message authentication
  • Password hashing
  • Key derivation
  • Authenticated encryption
    • Stream and file encryption
    • AEGIS-128L
    • AEGIS-256
    • ChaCha20-Poly1305
    • XChaCha20-Poly1305
  • Key exchange
  • Digital signatures
  • Advanced
    • Validation
    • Concat
    • ChaCha20
    • XChaCha20
    • HChaCha20
    • Poly1305
    • Ed25519 to X25519
Powered by GitBook
On this page
  • Purpose
  • Usage
  • ComputeTag
  • VerifyTag
  • IncrementalPoly1305
  • Constants
  • Notes
  1. Advanced

Poly1305

Last updated 5 months ago

Purpose

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 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

tag has a length not equal to TagSize.

oneTimeKey has a length not equal to KeySize.

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

tag has a length not equal to TagSize.

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

oneTimeKey has a length not equal to KeySize.

tag has a length not equal to TagSize.

The tag could not be computed.

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

The object has been disposed.

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).

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.

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

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.

Poly1305
BLAKE2b
ArgumentOutOfRangeException
ArgumentOutOfRangeException
CryptographicException
ArgumentOutOfRangeException
ArgumentOutOfRangeException
ArgumentOutOfRangeException
ArgumentOutOfRangeException
CryptographicException
InvalidOperationException
ObjectDisposedException
BLAKE2b
BLAKE2b