hash: add XOF interface

For #69518

Change-Id: I68c7057c776522514eed37cf4dc0cfddec034d3a
Reviewed-on: https://go-review.googlesource.com/c/go/+/644235
Reviewed-by: Austin Clements <austin@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Cherry Mui <cherryyz@google.com>
Reviewed-by: Filippo Valsorda <filippo@golang.org>

diff --git a/api/next/69518.txt b/api/next/69518.txt
new file mode 100644 (file)
index 0000000..b70fcc1
--- /dev/null
+++ b/api/next/69518.txt
@@ -0,0 +1,5 @@
+pkg hash, type XOF interface { BlockSize, Read, Reset, Write } #69518
+pkg hash, type XOF interface, BlockSize() int #69518
+pkg hash, type XOF interface, Read([]uint8) (int, error) #69518
+pkg hash, type XOF interface, Reset() #69518
+pkg hash, type XOF interface, Write([]uint8) (int, error) #69518

diff --git a/doc/next/6-stdlib/99-minor/hash/69518.md b/doc/next/6-stdlib/99-minor/hash/69518.md
new file mode 100644 (file)
index 0000000..67dbdd4
--- /dev/null
+++ b/doc/next/6-stdlib/99-minor/hash/69518.md
@@ -0,0 +1,3 @@
+The new [XOF](/pkg/hash#XOF) interface can be implemented by "extendable output
+functions", which are hash functions with arbitrary or unlimited output length
+such as [BLAKE2Xb](https://pkg.go.dev/golang.org/x/crypto/blake2b).

diff --git a/src/hash/hash.go b/src/hash/hash.go
index 08a0c6764c3dda8a9cc69ae0ce723112410f07be..c72c4af710d29a70d31bcffe3bbf00aa75de062f 100644 (file)
--- a/src/hash/hash.go
+++ b/src/hash/hash.go
@@ -56,3 +56,23 @@ type Hash64 interface {
        Hash
        Sum64() uint64
 }
+
+// XOF (extendable output function) is a hash function with arbitrary or unlimited output length.
+type XOF interface {
+       // Write absorbs more data into the XOF's state. It panics if called
+       // after Read.
+       io.Writer
+
+       // Read reads more output from the XOF. It may return io.EOF if there
+       // is a limit to the XOF output length.
+       io.Reader
+
+       // Reset resets the XOF to its initial state.
+       Reset()
+
+       // BlockSize returns the XOF's underlying block size.
+       // The Write method must be able to accept any amount
+       // of data, but it may operate more efficiently if all writes
+       // are a multiple of the block size.
+       BlockSize() int
+}