crypto/internal/fips/sha3: restructure as an internal package

Main changes are

    - return concrete *Digest and *SHAKE instead of interfaces

    - make tests external (sha3_test) so they will be easy to move to
      the public package

    - drop most of the developer guidance docs (to be updated and
      reintroduced in the public package)

    - consolidate the _noasm.go files (matching the single _s390x.go)

    - move TestAllocations from build tags to testenv

    - temporarily disable s390x code, to refactor in a following CL

For #69536

Change-Id: Ie5fd3e2b589b9eb835b9e3174b7a79c2ac728ab1
Reviewed-on: https://go-review.googlesource.com/c/go/+/617357
Reviewed-by: Roland Shoemaker <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>
Reviewed-by: Carlos Amedee <[email protected]>
Auto-Submit: Filippo Valsorda <[email protected]>
Reviewed-by: Daniel McCarney <[email protected]>

Author: FiloSottile

src/crypto/internal/fips/hmac/hmac.go

@@ -10,6 +10,7 @@ package hmac
 import (
 	"crypto/internal/fips"
 	"crypto/internal/fips/sha256"
+	"crypto/internal/fips/sha3"
 	"crypto/internal/fips/sha512"
 )
 
@@ -158,8 +159,7 @@ func setServiceIndicator(h fips.Hash, key []byte) {
 	}
 
 	switch h.(type) {
-	case *sha256.Digest, *sha512.Digest:
-	// TODO(fips): SHA-3
+	case *sha256.Digest, *sha512.Digest, *sha3.Digest:
 	default:
 		return
 	}

src/crypto/internal/fips/sha3/allocations_test.go

@@ -4,37 +4,23 @@
 
 package sha3
 
-// This file provides functions for creating instances of the SHA-3
-// and SHAKE hash functions, as well as utility functions for hashing
-// bytes.
-
-import "crypto/internal/fips"
-
-// New224 creates a new SHA3-224 hash.
-// Its generic security strength is 224 bits against preimage attacks,
-// and 112 bits against collision attacks.
-func New224() fips.Hash {
+// New224 returns a new Digest computing the SHA3-224 hash.
+func New224() *Digest {
 	return new224()
 }
 
-// New256 creates a new SHA3-256 hash.
-// Its generic security strength is 256 bits against preimage attacks,
-// and 128 bits against collision attacks.
-func New256() fips.Hash {
+// New256 returns a new Digest computing the SHA3-256 hash.
+func New256() *Digest {
 	return new256()
 }
 
-// New384 creates a new SHA3-384 hash.
-// Its generic security strength is 384 bits against preimage attacks,
-// and 192 bits against collision attacks.
-func New384() fips.Hash {
+// New384 returns a new Digest computing the SHA3-384 hash.
+func New384() *Digest {
 	return new384()
 }
 
-// New512 creates a new SHA3-512 hash.
-// Its generic security strength is 512 bits against preimage attacks,
-// and 256 bits against collision attacks.
-func New512() fips.Hash {
+// New512 returns a new Digest computing the SHA3-512 hash.
+func New512() *Digest {
 	return new512()
 }
 
@@ -60,66 +46,30 @@ const (
 	rateK1024 = (1600 - 1024) / 8
 )
 
-func new224Generic() *state {
-	return &state{rate: rateK448, outputLen: 28, dsbyte: dsbyteSHA3}
-}
-
-func new256Generic() *state {
-	return &state{rate: rateK512, outputLen: 32, dsbyte: dsbyteSHA3}
-}
-
-func new384Generic() *state {
-	return &state{rate: rateK768, outputLen: 48, dsbyte: dsbyteSHA3}
+func new224Generic() *Digest {
+	return &Digest{rate: rateK448, outputLen: 28, dsbyte: dsbyteSHA3}
 }
 
-func new512Generic() *state {
-	return &state{rate: rateK1024, outputLen: 64, dsbyte: dsbyteSHA3}
-}
-
-// NewLegacyKeccak256 creates a new Keccak-256 hash.
-//
-// Only use this function if you require compatibility with an existing cryptosystem
-// that uses non-standard padding. All other users should use New256 instead.
-func NewLegacyKeccak256() fips.Hash {
-	return &state{rate: rateK512, outputLen: 32, dsbyte: dsbyteKeccak}
-}
-
-// NewLegacyKeccak512 creates a new Keccak-512 hash.
-//
-// Only use this function if you require compatibility with an existing cryptosystem
-// that uses non-standard padding. All other users should use New512 instead.
-func NewLegacyKeccak512() fips.Hash {
-	return &state{rate: rateK1024, outputLen: 64, dsbyte: dsbyteKeccak}
+func new256Generic() *Digest {
+	return &Digest{rate: rateK512, outputLen: 32, dsbyte: dsbyteSHA3}
 }
 
-// Sum224 returns the SHA3-224 digest of the data.
-func Sum224(data []byte) (digest [28]byte) {
-	h := New224()
-	h.Write(data)
-	h.Sum(digest[:0])
-	return
+func new384Generic() *Digest {
+	return &Digest{rate: rateK768, outputLen: 48, dsbyte: dsbyteSHA3}
 }
 
-// Sum256 returns the SHA3-256 digest of the data.
-func Sum256(data []byte) (digest [32]byte) {
-	h := New256()
-	h.Write(data)
-	h.Sum(digest[:0])
-	return
+func new512Generic() *Digest {
+	return &Digest{rate: rateK1024, outputLen: 64, dsbyte: dsbyteSHA3}
 }
 
-// Sum384 returns the SHA3-384 digest of the data.
-func Sum384(data []byte) (digest [48]byte) {
-	h := New384()
-	h.Write(data)
-	h.Sum(digest[:0])
-	return
+// NewLegacyKeccak256 returns a new Digest computing the legacy, non-standard
+// Keccak-256 hash.
+func NewLegacyKeccak256() *Digest {
+	return &Digest{rate: rateK512, outputLen: 32, dsbyte: dsbyteKeccak}
 }
 
-// Sum512 returns the SHA3-512 digest of the data.
-func Sum512(data []byte) (digest [64]byte) {
-	h := New512()
-	h.Write(data)
-	h.Sum(digest[:0])
-	return
+// NewLegacyKeccak512 returns a new Digest computing the legacy, non-standard
+// Keccak-512 hash.
+func NewLegacyKeccak512() *Digest {
+	return &Digest{rate: rateK1024, outputLen: 64, dsbyte: dsbyteKeccak}
 }