poly1305: deprecate public package

Fixes golang/go#36646

Change-Id: Ic19dd2171c84472fc9d3f44803224b87fc5c0417
Reviewed-on: https://go-review.googlesource.com/c/crypto/+/345649
Trust: Filippo Valsorda <[email protected]>
Trust: Katie Hockman <[email protected]>
Run-TryBot: Filippo Valsorda <[email protected]>
TryBot-Result: Go Bot <[email protected]>
Reviewed-by: Roland Shoemaker <[email protected]>
Reviewed-by: Katie Hockman <[email protected]>

Author: FiloSottile

chacha20poly1305/chacha20poly1305.go

@@ -26,6 +26,10 @@ const (
 	// NonceSizeX is the size of the nonce used with the XChaCha20-Poly1305
 	// variant of this AEAD, in bytes.
 	NonceSizeX = 24
+
+	// Overhead is the size of the Poly1305 authentication tag, and the
+	// difference between a ciphertext length and its plaintext.
+	Overhead = 16
 )
 
 type chacha20poly1305 struct {
@@ -47,7 +51,7 @@ func (c *chacha20poly1305) NonceSize() int {
 }
 
 func (c *chacha20poly1305) Overhead() int {
-	return 16
+	return Overhead
 }
 
 func (c *chacha20poly1305) Seal(dst, nonce, plaintext, additionalData []byte) []byte {

chacha20poly1305/chacha20poly1305_generic.go

@@ -8,8 +8,8 @@ import (
 	"encoding/binary"
 
 	"golang.org/x/crypto/chacha20"
+	"golang.org/x/crypto/internal/poly1305"
 	"golang.org/x/crypto/internal/subtle"
-	"golang.org/x/crypto/poly1305"
 )
 
 func writeWithPadding(p *poly1305.MAC, b []byte) {

chacha20poly1305/xchacha20poly1305.go

@@ -35,7 +35,7 @@ func (*xchacha20poly1305) NonceSize() int {
 }
 
 func (*xchacha20poly1305) Overhead() int {
-	return 16
+	return Overhead
 }
 
 func (x *xchacha20poly1305) Seal(dst, nonce, plaintext, additionalData []byte) []byte {

poly1305/bits_compat.go renamed to internal/poly1305/bits_compat.go

@@ -15,7 +15,7 @@
 // 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"
+package poly1305
 
 import "crypto/subtle"
 

poly1305/bits_go1.13.go renamed to internal/poly1305/bits_go1.13.go

@@ -35,8 +35,8 @@ This package is interoperable with NaCl: https://nacl.cr.yp.to/secretbox.html.
 package secretbox // import "golang.org/x/crypto/nacl/secretbox"
 
 import (
+	"golang.org/x/crypto/internal/poly1305"
 	"golang.org/x/crypto/internal/subtle"
-	"golang.org/x/crypto/poly1305"
 	"golang.org/x/crypto/salsa20/salsa"
 )
 

poly1305/mac_noasm.go renamed to internal/poly1305/mac_noasm.go

@@ -0,0 +1,91 @@
+// Copyright 2012 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.
+
+// 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
+// golang.org/x/crypto/chacha20poly1305. For authentication, use a general
+// purpose MAC such as HMAC implemented by crypto/hmac.
+package poly1305 // import "golang.org/x/crypto/poly1305"
+
+import "golang.org/x/crypto/internal/poly1305"
+
+// TagSize is the size, in bytes, of a poly1305 authenticator.
+//
+// For use with golang.org/x/crypto/chacha20poly1305, chacha20poly1305.Overhead
+// can be used instead.
+const TagSize = 16
+
+// 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 *[16]byte, m []byte, key *[32]byte) {
+	poly1305.Sum(out, m, key)
+}
+
+// Verify returns true if mac is a valid authenticator for m with the given key.
+func Verify(mac *[16]byte, m []byte, key *[32]byte) bool {
+	return poly1305.Verify(mac, m, key)
+}
+
+// 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: poly1305.New(key)}
+}
+
+// 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.
+type MAC struct {
+	mac *poly1305.MAC
+}
+
+// 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 or Verify.
+func (h *MAC) Write(p []byte) (n int, err error) {
+	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 {
+	return h.mac.Sum(b)
+}
+
+// Verify returns whether the authenticator of all data written to
+// the message authentication code matches the expected value.
+func (h *MAC) Verify(expected []byte) bool {
+	return h.mac.Verify(expected)
+}

poly1305/poly1305.go renamed to internal/poly1305/poly1305.go

@@ -18,7 +18,7 @@ import (
 	"io/ioutil"
 
 	"golang.org/x/crypto/chacha20"
-	"golang.org/x/crypto/poly1305"
+	"golang.org/x/crypto/internal/poly1305"
 )
 
 const (