poly1305

Documentation

Overview

Package poly1305 implements Poly1305 one-time message authentication code as specified in https://cr.yp.to/mac/poly1305-20050329.pdf.

Poly1305 is a fast, one-time authentication function. It is infeasible for an attacker to generate an authenticator for a message without the key. However, a key must only be used for a single message. Authenticating two different messages with the same key allows an attacker to forge authenticators for other messages with the same key.

Poly1305 was originally coupled with AES in order to make Poly1305-AES. AES was used with a fixed key in order to generate one-time keys from an nonce. However, in this package AES isn't used and the one-time key is specified directly.

Deprecated: Poly1305 as implemented by this package is a cryptographic building block that is not safe for general purpose use. For encryption, use the full ChaCha20-Poly1305 construction implemented by github.com/dagood/x/crypto/chacha20poly1305. For authentication, use a general purpose MAC such as HMAC implemented by crypto/hmac.

Index

• Constants
• func Sum(out *[16]byte, m []byte, key *[32]byte)
• func Verify(mac *[16]byte, m []byte, key *[32]byte) bool
• type MAC
  • func New(key *[32]byte) *MAC
  • func (h *MAC) Size() int
  • func (h *MAC) Sum(b []byte) []byte
  • func (h *MAC) Verify(expected []byte) bool
  • func (h *MAC) Write(p []byte) (n int, err error)

Constants

const TagSize = 16

TagSize is the size, in bytes, of a poly1305 authenticator.

For use with github.com/dagood/x/crypto/chacha20poly1305, chacha20poly1305.Overhead can be used instead.

Functions

func Sum

func Sum(out *[16]byte, m []byte, key *[32]byte)

Sum generates an authenticator for msg using a one-time key and puts the 16-byte result into out. Authenticating two different messages with the same key allows an attacker to forge messages at will.

func Verify

func Verify(mac *[16]byte, m []byte, key *[32]byte) bool

Verify returns true if mac is a valid authenticator for m with the given key.

Types

type MAC

type MAC struct {
	// contains filtered or unexported fields
}

MAC is an io.Writer computing an authentication tag of the data written to it.

MAC cannot be used like common hash.Hash implementations, because using a poly1305 key twice breaks its security. Therefore writing data to a running MAC after calling Sum or Verify causes it to panic.

func New

func New(key *[32]byte) *MAC

New returns a new MAC computing an authentication tag of all data written to it with the given key. This allows writing the message progressively instead of passing it as a single slice. Common users should use the Sum function instead.

The key must be unique for each message, as authenticating two different messages with the same key allows an attacker to forge messages at will.

func (*MAC) Size

func (h *MAC) Size() int

Size returns the number of bytes Sum will return.

func (*MAC) Sum

func (h *MAC) Sum(b []byte) []byte

Sum computes the authenticator of all data written to the message authentication code.

func (*MAC) Verify

func (h *MAC) Verify(expected []byte) bool

Verify returns whether the authenticator of all data written to the message authentication code matches the expected value.

func (*MAC) Write

func (h *MAC) Write(p []byte) (n int, err error)

Write adds more data to the running message authentication code. It never returns an error.

It must not be called after the first call of Sum or Verify.