1 // Copyright 2012 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Package poly1305 implements Poly1305 one-time message authentication code as 6 // specified in https://cr.yp.to/mac/poly1305-20050329.pdf. 7 // 8 // Poly1305 is a fast, one-time authentication function. It is infeasible for an 9 // attacker to generate an authenticator for a message without the key. However, a 10 // key must only be used for a single message. Authenticating two different 11 // messages with the same key allows an attacker to forge authenticators for other 12 // messages with the same key. 13 // 14 // Poly1305 was originally coupled with AES in order to make Poly1305-AES. AES was 15 // used with a fixed key in order to generate one-time keys from an nonce. 16 // However, in this package AES isn't used and the one-time key is specified 17 // directly. 18 package poly1305 19 20 import "crypto/subtle" 21 22 // TagSize is the size, in bytes, of a poly1305 authenticator. 23 const TagSize = 16 24 25 // Sum generates an authenticator for msg using a one-time key and puts the 26 // 16-byte result into out. Authenticating two different messages with the same 27 // key allows an attacker to forge messages at will. 28 func Sum(out *[16]byte, m []byte, key *[32]byte) { 29 h := New(key) 30 h.Write(m) 31 h.Sum(out[:0]) 32 } 33 34 // Verify returns true if mac is a valid authenticator for m with the given key. 35 func Verify(mac *[16]byte, m []byte, key *[32]byte) bool { 36 var tmp [16]byte 37 Sum(&tmp, m, key) 38 return subtle.ConstantTimeCompare(tmp[:], mac[:]) == 1 39 } 40 41 // New returns a new MAC computing an authentication 42 // tag of all data written to it with the given key. 43 // This allows writing the message progressively instead 44 // of passing it as a single slice. Common users should use 45 // the Sum function instead. 46 // 47 // The key must be unique for each message, as authenticating 48 // two different messages with the same key allows an attacker 49 // to forge messages at will. 50 func New(key *[32]byte) *MAC { 51 m := &MAC{} 52 initialize(key, &m.macState) 53 return m 54 } 55 56 // MAC is an io.Writer computing an authentication tag 57 // of the data written to it. 58 // 59 // MAC cannot be used like common hash.Hash implementations, 60 // because using a poly1305 key twice breaks its security. 61 // Therefore writing data to a running MAC after calling 62 // Sum or Verify causes it to panic. 63 type MAC struct { 64 mac // platform-dependent implementation 65 66 finalized bool 67 } 68 69 // Size returns the number of bytes Sum will return. 70 func (h *MAC) Size() int { return TagSize } 71 72 // Write adds more data to the running message authentication code. 73 // It never returns an error. 74 // 75 // It must not be called after the first call of Sum or Verify. 76 func (h *MAC) Write(p []byte) (n int, err error) { 77 if h.finalized { 78 panic("poly1305: write to MAC after Sum or Verify") 79 } 80 return h.mac.Write(p) 81 } 82 83 // Sum computes the authenticator of all data written to the 84 // message authentication code. 85 func (h *MAC) Sum(b []byte) []byte { 86 var mac [TagSize]byte 87 h.mac.Sum(&mac) 88 h.finalized = true 89 return append(b, mac[:]...) 90 } 91 92 // Verify returns whether the authenticator of all data written to 93 // the message authentication code matches the expected value. 94 func (h *MAC) Verify(expected []byte) bool { 95 var mac [TagSize]byte 96 h.mac.Sum(&mac) 97 h.finalized = true 98 return subtle.ConstantTimeCompare(expected, mac[:]) == 1 99 } 100