poly1305

README

poly1305

A Go wrapper of the poly1305-donna MAC library, using the public domain, SSE-optimized C implementation.

For documentation, check godoc.

Documentation

Overview

Package poly1305 provides a Go wrapper around floodyberry's optimized implementation of Poly1305. Poly1305 is a message authentication code (MAC) designed to meet the standard notion of unforgeability after a single message. After the sender authenticates one message, an attacker cannot find authenticators for any other messages. The sender MUST NOT use Poly1305 to authenticate more than one message under the same key. Authenticators for two messages under the same key should be expected to reveal enough information to allow forgeries of authenticators on other messages.

Index

• Constants
• Variables
• func New(key []byte) (hash.Hash, error)

Examples

• New

Constants

const (
	// KeySize is the length of Poly1305 keys, in bytes.
	KeySize = 32
	// BlockSize is the length of Poly1305 blocks, in bytes.
	BlockSize = 16
	// Size is the length of Poly1305 digests, in bytes.
	Size = 16
)

Variables

var (
	// ErrInvalidKey is returned when the provided key is not 256 bits long.
	ErrInvalidKey = errors.New("poly1305: invalid key length")
)

Functions

func New

func New(key []byte) (hash.Hash, error)

New creates and returns a keyed Hash implementation. The key argument must be 256 bits long, the value of which must only be used once.

Example

// A message for which we'd like to ensure authenticity.
message := []byte("A message which must be authentic.")

// NEVER USE THE SAME KEY TWICE. A critical aspect of Poly1305's design is
// that if you use the same key twice for two messages, an attacker can
// recover the key and forge messages. Poly1305 is generally assumed to be
// used in combination with an encryption algorithm (e.g., ChaCha20), which
// also requires a nonce. The Poly1305 key can be derived from the
// encryption algorithm's key stream, in this case, as long as the algorithm
// is used in a construction which requires a unique nonce or IV
// (e.g., ChaCha20).
key := make([]byte, KeySize)
_, err := io.ReadFull(rand.Reader, key)
if err != nil {
	panic(err)
}

// The sender calculates the MAC for the message it sends.
sender, err := New(key)
if err != nil {
	panic(err)
}
sender.Write(message)
sent := sender.Sum(nil)

// The receiver calculates the MAC for the message it received.
receiver, err := New(key)
if err != nil {
	panic(err)
}
receiver.Write(message)
received := receiver.Sum(nil)

// The receiver compares the two MACs (using a constant-time comparison
// algorithm to prevent timing attacks), and iff they match is assured of
// the message's authenticity.
if subtle.ConstantTimeCompare(sent, received) != 1 {
	panic("Invalid message! Don't decrypt, process, or look at it.")
}