crypto/sha3: import from x/crypto

[FiloSottile]

As part of #65269 (and for #69536), I propose we migrate golang.org/x/crypto/sha3 to the standard library, with the following API.

package sha3

func Sum224(data []byte) [28]byte
func Sum256(data []byte) [32]byte
func Sum384(data []byte) [48]byte
func Sum512(data []byte) [64]byte

func SumSHAKE128(data []byte, length int) []byte
func SumSHAKE256(data []byte, length int) []byte

type SHA3 struct{}
func New224() *SHA3
func New256() *SHA3
func New384() *SHA3
func New512() *SHA3
func (*SHA3) Write(p []byte) (n int, err error)
func (*SHA3) Sum(b []byte) []byte
func (*SHA3) Reset()
func (*SHA3) Size() int
func (*SHA3) BlockSize() int
func (*SHA3) MarshalBinary() ([]byte, error)
func (*SHA3) AppendBinary([]byte) ([]byte, error)
func (*SHA3) UnmarshalBinary(data []byte) error

type SHAKE struct {}
func (*SHAKE) Write(p []byte) (n int, err error)
func (*SHAKE) Read(p []byte) (n int, err error)
func (*SHAKE) Reset()
func (*SHAKE) BlockSize() int
func (*SHAKE) MarshalBinary() ([]byte, error)
func (*SHAKE) AppendBinary([]byte) ([]byte, error)
func (*SHAKE) UnmarshalBinary(data []byte) error
func NewCSHAKE128(N, S []byte) *SHAKE
func NewCSHAKE256(N, S []byte) *SHAKE
func NewSHAKE128() *SHAKE
func NewSHAKE256() *SHAKE

/cc @golang/security @cpu

Changes from golang.org/x/crypto/sha3

• Return concrete types *SHA3 and *SHAKE instead of hash.Hash and ShakeHash
  • This lets us add new methods in the future, but note that it makes it harder to use New functions with crypto/hmac, because they don't have type func() hash.Hash without wrapping. Feels worth it to me, and maybe we can make a v2 one day with generics, but if anyone has ideas to smooth this over let me know.
• Expose MarshalBinary, AppendBinary, and UnmarshalBinary
  • Implemented by CL 616635 as an interface upgrade, see hash: allow Hash to implement encoding.BinaryMarshaler, encoding.BinaryUnmarshaler #20573.
• Dropped Sum and Size from SHAKE
  • These were added recently by @mdempsky without a proposal in CL 526937, I see the value in making SHAKE usable as a hash, especially since the actual hashes NIST specified are so needlessly slow, but I found it confusing that SHAKE-128's Size is 256 bits, which doesn't come from any specs. We can add these back in a separate proposal.
• Replaced ShakeSum/n/(hash, data []byte) with SumSHAKE/n/(data []byte, length int) []byte
  • I found the old one confusing with its two []byte arguments. The new one matches more closely Sum/n/ and can be made zero-allocations in most cases by outlining a fixed-size allocation of a reasonable length. We can also make the default recommendation "Just use SHAKE128 with a length of 32" and this would be the easiest to use API for that.
• Dropped Clone() ShakeHash
  • Pending hash: add Clone #69521, can use MarshalBinary / UnmarshalBinary for now
• Dropped NewLegacyKeccak256 and NewLegacyKeccak512
  • We can use a linkname for now to make x/crypto/sha3 a full wrapper of crypto/sha3, and can add them back to the public API if they are still necessary.
• Renamed Shake to SHAKE to match standard spelling

For reference, here is the current x/crypto/sha3 API.

func New224() hash.Hash
func New256() hash.Hash
func New384() hash.Hash
func New512() hash.Hash
func NewLegacyKeccak256() hash.Hash
func NewLegacyKeccak512() hash.Hash
func ShakeSum128(hash, data []byte)
func ShakeSum256(hash, data []byte)
func Sum224(data []byte) (digest [28]byte)
func Sum256(data []byte) (digest [32]byte)
func Sum384(data []byte) (digest [48]byte)
func Sum512(data []byte) (digest [64]byte)
type ShakeHash interface {
	hash.Hash
	io.Reader
	Clone() ShakeHash
}
func NewCShake128(N, S []byte) ShakeHash
func NewCShake256(N, S []byte) ShakeHash
func NewShake128() ShakeHash
func NewShake256() ShakeHash

[gabyhelp]

Related Issues and Documentation

• crypto/sha{256,512}: unname result parameters for consistency
• crypto: add SHA-512/224 and SHA-512/256 as described in FIPS 180-4

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[mateusz834]

This lets us add new methods in the future, but note that it makes it harder to use New functions with crypto/hmac,

I guess this is going to work:

hmac.New(crypto.SHA3_256.New, make([]byte, 32))

[mateusz834]

Speaking of crypto.SHA3_256.New, once this proposal gets accepted, the x/crypto/sha3 is going to be implemented in terms of crypto/sha3 (for go1.24), but if someone is going to use crypto/sha3 AND an old version of x/crypto package, then crypto.SHA3_256.New is going to be random (depending on the import order) crypto/sha3 or x/crypto/sha3, right?

go/src/crypto/crypto.go

Lines 145 to 150 in 38f8596

	func RegisterHash(h Hash, f func() hash.Hash) {
	if h >= maxHash {
	panic("crypto: RegisterHash of unknown hash function")
	}
	hashes[h] = f
	}

At least it does not panic. I assume that this is fine, right?

[FiloSottile]

Yeah, I was just thinking about that, and indeed it doesn't really matter since they will be equivalent and they don't panic. Newer versions of x/crypto will simply not register the hash if running on Go 1.24 (and import crypto/sha3 which will register its version).

[magical]

This lets us add new methods in the future, but note that it makes it harder to use New functions with crypto/hmac

Indeed, though it's worth noting that SHA-3 has its own MAC construction, KMAC, which should probably be preferred over HMAC-SHA3. So making the package slightly harder to use with crypto/hmac is not necessarily a bad thing.

[gopherbot]

Change https://go.dev/cl/616717 mentions this issue: crypto/internal/fips/sha3: import x/crypto/sha3@750a45fe5e4

[aclements]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.