go.crypto/sha3: update to sync with draft FIPS-202

1. API:

This exposes a minimal API: the SHA-3 functions implement hash.Hash. The
SHAKE functions implement a new "ShakeHash" interface that implements
io.Reader, io.Writer, and Reset().

(The previous Barrier() function has been removed.)

(Alternative proposal: Don't implement io.Reader, but instead provide a
"Digest(d []byte) error" function that performs a hash.Hash style copy.
Somewhat more minimal, but very easy to use incorrectly.)

2. Tests

Added the complete set of ShortMsgKATs from
   https://github.com/gvanas/KeccakCodePackage

3. Correctness

In sync with draft FIPS-202.

4. Documentation

A summary of the security properties of the SHA-3 and SHAKE functions is
provided in doc.go; some concrete recommendations as well.

Fixes 8563.

R=golang-codereviews, agl
CC=golang-codereviews
https://golang.org/cl/130950043

sha3/doc.go

@@ -0,0 +1,68 @@
+// Copyright 2014 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 sha3 implements the SHA-3 fixed-output-length hash functions and
+// the SHAKE variable-output-length hash functions defined by FIPS-202.
+//
+// Both types of hash function use the "sponge" construction and the Keccak
+// permutation. For a detailed specification see http://keccak.noekeon.org/
+//
+//
+// Guidance
+//
+// If you aren't sure what function you need, use SHAKE256 with at least 64
+// bytes of output.
+//
+// If you need a secret-key MAC (message authentication code), prepend the
+// secret key to the input, hash with SHAKE256 and read at least 32 bytes of
+// output.
+//
+//
+// Security strengths
+//
+// The SHA3-x functions have a security strength against preimage attacks of x
+// bits. Since they only produce x bits of output, their collision-resistance
+// is only x/2 bits.
+//
+// The SHAKE-x functions have a generic security strength of x bits against
+// all attacks, provided that at least 2x bits of their output is used.
+// Requesting more than 2x bits of output does not increase the collision-
+// resistance of the SHAKE functions.
+//
+//
+// The sponge construction
+//
+// A sponge builds a pseudo-random function from a pseudo-random permutation,
+// by applying the permutation to a state of "rate + capacity" bytes, but
+// hiding "capacity" of the bytes.
+//
+// A sponge starts out with a zero state. To hash an input using a sponge, up
+// to "rate" bytes of the input are XORed into the sponge's state. The sponge
+// has thus been "filled up" and the permutation is applied. This process is
+// repeated until all the input has been "absorbed". The input is then padded.
+// The digest is "squeezed" from the sponge by the same method, except that
+// output is copied out.
+//
+// A sponge is parameterized by its generic security strength, which is equal
+// to half its capacity; capacity + rate is equal to the permutation's width.
+//
+// Since the KeccakF-1600 permutation is 1600 bits (200 bytes) wide, this means
+// that security_strength == (1600 - bitrate) / 2.
+//
+//
+// Recommendations, detailed
+//
+// The SHAKE functions are recommended for most new uses. They can produce
+// output of arbitrary length. SHAKE256, with an output length of at least
+// 64 bytes, provides 256-bit security against all attacks.
+//
+// The Keccak team recommends SHAKE256 for most applications upgrading from
+// SHA2-512. (NIST chose a much stronger, but much slower, sponge instance
+// for SHA3-512.)
+//
+// The SHA-3 functions are "drop-in" replacements for the SHA-2 functions.
+// They produce output of the same length, with the same security strengths
+// against all attacks. This means, in particular, that SHA3-256 only has
+// 128-bit collision resistance, because its output length is 32 bytes.
+package sha3

sha3/hashes.go

@@ -0,0 +1,73 @@
+// Copyright 2014 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 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"
+	"hash"
+)
+
+func init() {
+	crypto.RegisterHash(crypto.SHA3_224, New224)
+	crypto.RegisterHash(crypto.SHA3_256, New256)
+	crypto.RegisterHash(crypto.SHA3_384, New384)
+	crypto.RegisterHash(crypto.SHA3_512, New512)
+}
+
+// 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() hash.Hash { return &state{rate: 144, outputLen: 28, dsbyte: 0x06} }
+
+// 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() hash.Hash { return &state{rate: 136, outputLen: 32, dsbyte: 0x06} }
+
+// 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() hash.Hash { return &state{rate: 104, outputLen: 48, dsbyte: 0x06} }
+
+// 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() hash.Hash { return &state{rate: 72, outputLen: 64, dsbyte: 0x06} }
+
+// 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
+}
+
+// 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
+}
+
+// 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
+}
+
+// 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
+}

sha3/keccakf.go

@@ -1,16 +1,11 @@
-// Copyright 2013 The Go Authors. All rights reserved.
+// Copyright 2014 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 sha3
 
-// This file implements the core Keccak permutation function necessary for computing SHA3.
-// This is implemented in a separate file to allow for replacement by an optimized implementation.
-// Nothing in this package is exported.
-// For the detailed specification, refer to the Keccak web site (http://keccak.noekeon.org/).
-
 // rc stores the round constants for use in the ι step.
-var rc = [...]uint64{
+var rc = [24]uint64{
 	0x0000000000000001,
 	0x0000000000008082,
 	0x800000000000808A,
@@ -37,10 +32,9 @@ var rc = [...]uint64{
 	0x8000000080008008,
 }
 
-// keccakF computes the complete Keccak-f function consisting of 24 rounds with a different
-// constant (rc) in each round. This implementation fully unrolls the round function to avoid
-// inner loops, as well as pre-calculating shift offsets.
-func keccakF(a *[numLanes]uint64) {
+// keccakF1600 applies the Keccak permutation to a 1600b-wide
+// state represented as a slice of 25 uint64s.
+func keccakF1600(a *[25]uint64) {
 	var t, bc0, bc1, bc2, bc3, bc4 uint64
 	for _, roundConstant := range rc {
 		// θ step

sha3/sha3.go

@@ -1,213 +1,226 @@
-// Copyright 2013 The Go Authors. All rights reserved.
+// Copyright 2014 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 sha3 implements the SHA3 hash algorithm (formerly called Keccak) chosen by NIST in 2012.
-// This file provides a SHA3 implementation which implements the standard hash.Hash interface.
-// Writing input data, including padding, and reading output data are computed in this file.
-// Note that the current implementation can compute the hash of an integral number of bytes only.
-// This is a consequence of the hash interface in which a buffer of bytes is passed in.
-// The internals of the Keccak-f function are computed in keccakf.go.
-// For the detailed specification, refer to the Keccak web site (http://keccak.noekeon.org/).
 package sha3
 
 import (
 	"encoding/binary"
-	"hash"
 )
 
-// laneSize is the size in bytes of each "lane" of the internal state of SHA3 (5 * 5 * 8).
-// Note that changing this size would requires using a type other than uint64 to store each lane.
-const laneSize = 8
-
-// sliceSize represents the dimensions of the internal state, a square matrix of
-// sliceSize ** 2 lanes. This is the size of both the "rows" and "columns" dimensions in the
-// terminology of the SHA3 specification.
-const sliceSize = 5
-
-// numLanes represents the total number of lanes in the state.
-const numLanes = sliceSize * sliceSize
-
-// stateSize is the size in bytes of the internal state of SHA3 (5 * 5 * WSize).
-const stateSize = laneSize * numLanes
-
-// digest represents the partial evaluation of a checksum.
-// Note that capacity, and not outputSize, is the critical security parameter, as SHA3 can output
-// an arbitrary number of bytes for any given capacity. The Keccak proposal recommends that
-// capacity = 2*outputSize to ensure that finding a collision of size outputSize requires
-// O(2^{outputSize/2}) computations (the birthday lower bound). Future standards may modify the
-// capacity/outputSize ratio to allow for more output with lower cryptographic security.
-type digest struct {
-	a          [numLanes]uint64 // main state of the hash
-	outputSize int              // desired output size in bytes
-	capacity   int              // number of bytes to leave untouched during squeeze/absorb
-	absorbed   int              // number of bytes absorbed thus far
-}
+// spongeDirection indicates the direction bytes are flowing through the sponge.
+type spongeDirection int
 
-// minInt returns the lesser of two integer arguments, to simplify the absorption routine.
-func minInt(v1, v2 int) int {
-	if v1 <= v2 {
-		return v1
-	}
-	return v2
-}
+const (
+	// spongeAbsorbing indicates that the sponge is absorbing input.
+	spongeAbsorbing spongeDirection = iota
+	// spongeSqueezing indicates that the sponge is being squeezed.
+	spongeSqueezing
+)
 
-// rate returns the number of bytes of the internal state which can be absorbed or squeezed
-// in between calls to the permutation function.
-func (d *digest) rate() int {
-	return stateSize - d.capacity
-}
+const (
+	// maxRate is the maximum size of the internal buffer. SHAKE-256
+	// currently needs the largest buffer.
+	maxRate = 168
+)
 
-// Reset clears the internal state by zeroing bytes in the state buffer.
-// This can be skipped for a newly-created hash state; the default zero-allocated state is correct.
-func (d *digest) Reset() {
-	d.absorbed = 0
-	for i := range d.a {
-		d.a[i] = 0
-	}
+type state struct {
+	// Generic sponge components.
+	a    [25]uint64 // main state of the hash
+	buf  []byte     // points into storage
+	rate int        // the number of bytes of state to use
+
+	// dsbyte contains the "domain separation" value and the first bit of
+	// the padding. In sections 6.1 and 6.2 of [1], the SHA-3 and SHAKE
+	// functions are defined with bits appended to the message: SHA-3
+	// functions have 01 and SHAKE functions have 1111. Because of the way
+	// that bits are numbered from the LSB upwards, that ends up as
+	// 00000010b and 00001111b, respectively. Then the padding rule from
+	// section 5.1 is applied to pad to a multiple of the rate, which
+	// involves adding a 1 bit, zero or more zero bits and then a final one
+	// bit. The first one bit from the padding is merged into the dsbyte
+	// value giving 00000110b (0x06) and 00011111b (0x1f), respectively.
+	//
+	// [1] http://csrc.nist.gov/publications/drafts/fips-202/fips_202_draft.pdf,
+	dsbyte  byte
+	storage [maxRate]byte
+
+	// Specific to SHA-3 and SHAKE.
+	fixedOutput bool            // whether this is a fixed-ouput-length instance
+	outputLen   int             // the default output size in bytes
+	state       spongeDirection // current direction of the sponge
 }
 
-// BlockSize, required by the hash.Hash interface, does not have a standard intepretation
-// for a sponge-based construction like SHA3. We return the data rate: the number of bytes which
-// can be absorbed per invocation of the permutation function. For Merkle-Damgård based hashes
-// (ie SHA1, SHA2, MD5) the output size of the internal compression function is returned.
-// We consider this to be roughly equivalent because it represents the number of bytes of output
-// produced per cryptographic operation.
-func (d *digest) BlockSize() int { return d.rate() }
+// BlockSize returns the rate of sponge underlying this hash function.
+func (d *state) BlockSize() int { return d.rate }
 
 // Size returns the output size of the hash function in bytes.
-func (d *digest) Size() int {
-	return d.outputSize
-}
+func (d *state) Size() int { return d.outputLen }
 
-// unalignedAbsorb is a helper function for Write, which absorbs data that isn't aligned with an
-// 8-byte lane. This requires shifting the individual bytes into position in a uint64.
-func (d *digest) unalignedAbsorb(p []byte) {
-	var t uint64
-	for i := len(p) - 1; i >= 0; i-- {
-		t <<= 8
-		t |= uint64(p[i])
+// Reset clears the internal state by zeroing the sponge state and
+// the byte buffer, and setting Sponge.state to absorbing.
+func (d *state) Reset() {
+	// Zero the permutation's state.
+	for i := range d.a {
+		d.a[i] = 0
 	}
-	offset := (d.absorbed) % d.rate()
-	t <<= 8 * uint(offset%laneSize)
-	d.a[offset/laneSize] ^= t
-	d.absorbed += len(p)
+	d.state = spongeAbsorbing
+	d.buf = d.storage[:0]
 }
 
-// Write "absorbs" bytes into the state of the SHA3 hash, updating as needed when the sponge
-// "fills up" with rate() bytes. Since lanes are stored internally as type uint64, this requires
-// converting the incoming bytes into uint64s using a little endian interpretation. This
-// implementation is optimized for large, aligned writes of multiples of 8 bytes (laneSize).
-// Non-aligned or uneven numbers of bytes require shifting and are slower.
-func (d *digest) Write(p []byte) (int, error) {
-	// An initial offset is needed if the we aren't absorbing to the first lane initially.
-	offset := d.absorbed % d.rate()
-	toWrite := len(p)
-
-	// The first lane may need to absorb unaligned and/or incomplete data.
-	if (offset%laneSize != 0 || len(p) < 8) && len(p) > 0 {
-		toAbsorb := minInt(laneSize-(offset%laneSize), len(p))
-		d.unalignedAbsorb(p[:toAbsorb])
-		p = p[toAbsorb:]
-		offset = (d.absorbed) % d.rate()
-
-		// For every rate() bytes absorbed, the state must be permuted via the F Function.
-		if (d.absorbed)%d.rate() == 0 {
-			keccakF(&d.a)
-		}
+func (d *state) clone() *state {
+	ret := *d
+	if ret.state == spongeAbsorbing {
+		ret.buf = ret.storage[:len(ret.buf)]
+	} else {
+		ret.buf = ret.storage[d.rate-cap(d.buf) : d.rate]
 	}
 
-	// This loop should absorb the bulk of the data into full, aligned lanes.
-	// It will call the update function as necessary.
-	for len(p) > 7 {
-		firstLane := offset / laneSize
-		lastLane := minInt(d.rate()/laneSize, firstLane+len(p)/laneSize)
+	return &ret
+}
 
-		// This inner loop absorbs input bytes into the state in groups of 8, converted to uint64s.
-		for lane := firstLane; lane < lastLane; lane++ {
-			d.a[lane] ^= binary.LittleEndian.Uint64(p[:laneSize])
-			p = p[laneSize:]
-		}
-		d.absorbed += (lastLane - firstLane) * laneSize
-		// For every rate() bytes absorbed, the state must be permuted via the F Function.
-		if (d.absorbed)%d.rate() == 0 {
-			keccakF(&d.a)
-		}
+// xorIn xors a buffer into the state, byte-swapping to
+// little-endian as necessary; it returns the number of bytes
+// copied, including any zeros appended to the bytestring.
+func (d *state) xorIn(buf []byte) {
+	n := len(buf) / 8
 
-		offset = 0
+	for i := 0; i < n; i++ {
+		a := binary.LittleEndian.Uint64(buf)
+		d.a[i] ^= a
+		buf = buf[8:]
 	}
+	if len(buf) != 0 {
+		// XOR in the last partial ulint64.
+		a := uint64(0)
+		for i, v := range buf {
+			a |= uint64(v) << uint64(8*i)
+		}
+		d.a[n] ^= a
+	}
+}
 
-	// If there are insufficient bytes to fill the final lane, an unaligned absorption.
-	// This should always start at a correct lane boundary though, or else it would be caught
-	// by the uneven opening lane case above.
-	if len(p) > 0 {
-		d.unalignedAbsorb(p)
+// copyOut copies ulint64s to a byte buffer.
+func (d *state) copyOut(b []byte) {
+	for i := 0; len(b) >= 8; i++ {
+		binary.LittleEndian.PutUint64(b, d.a[i])
+		b = b[8:]
 	}
+}
 
-	return toWrite, nil
+// permute applies the KeccakF-1600 permutation. It handles
+// any input-output buffering.
+func (d *state) permute() {
+	switch d.state {
+	case spongeAbsorbing:
+		// If we're absorbing, we need to xor the input into the state
+		// before applying the permutation.
+		d.xorIn(d.buf)
+		d.buf = d.storage[:0]
+		keccakF1600(&d.a)
+	case spongeSqueezing:
+		// If we're squeezing, we need to apply the permutatin before
+		// copying more output.
+		keccakF1600(&d.a)
+		d.buf = d.storage[:d.rate]
+		d.copyOut(d.buf)
+	}
 }
 
-// pad computes the SHA3 padding scheme based on the number of bytes absorbed.
-// The padding is a 1 bit, followed by an arbitrary number of 0s and then a final 1 bit, such that
-// the input bits plus padding bits are a multiple of rate(). Adding the padding simply requires
-// xoring an opening and closing bit into the appropriate lanes.
-func (d *digest) pad() {
-	offset := d.absorbed % d.rate()
-	// The opening pad bit must be shifted into position based on the number of bytes absorbed
-	padOpenLane := offset / laneSize
-	d.a[padOpenLane] ^= 0x0000000000000001 << uint(8*(offset%laneSize))
-	// The closing padding bit is always in the last position
-	padCloseLane := (d.rate() / laneSize) - 1
-	d.a[padCloseLane] ^= 0x8000000000000000
+// pads appends the domain separation bits in dsbyte, applies
+// the multi-bitrate 10..1 padding rule, and permutes the state.
+func (d *state) padAndPermute(dsbyte byte) {
+	if d.buf == nil {
+		d.buf = d.storage[:0]
+	}
+	// Pad with this instance's domain-separator bits. We know that there's
+	// at least one byte of space in d.buf because, if it were full,
+	// permute would have been called to empty it. dsbyte also contains the
+	// first one bit for the padding. See the comment in the state struct.
+	d.buf = append(d.buf, dsbyte)
+	zerosStart := len(d.buf)
+	d.buf = d.storage[:d.rate]
+	for i := zerosStart; i < d.rate; i++ {
+		d.buf[i] = 0
+	}
+	// This adds the final one bit for the padding. Because of the way that
+	// bits are numbered from the LSB upwards, the final bit is the MSB of
+	// the last byte.
+	d.buf[d.rate-1] ^= 0x80
+	// Apply the permutation
+	d.permute()
+	d.state = spongeSqueezing
+	d.buf = d.storage[:d.rate]
+	d.copyOut(d.buf)
 }
 
-// finalize prepares the hash to output data by padding and one final permutation of the state.
-func (d *digest) finalize() {
-	d.pad()
-	keccakF(&d.a)
+// Write absorbs more data into the hash's state. It produces an error
+// if more data is written to the ShakeHash after writing
+func (d *state) Write(p []byte) (written int, err error) {
+	if d.state != spongeAbsorbing {
+		panic("sha3: write to sponge after read")
+	}
+	if d.buf == nil {
+		d.buf = d.storage[:0]
+	}
+	written = len(p)
+
+	for len(p) > 0 {
+		if len(d.buf) == 0 && len(p) >= d.rate {
+			// The fast path; absorb a full "rate" bytes of input and apply the permutation.
+			d.xorIn(p[:d.rate])
+			p = p[d.rate:]
+			keccakF1600(&d.a)
+		} else {
+			// The slow path; buffer the input until we can fill the sponge, and then xor it in.
+			todo := d.rate - len(d.buf)
+			if todo > len(p) {
+				todo = len(p)
+			}
+			d.buf = append(d.buf, p[:todo]...)
+			p = p[todo:]
+
+			// If the sponge is full, apply the permutation.
+			if len(d.buf) == d.rate {
+				d.permute()
+			}
+		}
+	}
+
+	return
 }
 
-// squeeze outputs an arbitrary number of bytes from the hash state.
-// Squeezing can require multiple calls to the F function (one per rate() bytes squeezed),
-// although this is not the case for standard SHA3 parameters. This implementation only supports
-// squeezing a single time, subsequent squeezes may lose alignment. Future implementations
-// may wish to support multiple squeeze calls, for example to support use as a PRNG.
-func (d *digest) squeeze(in []byte, toSqueeze int) []byte {
-	// Because we read in blocks of laneSize, we need enough room to read
-	// an integral number of lanes
-	needed := toSqueeze + (laneSize-toSqueeze%laneSize)%laneSize
-	if cap(in)-len(in) < needed {
-		newIn := make([]byte, len(in), len(in)+needed)
-		copy(newIn, in)
-		in = newIn
+// Read squeezes an arbitrary number of bytes from the sponge.
+func (d *state) Read(out []byte) (n int, err error) {
+	// If we're still absorbing, pad and apply the permutation.
+	if d.state == spongeAbsorbing {
+		d.padAndPermute(d.dsbyte)
 	}
-	out := in[len(in) : len(in)+needed]
 
+	n = len(out)
+
+	// Now, do the squeezing.
 	for len(out) > 0 {
-		for i := 0; i < d.rate() && len(out) > 0; i += laneSize {
-			binary.LittleEndian.PutUint64(out[:], d.a[i/laneSize])
-			out = out[laneSize:]
-		}
-		if len(out) > 0 {
-			keccakF(&d.a)
+		n := copy(out, d.buf)
+		d.buf = d.buf[n:]
+		out = out[n:]
+
+		// Apply the permutation if we've squeezed the sponge dry.
+		if len(d.buf) == 0 {
+			d.permute()
 		}
 	}
-	return in[:len(in)+toSqueeze] // Re-slice in case we wrote extra data.
-}
 
-// Sum applies padding to the hash state and then squeezes out the desired nubmer of output bytes.
-func (d *digest) Sum(in []byte) []byte {
-	// Make a copy of the original hash so that caller can keep writing and summing.
-	dup := *d
-	dup.finalize()
-	return dup.squeeze(in, dup.outputSize)
+	return
 }
 
-// The NewKeccakX constructors enable initializing a hash in any of the four recommend sizes
-// from the Keccak specification, all of which set capacity=2*outputSize. Note that the final
-// NIST standard for SHA3 may specify different input/output lengths.
-// The output size is indicated in bits but converted into bytes internally.
-func NewKeccak224() hash.Hash { return &digest{outputSize: 224 / 8, capacity: 2 * 224 / 8} }
-func NewKeccak256() hash.Hash { return &digest{outputSize: 256 / 8, capacity: 2 * 256 / 8} }
-func NewKeccak384() hash.Hash { return &digest{outputSize: 384 / 8, capacity: 2 * 384 / 8} }
-func NewKeccak512() hash.Hash { return &digest{outputSize: 512 / 8, capacity: 2 * 512 / 8} }
+// Sum applies padding to the hash state and then squeezes out the desired
+// number of output bytes.
+func (d *state) Sum(in []byte) []byte {
+	// Make a copy of the original hash so that caller can keep writing
+	// and summing.
+	dup := d.clone()
+	hash := make([]byte, dup.outputLen)
+	dup.Read(hash)
+	return append(in, hash...)
+}

sha3/sha3_test.go

@@ -1,34 +1,56 @@
-// Copyright 2013 The Go Authors. All rights reserved.
+// Copyright 2014 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 sha3
 
-// These tests are a subset of those provided by the Keccak web site(http://keccak.noekeon.org/).
+// Tests include all the ShortMsgKATs provided by the Keccak team at
+// https://github.com/gvanas/KeccakCodePackage
+//
+// They only include the zero-bit case of the utterly useless bitwise
+// testvectors published by NIST in the draft of FIPS-202.
 
 import (
 	"bytes"
+	"compress/flate"
 	"encoding/hex"
-	"fmt"
+	"encoding/json"
 	"hash"
+	"os"
 	"strings"
 	"testing"
 )
 
-// testDigests maintains a digest state of each standard type.
-var testDigests = map[string]*digest{
-	"Keccak224": {outputSize: 224 / 8, capacity: 2 * 224 / 8},
-	"Keccak256": {outputSize: 256 / 8, capacity: 2 * 256 / 8},
-	"Keccak384": {outputSize: 384 / 8, capacity: 2 * 384 / 8},
-	"Keccak512": {outputSize: 512 / 8, capacity: 2 * 512 / 8},
+const (
+	testString  = "brekeccakkeccak koax koax"
+	katFilename = "keccakKats.json.deflate"
+)
+
+// Internal-use instances of SHAKE used to test against KATs.
+func newHashShake128() hash.Hash {
+	return &state{rate: 168, dsbyte: 0x1f, outputLen: 512}
+}
+func newHashShake256() hash.Hash {
+	return &state{rate: 136, dsbyte: 0x1f, outputLen: 512}
 }
 
-// testVector represents a test input and expected outputs from multiple algorithm variants.
-type testVector struct {
-	desc   string
-	input  []byte
-	repeat int // input will be concatenated the input this many times.
-	want   map[string]string
+// testDigests contains functions returning hash.Hash instances
+// with output-length equal to the KAT length for both SHA-3 and
+// SHAKE instances.
+var testDigests = map[string]func() hash.Hash{
+	"SHA3-224": New224,
+	"SHA3-256": New256,
+	"SHA3-384": New384,
+	"SHA3-512": New512,
+	"SHAKE128": newHashShake128,
+	"SHAKE256": newHashShake256,
+}
+
+// testShakes contains functions returning ShakeHash instances for
+// testing the ShakeHash-specific interface.
+var testShakes = map[string]func() ShakeHash{
+	"SHAKE128": NewShake128,
+	"SHAKE256": NewShake256,
 }
 
 // decodeHex converts an hex-encoded string into a raw byte string.
@@ -40,102 +62,61 @@ func decodeHex(s string) []byte {
 	return b
 }
 
-// shortTestVectors stores a series of short testVectors.
-// Inputs of 8, 248, and 264 bits from http://keccak.noekeon.org/ are included below.
-// The standard defines additional test inputs of all sizes between 0 and 2047 bits.
-// Because the current implementation can only handle an integral number of bytes,
-// most of the standard test inputs can't be used.
-var shortKeccakTestVectors = []testVector{
-	{
-		desc:   "short-8b",
-		input:  decodeHex("CC"),
-		repeat: 1,
-		want: map[string]string{
-			"Keccak224": "A9CAB59EB40A10B246290F2D6086E32E3689FAF1D26B470C899F2802",
-			"Keccak256": "EEAD6DBFC7340A56CAEDC044696A168870549A6A7F6F56961E84A54BD9970B8A",
-			"Keccak384": "1B84E62A46E5A201861754AF5DC95C4A1A69CAF4A796AE405680161E29572641F5FA1E8641D7958336EE7B11C58F73E9",
-			"Keccak512": "8630C13CBD066EA74BBE7FE468FEC1DEE10EDC1254FB4C1B7C5FD69B646E44160B8CE01D05A0908CA790DFB080F4B513BC3B6225ECE7A810371441A5AC666EB9",
-		},
-	},
-	{
-		desc:   "short-248b",
-		input:  decodeHex("84FB51B517DF6C5ACCB5D022F8F28DA09B10232D42320FFC32DBECC3835B29"),
-		repeat: 1,
-		want: map[string]string{
-			"Keccak224": "81AF3A7A5BD4C1F948D6AF4B96F93C3B0CF9C0E7A6DA6FCD71EEC7F6",
-			"Keccak256": "D477FB02CAAA95B3280EC8EE882C29D9E8A654B21EF178E0F97571BF9D4D3C1C",
-			"Keccak384": "503DCAA4ADDA5A9420B2E436DD62D9AB2E0254295C2982EF67FCE40F117A2400AB492F7BD5D133C6EC2232268BC27B42",
-			"Keccak512": "9D8098D8D6EDBBAA2BCFC6FB2F89C3EAC67FEC25CDFE75AA7BD570A648E8C8945FF2EC280F6DCF73386109155C5BBC444C707BB42EAB873F5F7476657B1BC1A8",
-		},
-	},
-	{
-		desc:   "short-264b",
-		input:  decodeHex("DE8F1B3FAA4B7040ED4563C3B8E598253178E87E4D0DF75E4FF2F2DEDD5A0BE046"),
-		repeat: 1,
-		want: map[string]string{
-			"Keccak224": "F217812E362EC64D4DC5EACFABC165184BFA456E5C32C2C7900253D0",
-			"Keccak256": "E78C421E6213AFF8DE1F025759A4F2C943DB62BBDE359C8737E19B3776ED2DD2",
-			"Keccak384": "CF38764973F1EC1C34B5433AE75A3AAD1AAEF6AB197850C56C8617BCD6A882F6666883AC17B2DCCDBAA647075D0972B5",
-			"Keccak512": "9A7688E31AAF40C15575FC58C6B39267AAD3722E696E518A9945CF7F7C0FEA84CB3CB2E9F0384A6B5DC671ADE7FB4D2B27011173F3EEEAF17CB451CF26542031",
-		},
-	},
-}
-
-// longTestVectors stores longer testVectors (currently only one).
-// The computed test vector is 64 MiB long and is a truncated version of the
-// ExtremelyLongMsgKAT taken from http://keccak.noekeon.org/.
-var longKeccakTestVectors = []testVector{
-	{
-		desc:   "long-64MiB",
-		input:  []byte("abcdefghbcdefghicdefghijdefghijkefghijklfghijklmghijklmnhijklmno"),
-		repeat: 1024 * 1024,
-		want: map[string]string{
-			"Keccak224": "50E35E40980FEEFF1EA490957B0E970257F75EA0D410EE0F0B8A7A58",
-			"Keccak256": "5015A4935F0B51E091C6550A94DCD262C08998232CCAA22E7F0756DEAC0DC0D0",
-			"Keccak384": "7907A8D0FAA7BC6A90FE14C6C958C956A0877E751455D8F13ACDB96F144B5896E716C06EC0CB56557A94EF5C3355F6F3",
-			"Keccak512": "3EC327D6759F769DEB74E80CA70C831BC29CAB048A4BF4190E4A1DD5C6507CF2B4B58937FDE81D36014E7DFE1B1DD8B0F27CB7614F9A645FEC114F1DAAEFC056",
-		},
-	},
+// structs used to marshal JSON test-cases.
+type KeccakKats struct {
+	Kats map[string][]struct {
+		Digest  string `json:"digest"`
+		Length  int64  `json:"length"`
+		Message string `json:"message"`
+	}
 }
 
-// TestKeccakVectors checks that correct output is produced for a set of known testVectors.
-func TestKeccakVectors(t *testing.T) {
-	testCases := append([]testVector{}, shortKeccakTestVectors...)
-	if !testing.Short() {
-		testCases = append(testCases, longKeccakTestVectors...)
+// TestKeccakKats tests the SHA-3 and Shake implementations against all the
+// ShortMsgKATs from https://github.com/gvanas/KeccakCodePackage
+// (The testvectors are stored in keccakKats.json.deflate due to their length.)
+func TestKeccakKats(t *testing.T) {
+	// Read the KATs.
+	deflated, err := os.Open(katFilename)
+	if err != nil {
+		t.Errorf("Error opening %s: %s", katFilename, err)
+	}
+	file := flate.NewReader(deflated)
+	dec := json.NewDecoder(file)
+	var katSet KeccakKats
+	err = dec.Decode(&katSet)
+	if err != nil {
+		t.Errorf("%s", err)
 	}
-	for _, tc := range testCases {
-		for alg, want := range tc.want {
-			d := testDigests[alg]
+
+	// Do the KATs.
+	for functionName, kats := range katSet.Kats {
+		d := testDigests[functionName]()
+		t.Logf("%s", functionName)
+		for _, kat := range kats {
 			d.Reset()
-			for i := 0; i < tc.repeat; i++ {
-				d.Write(tc.input)
+			in, err := hex.DecodeString(kat.Message)
+			if err != nil {
+				t.Errorf("%s", err)
 			}
+			d.Write(in[:kat.Length/8])
 			got := strings.ToUpper(hex.EncodeToString(d.Sum(nil)))
+			want := kat.Digest
 			if got != want {
-				t.Errorf("%s, alg=%s\ngot %q, want %q", tc.desc, alg, got, want)
+				t.Errorf("function=%s, length=%d\nmessage:\n  %s\ngot:\n  %s\nwanted:\n %s",
+					functionName, kat.Length, kat.Message, got, want)
+				t.Logf("wanted %+v", kat)
+				t.FailNow()
 			}
 		}
 	}
 }
 
-// dumpState is a debugging function to pretty-print the internal state of the hash.
-func (d *digest) dumpState() {
-	fmt.Printf("SHA3 hash, %d B output, %d B capacity (%d B rate)\n", d.outputSize, d.capacity, d.rate())
-	fmt.Printf("Internal state after absorbing %d B:\n", d.absorbed)
-
-	for x := 0; x < sliceSize; x++ {
-		for y := 0; y < sliceSize; y++ {
-			fmt.Printf("%v, ", d.a[x*sliceSize+y])
-		}
-		fmt.Println("")
-	}
-}
-
-// TestUnalignedWrite tests that writing data in an arbitrary pattern with small input buffers.
+// TestUnalignedWrite tests that writing data in an arbitrary pattern with
+// small input buffers.
 func TestUnalignedWrite(t *testing.T) {
 	buf := sequentialBytes(0x10000)
-	for alg, d := range testDigests {
+	for alg, df := range testDigests {
+		d := df()
 		d.Reset()
 		d.Write(buf)
 		want := d.Sum(nil)
@@ -145,7 +126,9 @@ func TestUnalignedWrite(t *testing.T) {
 			// Because 137 is prime this sequence should exercise all corner cases.
 			offsets := [17]int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 1}
 			for _, j := range offsets {
-				j = minInt(j, len(buf)-i)
+				if v := len(buf) - i; v < j {
+					j = v
+				}
 				d.Write(buf[i : i+j])
 				i += j
 			}
@@ -157,8 +140,9 @@ func TestUnalignedWrite(t *testing.T) {
 	}
 }
 
+// Test that appending works when reallocation is necessary.
 func TestAppend(t *testing.T) {
-	d := NewKeccak224()
+	d := New224()
 
 	for capacity := 2; capacity < 64; capacity += 64 {
 		// The first time around the loop, Sum will have to reallocate.
@@ -167,24 +151,57 @@ func TestAppend(t *testing.T) {
 		d.Reset()
 		d.Write([]byte{0xcc})
 		buf = d.Sum(buf)
-		expected := "0000A9CAB59EB40A10B246290F2D6086E32E3689FAF1D26B470C899F2802"
+		expected := "0000DF70ADC49B2E76EEE3A6931B93FA41841C3AF2CDF5B32A18B5478C39"
 		if got := strings.ToUpper(hex.EncodeToString(buf)); got != expected {
 			t.Errorf("got %s, want %s", got, expected)
 		}
 	}
 }
 
+// Test that appending works when no reallocation is necessary.
 func TestAppendNoRealloc(t *testing.T) {
 	buf := make([]byte, 1, 200)
-	d := NewKeccak224()
+	d := New224()
 	d.Write([]byte{0xcc})
 	buf = d.Sum(buf)
-	expected := "00A9CAB59EB40A10B246290F2D6086E32E3689FAF1D26B470C899F2802"
+	expected := "00DF70ADC49B2E76EEE3A6931B93FA41841C3AF2CDF5B32A18B5478C39"
 	if got := strings.ToUpper(hex.EncodeToString(buf)); got != expected {
 		t.Errorf("got %s, want %s", got, expected)
 	}
 }
 
+// TestSqueezing checks that squeezing the full output a single time produces
+// the same output as repeatedly squeezing the instance.
+func TestSqueezing(t *testing.T) {
+	for functionName, newShakeHash := range testShakes {
+		t.Logf("%s", functionName)
+		d0 := newShakeHash()
+		d0.Write([]byte(testString))
+		ref := make([]byte, 32)
+		d0.Read(ref)
+
+		d1 := newShakeHash()
+		d1.Write([]byte(testString))
+		var multiple []byte
+		for range ref {
+			one := make([]byte, 1)
+			d1.Read(one)
+			multiple = append(multiple, one...)
+		}
+		if !bytes.Equal(ref, multiple) {
+			t.Errorf("squeezing %d bytes one at a time failed", len(ref))
+		}
+	}
+}
+
+func TestReadSimulation(t *testing.T) {
+	d := NewShake256()
+	d.Write(nil)
+	dwr := make([]byte, 32)
+	d.Read(dwr)
+
+}
+
 // sequentialBytes produces a buffer of size consecutive bytes 0x00, 0x01, ..., used for testing.
 func sequentialBytes(size int) []byte {
 	result := make([]byte, size)
@@ -194,77 +211,39 @@ func sequentialBytes(size int) []byte {
 	return result
 }
 
-// benchmarkBlockWrite tests the speed of writing data and never calling the permutation function.
-func benchmarkBlockWrite(b *testing.B, d *digest) {
-	b.StopTimer()
-	d.Reset()
-	// Write all but the last byte of a block, to ensure that the permutation is not called.
-	data := sequentialBytes(d.rate() - 1)
-	b.SetBytes(int64(len(data)))
-	b.StartTimer()
-	for i := 0; i < b.N; i++ {
-		d.absorbed = 0 // Reset absorbed to avoid ever calling the permutation function
-		d.Write(data)
-	}
-	b.StopTimer()
-	d.Reset()
-}
-
-// BenchmarkPermutationFunction measures the speed of the permutation function with no input data.
+// BenchmarkPermutationFunction measures the speed of the permutation function
+// with no input data.
 func BenchmarkPermutationFunction(b *testing.B) {
-	b.SetBytes(int64(stateSize))
-	var lanes [numLanes]uint64
+	b.SetBytes(int64(200))
+	var lanes [25]uint64
 	for i := 0; i < b.N; i++ {
-		keccakF(&lanes)
+		keccakF1600(&lanes)
 	}
 }
 
-// BenchmarkSingleByteWrite tests the latency from writing a single byte
-func BenchmarkSingleByteWrite(b *testing.B) {
-	b.StopTimer()
-	d := testDigests["Keccak512"]
-	d.Reset()
-	data := sequentialBytes(1) //1 byte buffer
-	b.SetBytes(int64(d.rate()) - 1)
-	b.StartTimer()
-	for i := 0; i < b.N; i++ {
-		d.absorbed = 0 // Reset absorbed to avoid ever calling the permutation function
-
-		// Write all but the last byte of a block, one byte at a time.
-		for j := 0; j < d.rate()-1; j++ {
-			d.Write(data)
-		}
-	}
-	b.StopTimer()
-	d.Reset()
-}
-
-// BenchmarkSingleByteX measures the block write speed for each size of the digest.
-func BenchmarkBlockWrite512(b *testing.B) { benchmarkBlockWrite(b, testDigests["Keccak512"]) }
-func BenchmarkBlockWrite384(b *testing.B) { benchmarkBlockWrite(b, testDigests["Keccak384"]) }
-func BenchmarkBlockWrite256(b *testing.B) { benchmarkBlockWrite(b, testDigests["Keccak256"]) }
-func BenchmarkBlockWrite224(b *testing.B) { benchmarkBlockWrite(b, testDigests["Keccak224"]) }
-
-// benchmarkBulkHash tests the speed to hash a 16 KiB buffer.
-func benchmarkBulkHash(b *testing.B, h hash.Hash) {
+// benchmarkBulkHash tests the speed to hash a buffer of buflen.
+func benchmarkBulkHash(b *testing.B, h hash.Hash, size int) {
 	b.StopTimer()
 	h.Reset()
-	size := 1 << 14
 	data := sequentialBytes(size)
 	b.SetBytes(int64(size))
 	b.StartTimer()
 
-	var digest []byte
+	var state []byte
 	for i := 0; i < b.N; i++ {
 		h.Write(data)
-		digest = h.Sum(digest[:0])
+		state = h.Sum(state[:0])
 	}
 	b.StopTimer()
 	h.Reset()
 }
 
-// benchmarkBulkKeccakX test the speed to hash a 16 KiB buffer by calling benchmarkBulkHash.
-func BenchmarkBulkKeccak512(b *testing.B) { benchmarkBulkHash(b, NewKeccak512()) }
-func BenchmarkBulkKeccak384(b *testing.B) { benchmarkBulkHash(b, NewKeccak384()) }
-func BenchmarkBulkKeccak256(b *testing.B) { benchmarkBulkHash(b, NewKeccak256()) }
-func BenchmarkBulkKeccak224(b *testing.B) { benchmarkBulkHash(b, NewKeccak224()) }
+func BenchmarkSha3_512_MTU(b *testing.B) { benchmarkBulkHash(b, New512(), 1350) }
+func BenchmarkSha3_384_MTU(b *testing.B) { benchmarkBulkHash(b, New384(), 1350) }
+func BenchmarkSha3_256_MTU(b *testing.B) { benchmarkBulkHash(b, New256(), 1350) }
+func BenchmarkSha3_224_MTU(b *testing.B) { benchmarkBulkHash(b, New224(), 1350) }
+func BenchmarkShake256_MTU(b *testing.B) { benchmarkBulkHash(b, newHashShake256(), 1350) }
+func BenchmarkShake128_MTU(b *testing.B) { benchmarkBulkHash(b, newHashShake128(), 1350) }
+
+func BenchmarkSha3_512_1MiB(b *testing.B) { benchmarkBulkHash(b, New512(), 1<<20) }
+func BenchmarkShake256_1MiB(b *testing.B) { benchmarkBulkHash(b, newHashShake256(), 1<<20) }

sha3/shake.go

@@ -0,0 +1,60 @@
+// Copyright 2014 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 sha3
+
+// This file defines the ShakeHash interface, and provides
+// functions for creating SHAKE instances, as well as utility
+// functions for hashing bytes to arbitrary-length output.
+
+import (
+	"io"
+)
+
+// ShakeHash defines the interface to hash functions that
+// support arbitrary-length output.
+type ShakeHash interface {
+	// Write absorbs more data into the hash's state. It panics if input is
+	// written to it after output has been read from it.
+	io.Writer
+
+	// Read reads more output from the hash; reading affects the hash's
+	// state. (ShakeHash.Read is thus very different from Hash.Sum)
+	// It never returns an error.
+	io.Reader
+
+	// Clone returns a copy of the ShakeHash in its current state.
+	Clone() ShakeHash
+
+	// Reset resets the ShakeHash to its initial state.
+	Reset()
+}
+
+func (d *state) Clone() ShakeHash {
+	return d.clone()
+}
+
+// NewShake128 creates a new SHAKE128 variable-output-length ShakeHash.
+// Its generic security strength is 128 bits against all attacks if at
+// least 32 bytes of its output are used.
+func NewShake128() ShakeHash { return &state{rate: 168, dsbyte: 0x1f} }
+
+// NewShake256 creates a new SHAKE128 variable-output-length ShakeHash.
+// Its generic security strength is 256 bits against all attacks if
+// at least 64 bytes of its output are used.
+func NewShake256() ShakeHash { return &state{rate: 136, dsbyte: 0x1f} }
+
+// ShakeSum128 writes an arbitrary-length digest of data into hash.
+func ShakeSum128(hash, data []byte) {
+	h := NewShake128()
+	h.Write(data)
+	h.Read(hash)
+}
+
+// ShakeSum256 writes an arbitrary-length digest of data into hash.
+func ShakeSum256(hash, data []byte) {
+	h := NewShake256()
+	h.Write(data)
+	h.Read(hash)
+}