poly1305: implement a subset of the hash.Hash interface

This CL adds the poly1305.MAC type which implements a subset of the hash.Hash interface. With MAC it is possible to compute an authentication tag of data without copying it into a single byte slice. This commit modifies the reference/generic and the AMD64 assembler but not the ARM/s390x implementation to support an io.Writer interface. Updates golang/go#25219 Change-Id: I7ee5a9eadd43387cf3cd887d734c625575eee47d Reviewed-on: https://go-review.googlesource.com/c/crypto/+/111335 Run-TryBot: Filippo Valsorda <[email protected]> TryBot-Result: Gobot Gobot <[email protected]> Reviewed-by: Filippo Valsorda <[email protected]>
golang · Mar 8, 2019 · c2843e0 · c2843e0
1 parent 8dd112b
commit c2843e0
Show file tree

Hide file tree

Showing 7 changed files with 322 additions and 92 deletions.
diff --git a/poly1305/mac_noasm.go b/poly1305/mac_noasm.go
@@ -0,0 +1,11 @@
+// Copyright 2018 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// +build !amd64 gccgo appengine
+
+package poly1305
+
+type mac struct{ macGeneric }
+
+func newMAC(key *[32]byte) mac { return mac{newMACGeneric(key)} }
diff --git a/poly1305/poly1305.go b/poly1305/poly1305.go
@@ -2,21 +2,19 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-/*
-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.
-*/
+// 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.
 package poly1305 // import "golang.org/x/crypto/poly1305"
 
 import "crypto/subtle"
@@ -31,3 +29,55 @@ func Verify(mac *[16]byte, m []byte, key *[32]byte) bool {
 	Sum(&tmp, m, key)
 	return subtle.ConstantTimeCompare(tmp[:], mac[:]) == 1
 }
+
+// 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 New(key *[32]byte) *MAC {
+	return &MAC{
+		mac:       newMAC(key),
+		finalized: false,
+	}
+}
+
+// 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 causes it to panic.
+type MAC struct {
+	mac // platform-dependent implementation
+
+	finalized bool
+}
+
+// Size returns the number of bytes Sum will return.
+func (h *MAC) Size() int { return TagSize }
+
+// 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.
+func (h *MAC) Write(p []byte) (n int, err error) {
+	if h.finalized {
+		panic("poly1305: write to MAC after Sum")
+	}
+	return h.mac.Write(p)
+}
+
+// Sum computes the authenticator of all data written to the
+// message authentication code.
+func (h *MAC) Sum(b []byte) []byte {
+	var mac [TagSize]byte
+	h.mac.Sum(&mac)
+	h.finalized = true
+	return append(b, mac[:]...)
+}
diff --git a/poly1305/poly1305_test.go b/poly1305/poly1305_test.go
@@ -100,7 +100,50 @@ func TestSumUnaligned(t *testing.T)        { testSum(t, true, Sum) }
 func TestSumGeneric(t *testing.T)          { testSum(t, false, sumGeneric) }
 func TestSumGenericUnaligned(t *testing.T) { testSum(t, true, sumGeneric) }
 
-func benchmark(b *testing.B, size int, unaligned bool) {
+func TestWriteGeneric(t *testing.T)          { testWriteGeneric(t, false) }
+func TestWriteGenericUnaligned(t *testing.T) { testWriteGeneric(t, true) }
+func TestWrite(t *testing.T)                 { testWrite(t, false) }
+func TestWriteUnaligned(t *testing.T)        { testWrite(t, true) }
+
+func testWriteGeneric(t *testing.T, unaligned bool) {
+	for i, v := range testData {
+		key := v.Key()
+		input := v.Input()
+		var out [16]byte
+
+		if unaligned {
+			input = unalignBytes(input)
+		}
+		h := newMACGeneric(&key)
+		h.Write(input[:len(input)/2])
+		h.Write(input[len(input)/2:])
+		h.Sum(&out)
+		if tag := v.Tag(); out != tag {
+			t.Errorf("%d: expected %x, got %x", i, tag[:], out[:])
+		}
+	}
+}
+
+func testWrite(t *testing.T, unaligned bool) {
+	for i, v := range testData {
+		key := v.Key()
+		input := v.Input()
+		var out [16]byte
+
+		if unaligned {
+			input = unalignBytes(input)
+		}
+		h := New(&key)
+		h.Write(input[:len(input)/2])
+		h.Write(input[len(input)/2:])
+		h.Sum(out[:0])
+		if tag := v.Tag(); out != tag {
+			t.Errorf("%d: expected %x, got %x", i, tag[:], out[:])
+		}
+	}
+}
+
+func benchmarkSum(b *testing.B, size int, unaligned bool) {
 	var out [16]byte
 	var key [32]byte
 	in := make([]byte, size)
@@ -114,11 +157,33 @@ func benchmark(b *testing.B, size int, unaligned bool) {
 	}
 }
 
-func Benchmark64(b *testing.B)          { benchmark(b, 64, false) }
-func Benchmark1K(b *testing.B)          { benchmark(b, 1024, false) }
-func Benchmark64Unaligned(b *testing.B) { benchmark(b, 64, true) }
-func Benchmark1KUnaligned(b *testing.B) { benchmark(b, 1024, true) }
-func Benchmark2M(b *testing.B)          { benchmark(b, 2097152, true) }
+func benchmarkWrite(b *testing.B, size int, unaligned bool) {
+	var key [32]byte
+	h := New(&key)
+	in := make([]byte, size)
+	if unaligned {
+		in = unalignBytes(in)
+	}
+	b.SetBytes(int64(len(in)))
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		h.Write(in)
+	}
+}
+
+func Benchmark64(b *testing.B)          { benchmarkSum(b, 64, false) }
+func Benchmark1K(b *testing.B)          { benchmarkSum(b, 1024, false) }
+func Benchmark2M(b *testing.B)          { benchmarkSum(b, 2*1024*1024, false) }
+func Benchmark64Unaligned(b *testing.B) { benchmarkSum(b, 64, true) }
+func Benchmark1KUnaligned(b *testing.B) { benchmarkSum(b, 1024, true) }
+func Benchmark2MUnaligned(b *testing.B) { benchmarkSum(b, 2*1024*1024, true) }
+
+func BenchmarkWrite64(b *testing.B)          { benchmarkWrite(b, 64, false) }
+func BenchmarkWrite1K(b *testing.B)          { benchmarkWrite(b, 1024, false) }
+func BenchmarkWrite2M(b *testing.B)          { benchmarkWrite(b, 2*1024*1024, false) }
+func BenchmarkWrite64Unaligned(b *testing.B) { benchmarkWrite(b, 64, true) }
+func BenchmarkWrite1KUnaligned(b *testing.B) { benchmarkWrite(b, 1024, true) }
+func BenchmarkWrite2MUnaligned(b *testing.B) { benchmarkWrite(b, 2*1024*1024, true) }
 
 func unalignBytes(in []byte) []byte {
 	out := make([]byte, len(in)+1)

diff --git a/poly1305/sum_amd64.go b/poly1305/sum_amd64.go
@@ -6,17 +6,63 @@
 
 package poly1305
 
-// This function is implemented in sum_amd64.s
 //go:noescape
-func poly1305(out *[16]byte, m *byte, mlen uint64, key *[32]byte)
+func initialize(state *[7]uint64, key *[32]byte)
+
+//go:noescape
+func update(state *[7]uint64, msg []byte)
+
+//go:noescape
+func finalize(tag *[TagSize]byte, state *[7]uint64)
 
 // Sum generates an authenticator for m 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 *[16]byte, m []byte, key *[32]byte) {
-	var mPtr *byte
-	if len(m) > 0 {
-		mPtr = &m[0]
+	h := newMAC(key)
+	h.Write(m)
+	h.Sum(out)
+}
+
+func newMAC(key *[32]byte) (h mac) {
+	initialize(&h.state, key)
+	return
+}
+
+type mac struct {
+	state [7]uint64 // := uint64{ h0, h1, h2, r0, r1, pad0, pad1 }
+
+	buffer [TagSize]byte
+	offset int
+}
+
+func (h *mac) Write(p []byte) (n int, err error) {
+	n = len(p)
+	if h.offset > 0 {
+		remaining := TagSize - h.offset
+		if n < remaining {
+			h.offset += copy(h.buffer[h.offset:], p)
+			return n, nil
+		}
+		copy(h.buffer[h.offset:], p[:remaining])
+		p = p[remaining:]
+		h.offset = 0
+		update(&h.state, h.buffer[:])
+	}
+	if nn := len(p) - (len(p) % TagSize); nn > 0 {
+		update(&h.state, p[:nn])
+		p = p[nn:]
+	}
+	if len(p) > 0 {
+		h.offset += copy(h.buffer[h.offset:], p)
+	}
+	return n, nil
+}
+
+func (h *mac) Sum(out *[16]byte) {
+	state := h.state
+	if h.offset > 0 {
+		update(&state, h.buffer[:h.offset])
 	}
-	poly1305(out, mPtr, uint64(len(m)), key)
+	finalize(out, &state)
 }
diff --git a/poly1305/sum_amd64.s b/poly1305/sum_amd64.s
@@ -58,20 +58,17 @@ DATA ·poly1305Mask<>+0x00(SB)/8, $0x0FFFFFFC0FFFFFFF
 DATA ·poly1305Mask<>+0x08(SB)/8, $0x0FFFFFFC0FFFFFFC
 GLOBL ·poly1305Mask<>(SB), RODATA, $16
 
-// func poly1305(out *[16]byte, m *byte, mlen uint64, key *[32]key)
-TEXT ·poly1305(SB), $0-32
-	MOVQ out+0(FP), DI
-	MOVQ m+8(FP), SI
-	MOVQ mlen+16(FP), R15
-	MOVQ key+24(FP), AX
-
-	MOVQ 0(AX), R11
-	MOVQ 8(AX), R12
-	ANDQ ·poly1305Mask<>(SB), R11   // r0
-	ANDQ ·poly1305Mask<>+8(SB), R12 // r1
-	XORQ R8, R8                    // h0
-	XORQ R9, R9                    // h1
-	XORQ R10, R10                  // h2
+// func update(state *[7]uint64, msg []byte)
+TEXT ·update(SB), $0-32
+	MOVQ state+0(FP), DI
+	MOVQ msg_base+8(FP), SI
+	MOVQ msg_len+16(FP), R15
+
+	MOVQ 0(DI), R8   // h0
+	MOVQ 8(DI), R9   // h1
+	MOVQ 16(DI), R10 // h2
+	MOVQ 24(DI), R11 // r0
+	MOVQ 32(DI), R12 // r1
 
 	CMPQ R15, $16
 	JB   bytes_between_0_and_15
@@ -109,16 +106,42 @@ flush_buffer:
 	JMP  multiply
 
 done:
-	MOVQ    R8, AX
-	MOVQ    R9, BX
+	MOVQ R8, 0(DI)
+	MOVQ R9, 8(DI)
+	MOVQ R10, 16(DI)
+	RET
+
+// func initialize(state *[7]uint64, key *[32]byte)
+TEXT ·initialize(SB), $0-16
+	MOVQ state+0(FP), DI
+	MOVQ key+8(FP), SI
+
+	// state[0...7] is initialized with zero
+	MOVOU 0(SI), X0
+	MOVOU 16(SI), X1
+	MOVOU ·poly1305Mask<>(SB), X2
+	PAND  X2, X0
+	MOVOU X0, 24(DI)
+	MOVOU X1, 40(DI)
+	RET
+
+// func finalize(tag *[TagSize]byte, state *[7]uint64)
+TEXT ·finalize(SB), $0-16
+	MOVQ tag+0(FP), DI
+	MOVQ state+8(FP), SI
+
+	MOVQ    0(SI), AX
+	MOVQ    8(SI), BX
+	MOVQ    16(SI), CX
+	MOVQ    AX, R8
+	MOVQ    BX, R9
 	SUBQ    $0xFFFFFFFFFFFFFFFB, AX
 	SBBQ    $0xFFFFFFFFFFFFFFFF, BX
-	SBBQ    $3, R10
+	SBBQ    $3, CX
 	CMOVQCS R8, AX
 	CMOVQCS R9, BX
-	MOVQ    key+24(FP), R8
-	ADDQ    16(R8), AX
-	ADCQ    24(R8), BX
+	ADDQ    40(SI), AX
+	ADCQ    48(SI), BX
 
 	MOVQ AX, 0(DI)
 	MOVQ BX, 8(DI)