crypto/internal/cryptotest: add common tests for the hash.Hash interface

This CL creates the cryptotest package to host a suite of tests
for interfaces that are implemented in the crypto package.  This CL
includes a set of tests for the hash.Hash interface, and calls these tests from the tests of hash.Hash implementations in crypto/.

Tests for other interfaces will be included in subsequent CLs.

Updates #25309

Change-Id: Ic47086fd7f585e812c8b0d2186c50792c773781e
Reviewed-on: https://go-review.googlesource.com/c/go/+/592855
Reviewed-by: Roland Shoemaker <roland@golang.org>
Reviewed-by: Carlos Amedee <carlos@golang.org>
Reviewed-by: Russell Webb <russell.webb@protonmail.com>
Reviewed-by: Filippo Valsorda <filippo@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Roland Shoemaker <roland@golang.org>

src/crypto/hmac/hmac_test.go

@@ -5,8 +5,8 @@
 package hmac
 
 import (
-	"bytes"
 	"crypto/internal/boring"
+	"crypto/internal/cryptotest"
 	"crypto/md5"
 	"crypto/sha1"
 	"crypto/sha256"
@@ -621,39 +621,14 @@ func TestEqual(t *testing.T) {
 	}
 }
 
-func TestWriteAfterSum(t *testing.T) {
+func TestHMACHash(t *testing.T) {
-	h := New(sha1.New, nil)
+	for i, test := range hmacTests {
-	h.Write([]byte("hello"))
+		baseHash := test.hash
-	sumHello := h.Sum(nil)
+		key := test.key
 
-	h = New(sha1.New, nil)
+		t.Run(fmt.Sprintf("test-%d", i), func(t *testing.T) {
-	h.Write([]byte("hello world"))
+			cryptotest.TestHash(t, func() hash.Hash { return New(baseHash, key) })
-	sumHelloWorld := h.Sum(nil)
+		})
-
-	// Test that Sum has no effect on future Sum or Write operations.
-	// This is a bit unusual as far as usage, but it's allowed
-	// by the definition of Go hash.Hash, and some clients expect it to work.
-	h = New(sha1.New, nil)
-	h.Write([]byte("hello"))
-	if sum := h.Sum(nil); !bytes.Equal(sum, sumHello) {
-		t.Fatalf("1st Sum after hello = %x, want %x", sum, sumHello)
-	}
-	if sum := h.Sum(nil); !bytes.Equal(sum, sumHello) {
-		t.Fatalf("2nd Sum after hello = %x, want %x", sum, sumHello)
-	}
-
-	h.Write([]byte(" world"))
-	if sum := h.Sum(nil); !bytes.Equal(sum, sumHelloWorld) {
-		t.Fatalf("1st Sum after hello world = %x, want %x", sum, sumHelloWorld)
-	}
-	if sum := h.Sum(nil); !bytes.Equal(sum, sumHelloWorld) {
-		t.Fatalf("2nd Sum after hello world = %x, want %x", sum, sumHelloWorld)
-	}
-
-	h.Reset()
-	h.Write([]byte("hello"))
-	if sum := h.Sum(nil); !bytes.Equal(sum, sumHello) {
-		t.Fatalf("Sum after Reset + hello = %x, want %x", sum, sumHello)
 	}
 }
 

src/crypto/internal/cryptotest/hash.go

@@ -0,0 +1,189 @@
+// Copyright 2024 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 cryptotest
+
+import (
+	"bytes"
+	"hash"
+	"io"
+	"math/rand"
+	"testing"
+	"time"
+)
+
+type MakeHash func() hash.Hash
+
+// TestHash performs a set of tests on hash.Hash implementations, checking the
+// documented requirements of Write, Sum, Reset, Size, and BlockSize.
+func TestHash(t *testing.T, mh MakeHash) {
+
+	// Test that Sum returns an appended digest matching output of Size
+	t.Run("SumAppend", func(t *testing.T) {
+		h := mh()
+		rng := newRandReader(t)
+
+		emptyBuff := []byte("")
+		shortBuff := []byte("a")
+		longBuff := make([]byte, h.BlockSize()+1)
+		rng.Read(longBuff)
+
+		// Set of example strings to append digest to
+		prefixes := [][]byte{nil, emptyBuff, shortBuff, longBuff}
+
+		// Go to each string and check digest gets appended to and is correct size.
+		for _, prefix := range prefixes {
+			h.Reset()
+
+			sum := getSum(t, h, prefix) // Append new digest to prefix
+
+			// Check that Sum didn't alter the prefix
+			if !bytes.Equal(sum[0:len(prefix)], prefix) {
+				t.Errorf("Sum alters passed buffer instead of appending; got %x, want %x", sum[0:len(prefix)], prefix)
+			}
+
+			// Check that the appended sum wasn't affected by the prefix
+			if expectedSum := getSum(t, h, nil); !bytes.Equal(sum[len(prefix):], expectedSum) {
+				t.Errorf("Sum behavior affected by data in the input buffer; got %x, want %x", sum[len(prefix):], expectedSum)
+			}
+
+			// Check size of append
+			if got, want := len(sum)-len(prefix), h.Size(); got != want {
+				t.Errorf("Sum appends number of bytes != Size; got %v , want %v", got, want)
+			}
+		}
+	})
+
+	// Test that Hash.Write never returns error.
+	t.Run("WriteWithoutError", func(t *testing.T) {
+		h := mh()
+		rng := newRandReader(t)
+
+		emptySlice := []byte("")
+		shortSlice := []byte("a")
+		longSlice := make([]byte, h.BlockSize()+1)
+		rng.Read(longSlice)
+
+		// Set of example strings to append digest to
+		slices := [][]byte{emptySlice, shortSlice, longSlice}
+
+		for _, slice := range slices {
+			writeToHash(t, h, slice) // Writes and checks Write doesn't error
+		}
+	})
+
+	t.Run("ResetState", func(t *testing.T) {
+		h := mh()
+		rng := newRandReader(t)
+
+		emptySum := getSum(t, h, nil)
+
+		// Write to hash and then Reset it and see if Sum is same as emptySum
+		writeEx := make([]byte, h.BlockSize())
+		rng.Read(writeEx)
+		writeToHash(t, h, writeEx)
+		h.Reset()
+		resetSum := getSum(t, h, nil)
+
+		if !bytes.Equal(emptySum, resetSum) {
+			t.Errorf("Reset hash yields different Sum than new hash; got %x, want %x", emptySum, resetSum)
+		}
+	})
+
+	// Check that Write isn't reading from beyond input slice's bounds
+	t.Run("OutOfBoundsRead", func(t *testing.T) {
+		h := mh()
+		blockSize := h.BlockSize()
+		rng := newRandReader(t)
+
+		msg := make([]byte, blockSize)
+		rng.Read(msg)
+		writeToHash(t, h, msg)
+		expectedDigest := getSum(t, h, nil) // Record control digest
+
+		h.Reset()
+
+		// Make a buffer with msg in the middle and data on either end
+		buff := make([]byte, blockSize*3)
+		endOfPrefix, startOfSuffix := blockSize, blockSize*2
+
+		copy(buff[endOfPrefix:startOfSuffix], msg)
+		rng.Read(buff[:endOfPrefix])
+		rng.Read(buff[startOfSuffix:])
+
+		writeToHash(t, h, buff[endOfPrefix:startOfSuffix])
+		testDigest := getSum(t, h, nil)
+
+		if !bytes.Equal(testDigest, expectedDigest) {
+			t.Errorf("Write affected by data outside of input slice bounds; got %x, want %x", testDigest, expectedDigest)
+		}
+	})
+
+	// Test that multiple calls to Write is stateful
+	t.Run("StatefulWrite", func(t *testing.T) {
+		h := mh()
+		rng := newRandReader(t)
+
+		prefix, suffix := make([]byte, h.BlockSize()), make([]byte, h.BlockSize())
+		rng.Read(prefix)
+		rng.Read(suffix)
+
+		// Write prefix then suffix sequentially and record resulting hash
+		writeToHash(t, h, prefix)
+		writeToHash(t, h, suffix)
+		serialSum := getSum(t, h, nil)
+
+		h.Reset()
+
+		// Write prefix and suffix at the same time and record resulting hash
+		writeToHash(t, h, append(prefix, suffix...))
+		compositeSum := getSum(t, h, nil)
+
+		// Check that sequential writing results in the same as writing all at once
+		if !bytes.Equal(compositeSum, serialSum) {
+			t.Errorf("two successive Write calls resulted in a different Sum than a single one; got %x, want %x", compositeSum, serialSum)
+		}
+	})
+}
+
+// Helper function for writing. Verifies that Write does not error.
+func writeToHash(t *testing.T, h hash.Hash, p []byte) {
+	t.Helper()
+
+	before := make([]byte, len(p))
+	copy(before, p)
+
+	n, err := h.Write(p)
+	if err != nil || n != len(p) {
+		t.Errorf("Write returned error; got (%v, %v), want (nil, %v)", err, n, len(p))
+	}
+
+	if !bytes.Equal(p, before) {
+		t.Errorf("Write modified input slice; got %x, want %x", p, before)
+	}
+}
+
+// Helper function for getting Sum. Checks that Sum doesn't change hash state.
+func getSum(t *testing.T, h hash.Hash, buff []byte) []byte {
+	t.Helper()
+
+	testBuff := make([]byte, len(buff))
+	copy(testBuff, buff)
+
+	sum := h.Sum(buff)
+	testSum := h.Sum(testBuff)
+
+	// Check that Sum doesn't change underlying hash state
+	if !bytes.Equal(sum, testSum) {
+		t.Errorf("successive calls to Sum yield different results; got %x, want %x", sum, testSum)
+	}
+
+	return sum
+}
+
+func newRandReader(t *testing.T) io.Reader {
+	seed := time.Now().UnixNano()
+	t.Logf("Deterministic RNG seed: 0x%x", seed)
+	return rand.New(rand.NewSource(seed))
+}

src/crypto/md5/md5_test.go

@@ -6,6 +6,7 @@ package md5
 
 import (
 	"bytes"
+	"crypto/internal/cryptotest"
 	"crypto/rand"
 	"encoding"
 	"fmt"
@@ -225,6 +226,10 @@ func TestAllocations(t *testing.T) {
 	}
 }
 
+func TestMD5Hash(t *testing.T) {
+	cryptotest.TestHash(t, New)
+}
+
 var bench = New()
 var buf = make([]byte, 1024*1024*8+1)
 var sum = make([]byte, bench.Size())

src/crypto/sha1/sha1_test.go

@@ -9,6 +9,7 @@ package sha1
 import (
 	"bytes"
 	"crypto/internal/boring"
+	"crypto/internal/cryptotest"
 	"crypto/rand"
 	"encoding"
 	"fmt"
@@ -234,6 +235,10 @@ func TestAllocations(t *testing.T) {
 	}
 }
 
+func TestSHA1Hash(t *testing.T) {
+	cryptotest.TestHash(t, New)
+}
+
 var bench = New()
 var buf = make([]byte, 8192)
 

src/crypto/sha256/sha256_test.go

@@ -9,6 +9,7 @@ package sha256
 import (
 	"bytes"
 	"crypto/internal/boring"
+	"crypto/internal/cryptotest"
 	"crypto/rand"
 	"encoding"
 	"fmt"
@@ -325,6 +326,15 @@ func TestCgo(t *testing.T) {
 	h.Sum(nil)
 }
 
+func TestSHA256Hash(t *testing.T) {
+	t.Run("SHA-224", func(t *testing.T) {
+		cryptotest.TestHash(t, New224)
+	})
+	t.Run("SHA-256", func(t *testing.T) {
+		cryptotest.TestHash(t, New)
+	})
+}
+
 var bench = New()
 var buf = make([]byte, 8192)
 

src/crypto/sha512/sha512_test.go

@@ -9,6 +9,7 @@ package sha512
 import (
 	"bytes"
 	"crypto/internal/boring"
+	"crypto/internal/cryptotest"
 	"crypto/rand"
 	"encoding"
 	"encoding/hex"
@@ -909,6 +910,21 @@ func TestAllocations(t *testing.T) {
 	}
 }
 
+func TestSHA512Hash(t *testing.T) {
+	t.Run("SHA-384", func(t *testing.T) {
+		cryptotest.TestHash(t, New384)
+	})
+	t.Run("SHA-512/224", func(t *testing.T) {
+		cryptotest.TestHash(t, New512_224)
+	})
+	t.Run("SHA-512/256", func(t *testing.T) {
+		cryptotest.TestHash(t, New512_256)
+	})
+	t.Run("SHA-512", func(t *testing.T) {
+		cryptotest.TestHash(t, New)
+	})
+}
+
 var bench = New()
 var buf = make([]byte, 8192)
 

src/go/build/deps_test.go

@@ -642,6 +642,9 @@ var depsRules = `
 	FMT
 	< internal/txtar;
 
+	CRYPTO-MATH, testing
+	< crypto/internal/cryptotest;
+
 	# v2 execution trace parser.
 	FMT
 	< internal/trace/event;