crypto/hmac: add Equal function.

It was suggested that it's too easy to use crypto/hmac insecurely and
I think that has some merit. This change adds a Equal function to
make it obvious that MAC values should be compared in constant time.

R=rsc, max
CC=golang-dev
https://golang.org/cl/6632044

diff --git a/src/pkg/crypto/hmac/hmac.go b/src/pkg/crypto/hmac/hmac.go
index a97ce09727abaaacccbba5db59a588e81ae17d51..b6f4919a7ce45e888d20fa3c77c1ca207ac3036c 100644 (file)
--- a/src/pkg/crypto/hmac/hmac.go
+++ b/src/pkg/crypto/hmac/hmac.go
@@ -2,13 +2,27 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Package hmac implements the Keyed-Hash Message Authentication Code (HMAC) as
-// defined in U.S. Federal Information Processing Standards Publication 198.
-// An HMAC is a cryptographic hash that uses a key to sign a message.
-// The receiver verifies the hash by recomputing it using the same key.
+/*
+Package hmac implements the Keyed-Hash Message Authentication Code (HMAC) as
+defined in U.S. Federal Information Processing Standards Publication 198.
+An HMAC is a cryptographic hash that uses a key to sign a message.
+The receiver verifies the hash by recomputing it using the same key.
+
+Receivers should be careful to use Equal to compare MACs in order to avoid
+timing side-channels:
+
+       // CheckMAC returns true if messageMAC is a valid HMAC tag for message.
+       func CheckMAC(message, messageMAC, key []byte) bool {
+               mac := hmac.New(sha256.New, key)
+               mac.Write(message)
+               expectedMAC := mac.Sum(nil)
+               return hmac.Equal(messageMAC, expectedMAC)
+       }
+*/
 package hmac
 
 import (
+       "crypto/subtle"
        "hash"
 )
 
@@ -57,7 +71,7 @@ func (h *hmac) BlockSize() int { return h.blocksize }
 func (h *hmac) Reset() {
        h.inner.Reset()
        h.tmpPad(0x36)
-       h.inner.Write(h.tmp[0:h.blocksize])
+       h.inner.Write(h.tmp[:h.blocksize])
 }
 
 // New returns a new HMAC hash using the given hash.Hash type and key.
@@ -78,3 +92,11 @@ func New(h func() hash.Hash, key []byte) hash.Hash {
        hm.Reset()
        return hm
 }
+
+// Equal compares two MACs for equality without leaking timing information.
+func Equal(mac1, mac2 []byte) bool {
+       // We don't have to be constant time if the lengths of the MACs are
+       // different as that suggests that a completely different hash function
+       // was used.
+       return len(mac1) == len(mac2) && subtle.ConstantTimeCompare(mac1, mac2) == 1
+}

diff --git a/src/pkg/crypto/hmac/hmac_test.go b/src/pkg/crypto/hmac/hmac_test.go
index 07957414c8836086750149c29346b482e8ea8a79..d4860424eb1df2583b0db00c15dfc971f337ef64 100644 (file)
--- a/src/pkg/crypto/hmac/hmac_test.go
+++ b/src/pkg/crypto/hmac/hmac_test.go
@@ -491,3 +491,22 @@ func TestHMAC(t *testing.T) {
                }
        }
 }
+
+func TestEqual(t *testing.T) {
+       a := []byte("test")
+       b := []byte("test1")
+       c := []byte("test2")
+
+       if !Equal(b, b) {
+               t.Error("Equal failed with equal arguments")
+       }
+       if Equal(a, b) {
+               t.Error("Equal accepted a prefix of the second argument")
+       }
+       if Equal(b, a) {
+               t.Error("Equal accepted a prefix of the first argument")
+       }
+       if Equal(b, c) {
+               t.Error("Equal accepted unequal slices")
+       }
+}

diff --git a/src/pkg/go/build/deps_test.go b/src/pkg/go/build/deps_test.go
index efed739dd216ee9482fc6c8ec587fdba104b9f59..725ce5bdc2d02761e76091f55a0bcf08b796dd4c 100644 (file)
--- a/src/pkg/go/build/deps_test.go
+++ b/src/pkg/go/build/deps_test.go
@@ -249,18 +249,23 @@ var pkgDeps = map[string][]string{
        "net/mail":      {"L4", "NET", "OS"},
        "net/textproto": {"L4", "OS", "net"},
 
+       // Support libraries for crypto that aren't L2.
+       "CRYPTO-SUPPORT": {
+               "crypto/subtle",
+       },
+
        // Core crypto.
        "crypto/aes":    {"L3"},
        "crypto/des":    {"L3"},
-       "crypto/hmac":   {"L3"},
+       "crypto/hmac":   {"L3", "CRYPTO-SUPPORT"},
        "crypto/md5":    {"L3"},
        "crypto/rc4":    {"L3"},
        "crypto/sha1":   {"L3"},
        "crypto/sha256": {"L3"},
        "crypto/sha512": {"L3"},
-       "crypto/subtle": {"L3"},
 
        "CRYPTO": {
+               "CRYPTO-SUPPORT",
                "crypto/aes",
                "crypto/des",
                "crypto/hmac",
@@ -269,7 +274,6 @@ var pkgDeps = map[string][]string{
                "crypto/sha1",
                "crypto/sha256",
                "crypto/sha512",
-               "crypto/subtle",
        },
 
        // Random byte, number generation.