Module poly1305 

Available on crate feature allow-non-fips only.

The Poly1305 Message Authentication Code

use wolf_crypto::mac::{Poly1305, poly1305::Key};

let key = Key::new([0u8; 32]);

let tag = Poly1305::new(key.as_ref())
    .aead_padding()
    .update(b"hello world")?
    .finalize();

let o_tag = Poly1305::new(key)
    .mac(b"Different message", ()).unwrap();

assert_eq!(
    tag, o_tag,
    "All of our coefficients are zero!"
);

let key = Key::new([42u8; 32]);

let tag = Poly1305::new(key.as_ref())
    .aead_padding_ct()
    .update_ct(b"thankfully this ")
    .update_ct(b"is only the case ")
    .update_ct(b"with a key of all zeroes.")
    .finalize(/* errors are accumulated in constant-time, so we handle them here */)?;

let o_tag = Poly1305::new(key.as_ref())
    .mac(b"thankfully this is only the case with a key of all zeroes.", ())?;

assert_eq!(tag, o_tag);

let bad_tag = Poly1305::new(key)
    .update(b"This tag will not be the same.")?
    .finalize();

assert_ne!(bad_tag, tag);

Note

The first test may be concerning, it is not. Poly1305 was originally designed to be paired with AES, this example only would take place if the cipher it is paired with is fundamentally broken. More explicitly, the cipher would need to be an identity function for the first 32 bytes, meaning not encrypt the first 32 bytes in any way shape or form.

The author of Poly1305 (Daniel J. Bernstein) also created Salsa20 (Snuffle 2005), and then ChaCha, which Poly1305 generally complements for authentication.

Security

Poly1305 is meant to be used with a one-time key, key reuse in Poly1305 can be devastating. When pairing with something like ChaCha20Poly1305 this requirement is handled via the discreteness of the initialization vector (more reason to never reuse initialization vectors).

If you are using Poly1305 directly, each discrete message you authenticate must leverage fresh key material.

Modules

state

Defines the various states that a Poly1305 instance can be in.

Structs

CtPoly1305

Provides a constant-time interface for updating the MAC computation, enhancing resistance against side-channel attacks.

CtPoly1305Aead

Provides a constant-time interface for updating the MAC computation, enhancing resistance against side-channel attacks.

Key

Represents a 32-byte secret key for Poly1305 and ChaCha20Poly1305.

KeyRef

A reference to a Key, allowing for efficient key handling without ownership.

Poly1305

The Poly1305 Message Authentication Code (MAC)

StreamPoly1305

Represents an ongoing streaming MAC computation, allowing incremental updates.

StreamPoly1305Aead

Represents an ongoing streaming MAC computation, allowing incremental updates.

Constants

KEY_SIZE

The size of the Poly1305 key in bytes.

Traits

GenericKey

A sealed trait for generic key types used in Poly1305.