poly1305

README

The poly1305 message authentication code

Poly1305 is a fast, one-time authentication function created by Daniel J. Bernstein.
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.

Installation

Install in your GOPATH: go get -u github.com/aead/poly1305

Requirements

All Go versions >= 1.7 are supported.

Performance

AMD64

Hardware: Intel i7-6500U 2.50GHz x 2
System: Linux Ubuntu 16.04 - kernel: 4.4.0-62-generic
Go version: 1.8.0

AVX2

name                 speed              cpb
Sum_64-4             1.60GB/s ± 0%      1.39
Sum_256-4            2.32GB/s ± 1%      1.00 
Sum_1K-4             3.61GB/s ± 1%      0.65 
Sum_8K-4             4.20GB/s ± 1%      0.55
Write_64-4           2.04GB/s ± 0%      1.14
Write_256-4          3.50GB/s ± 2%      0.67
Write_1K-4           4.08GB/s ± 2%      0.57
Write_8K-4           4.25GB/s ± 2%      0.55

x64

name                 speed              cpb
Sum_64-4             1.60GB/s ± 1%      1.46
Sum_256-4            2.11GB/s ± 3%      1.10
Sum_1K-4             2.35GB/s ±13%      0.99
Sum_8K-4             2.47GB/s ±13%      0.94
Write_64-4           1.81GB/s ± 5%      1.29
Write_256-4          2.24GB/s ± 4%      1.04   
Write_1K-4           2.55GB/s ± 0%      0.91
Write_8K-4           2.63GB/s ± 0%      0.88

Documentation

Overview

Package poly1305 implements Poly1305 one-time message authentication code defined in RFC 7539..

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.

Index

• Constants
• func Sum(msg []byte, key [32]byte) [TagSize]byte
• func Verify(mac *[TagSize]byte, msg []byte, key [32]byte) bool
• type Hash
  • func New(key [32]byte) *Hash
  • func (h *Hash) Size() int
  • func (h *Hash) Sum(b []byte) []byte
  • func (h *Hash) Write(msg []byte) (int, error)

Constants

const TagSize = 16

TagSize is the size of the poly1305 authentication tag in bytes.

Functions

func Sum

func Sum(msg []byte, key [32]byte) [TagSize]byte

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

func Verify

func Verify(mac *[TagSize]byte, msg []byte, key [32]byte) bool

Verify returns true if and only if the mac is a valid authenticator for msg with the given key.

Types

type Hash

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

Hash implements the poly1305 authenticator. Poly1305 cannot be used like common hash.Hash implementations, because using a poly1305 key twice breaks its security.

func New

func New(key [32]byte) *Hash

New returns a Hash computing the poly1305 sum. Notice that Poly1305 is insecure if one key is used twice.

func (*Hash) Size

func (h *Hash) Size() int

Size returns the number of bytes Sum will append.

func (*Hash) Sum

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

Sum appends the Poly1305 hash of the previously processed data to b and returns the resulting slice. It is safe to call this function multiple times.

func (*Hash) Write

func (h *Hash) Write(msg []byte) (int, error)

Write adds more data to the running Poly1305 hash. This function should return a non-nil error if a call to Write happens after a call to Sum. So it is not possible to compute the checksum and than add more data.