redefine the API (backward breaking change)

This change makes it possible to include poly1305 in
https://github.com/aead/poly.

Remove go master from travis

Author: Andreas Auernhammer

.travis.yml

@@ -5,7 +5,6 @@ go:
   - 1.6
   - 1.7
   - 1.8
-  - master
 
 env:
   - TRAVIS_GOARCH=amd64

poly1305.go

@@ -24,8 +24,7 @@ var errWriteAfterSum = errors.New("checksum already computed - adding more data
 
 // Verify returns true if and only if the mac is a valid authenticator
 // for msg with the given key.
-func Verify(mac *[TagSize]byte, msg []byte, key *[32]byte) bool {
-	var sum [TagSize]byte
-	Sum(&sum, msg, key)
+func Verify(mac *[TagSize]byte, msg []byte, key [32]byte) bool {
+	sum := Sum(msg, key)
 	return subtle.ConstantTimeCompare(sum[:], mac[:]) == 1
 }

poly1305_amd64.go

@@ -20,32 +20,32 @@ func update(state *[7]uint64, msg []byte)
 //go:noescape
 func finalize(tag *[TagSize]byte, state *[7]uint64)
 
-// 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 Sum(out *[TagSize]byte, msg []byte, key *[32]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 Sum(msg []byte, key [32]byte) [TagSize]byte {
 	if len(msg) == 0 {
 		msg = []byte{}
 	}
-
+	var out [TagSize]byte
 	var state [7]uint64 // := uint64{ h0, h1, h2, r0, r1, pad0, pad1 }
-	initialize(&state, key)
+	initialize(&state, &key)
 	update(&state, msg)
-	finalize(out, &state)
+	finalize(&out, &state)
+	return out
 }
 
-// New returns a hash.Hash computing the poly1305 sum.
+// New returns a Hash computing the poly1305 sum.
 // Notice that Poly1305 is insecure if one key is used twice.
-func New(key *[32]byte) *Hash {
+func New(key [32]byte) *Hash {
 	p := new(Hash)
-	initialize(&(p.state), key)
+	initialize(&(p.state), &key)
 	return p
 }
 
-// Hash implements a Poly1305 writer interface.
+// Hash implements the poly1305 authenticator.
 // Poly1305 cannot be used like common hash.Hash implementations,
 // because of using a poly1305 key twice breaks its security.
-// So poly1305.Hash does not support some kind of reset.
 type Hash struct {
 	state [7]uint64 // := uint64{ h0, h1, h2, r0, r1, pad0, pad1 }
 
@@ -54,11 +54,13 @@ type Hash struct {
 	done bool
 }
 
+// Size returns the number of bytes Sum will append.
+func (p *Hash) Size() int { return TagSize }
+
 // Write adds more data to the running Poly1305 hash.
-// This function returns an non-nil error, if a call
-// to Write happens after the hash's Sum function was
-// called. So it's not possible to compute the checksum
-// and than add more data.
+// 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.
 func (p *Hash) Write(msg []byte) (int, error) {
 	if p.done {
 		return 0, errWriteAfterSum
@@ -89,16 +91,18 @@ func (p *Hash) Write(msg []byte) (int, error) {
 	return n, nil
 }
 
-// Sum computes the Poly1305 checksum of the previously
-// processed data and writes it to out. It is legal to
-// call this function more than one time.
-func (p *Hash) Sum(out *[TagSize]byte) {
+// Sum appends the Pol1305 hash of the previously
+// processed data to b and returns the resulting slice.
+// It is safe to call this function multiple times.
+func (p *Hash) Sum(b []byte) []byte {
+	var out [TagSize]byte
 	state := p.state
 
 	if p.off > 0 {
 		update(&state, p.buf[:p.off])
 	}
 
-	finalize(out, &state)
+	finalize(&out, &state)
 	p.done = true
+	return append(b, out[:]...)
 }

poly1305_ref.go

@@ -13,39 +13,39 @@ const (
 	finalBlock = uint32(0)
 )
 
-// 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 Sum(out *[TagSize]byte, msg []byte, key *[32]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 Sum(msg []byte, key [32]byte) [TagSize]byte {
 	var (
 		h, r  [5]uint32
 		s     [4]uint32
 		block [TagSize]byte
 		off   int
 	)
+	var out [TagSize]byte
 
-	initialize(&r, &s, key)
+	initialize(&r, &s, &key)
 
 	n := len(msg) & (^(TagSize - 1))
 	if n > 0 {
 		update(msg[:n], msgBlock, &h, &r)
 		msg = msg[n:]
 	}
-
 	if len(msg) > 0 {
 		off += copy(block[:], msg)
 		block[off] = 1
 		update(block[:], finalBlock, &h, &r)
 	}
-
-	finalize(out, &h, &s)
+	finalize(&out, &h, &s)
+	return out
 }
 
 // New returns a hash.Hash computing the poly1305 sum.
 // Notice that Poly1305 is insecure if one key is used twice.
-func New(key *[32]byte) *Hash {
+func New(key [32]byte) *Hash {
 	p := new(Hash)
-	initialize(&(p.r), &(p.s), key)
+	initialize(&(p.r), &(p.s), &key)
 	return p
 }
 
@@ -62,11 +62,13 @@ type Hash struct {
 	done bool
 }
 
+// Size returns the number of bytes Sum will append.
+func (p *Hash) Size() int { return TagSize }
+
 // Write adds more data to the running Poly1305 hash.
-// This function returns an non-nil error, if a call
-// to Write happens after the hash's Sum function was
-// called. So it's not possible to compute the checksum
-// and than add more data.
+// 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.
 func (p *Hash) Write(msg []byte) (int, error) {
 	if p.done {
 		return 0, errWriteAfterSum
@@ -97,10 +99,11 @@ func (p *Hash) Write(msg []byte) (int, error) {
 	return n, nil
 }
 
-// Sum computes the Poly1305 checksum of the previously
-// processed data and writes it to out. It is legal to
-// call this function more than one time.
-func (p *Hash) Sum(out *[TagSize]byte) {
+// Sum appends the Pol1305 hash of the previously
+// processed data to b and returns the resulting slice.
+// It is safe to call this function multiple times.
+func (p *Hash) Sum(b []byte) []byte {
+	var out [TagSize]byte
 	h := p.h
 
 	if p.off > 0 {
@@ -111,8 +114,9 @@ func (p *Hash) Sum(out *[TagSize]byte) {
 		update(buf[:], finalBlock, &h, &(p.r))
 	}
 
-	finalize(out, &h, &(p.s))
+	finalize(&out, &h, &(p.s))
 	p.done = true
+	return append(b, out[:]...)
 }
 
 func initialize(r *[5]uint32, s *[4]uint32, key *[32]byte) {

poly1305_test.go

@@ -57,44 +57,41 @@ var vectors = []struct {
 }
 
 func TestVectors(t *testing.T) {
-	var out [16]byte
 	var key [32]byte
 
 	for i, v := range vectors {
 		msg := v.msg
 		copy(key[:], v.key)
 
-		Sum(&out, msg, &key)
+		out := Sum(msg, key)
 		if !bytes.Equal(out[:], v.tag) {
 			t.Errorf("Test vector %d : got: %x expected: %x", i, out[:], v.tag)
 		}
 
-		h := New(&key)
+		h := New(key)
 		h.Write(msg)
-		h.Sum(&out)
-		if !bytes.Equal(out[:], v.tag) {
-			t.Errorf("Test vector %d : got: %x expected: %x", i, out[:], v.tag)
+		tag := h.Sum(nil)
+		if !bytes.Equal(tag[:], v.tag) {
+			t.Errorf("Test vector %d : got: %x expected: %x", i, tag[:], v.tag)
 		}
 
 		var mac [16]byte
 		copy(mac[:], v.tag)
-		if !Verify(&mac, msg, &key) {
+		if !Verify(&mac, msg, key) {
 			t.Errorf("Test vector %d : Verify failed", i)
 		}
 	}
 }
 
 func TestWriteAfterSum(t *testing.T) {
-	var sum [TagSize]byte
-
 	msg := make([]byte, 64)
 	for i := range msg {
-		h := New(new([32]byte))
+		h := New([32]byte{})
 
 		if _, err := h.Write(msg[:i]); err != nil {
 			t.Fatalf("Iteration %d: poly1305.Hash returned unexpected error: %s", i, err)
 		}
-		h.Sum(&sum)
+		h.Sum(nil)
 		if _, err := h.Write(nil); err == nil {
 			t.Fatalf("Iteration %d: poly1305.Hash returned no error for write after sum", i)
 		}
@@ -107,7 +104,7 @@ func TestWrite(t *testing.T) {
 		key[i] = byte(i)
 	}
 
-	h := New(&key)
+	h := New(key)
 
 	var msg1 []byte
 	msg0 := make([]byte, 64)
@@ -116,11 +113,10 @@ func TestWrite(t *testing.T) {
 		msg1 = append(msg1, msg0[:i]...)
 	}
 
-	var tag0, tag1 [TagSize]byte
-	h.Sum(&tag0)
-	Sum(&tag1, msg1, &key)
+	tag0 := h.Sum(nil)
+	tag1 := Sum(msg1, key)
 
-	if tag0 != tag1 {
+	if !bytes.Equal(tag0[:], tag1[:]) {
 		t.Fatalf("Sum differ from poly1305.Sum\n Sum: %s \n poly1305.Sum: %s", hex.EncodeToString(tag0[:]), hex.EncodeToString(tag1[:]))
 	}
 }
@@ -138,7 +134,6 @@ func BenchmarkWriteUnaligned_1K(b *testing.B) { benchmarkWrite(b, 1024, true) }
 
 func benchmarkSum(b *testing.B, size int, unalign bool) {
 	var key [32]byte
-	var tag [16]byte
 
 	msg := make([]byte, size)
 	if unalign {
@@ -148,13 +143,13 @@ func benchmarkSum(b *testing.B, size int, unalign bool) {
 	b.SetBytes(int64(size))
 	b.ResetTimer()
 	for i := 0; i < b.N; i++ {
-		Sum(&tag, msg, &key)
+		Sum(msg, key)
 	}
 }
 
 func benchmarkWrite(b *testing.B, size int, unalign bool) {
 	var key [32]byte
-	h := New(&key)
+	h := New(key)
 
 	msg := make([]byte, size)
 	if unalign {