diff --git a/sha3/doc.go b/sha3/doc.go new file mode 100644 index 0000000..0ba123b --- /dev/null +++ b/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 diff --git a/sha3/hashes.go b/sha3/hashes.go new file mode 100644 index 0000000..6a383c9 --- /dev/null +++ b/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 +} diff --git a/sha3/keccakKats.json.deflate b/sha3/keccakKats.json.deflate new file mode 100644 index 0000000..62e85ae Binary files /dev/null and b/sha3/keccakKats.json.deflate differ diff --git a/sha3/keccakf.go b/sha3/keccakf.go index 76c0312..c267ee0 100644 --- a/sha3/keccakf.go +++ b/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 diff --git a/sha3/sha3.go b/sha3/sha3.go index e1f9aa8..8d77568 100644 --- a/sha3/sha3.go +++ b/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 +// spongeDirection indicates the direction bytes are flowing through the sponge. +type spongeDirection int -// 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 +const ( + // spongeAbsorbing indicates that the sponge is absorbing input. + spongeAbsorbing spongeDirection = iota + // spongeSqueezing indicates that the sponge is being squeezed. + spongeSqueezing +) -// numLanes represents the total number of lanes in the state. -const numLanes = sliceSize * sliceSize +const ( + // maxRate is the maximum size of the internal buffer. SHAKE-256 + // currently needs the largest buffer. + maxRate = 168 +) -// stateSize is the size in bytes of the internal state of SHA3 (5 * 5 * WSize). -const stateSize = laneSize * numLanes +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 -// 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 + // 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 } -// 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 -} +// BlockSize returns the rate of sponge underlying this hash function. +func (d *state) BlockSize() int { return d.rate } -// 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 -} +// Size returns the output size of the hash function in bytes. +func (d *state) Size() int { return d.outputLen } -// 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 +// 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 } + d.state = spongeAbsorbing + d.buf = d.storage[:0] } -// 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() } - -// Size returns the output size of the hash function in bytes. -func (d *digest) Size() int { - return d.outputSize -} - -// 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]) +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] } - offset := (d.absorbed) % d.rate() - t <<= 8 * uint(offset%laneSize) - d.a[offset/laneSize] ^= t - d.absorbed += len(p) + + return &ret } -// 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) +// 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 - // 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 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 + } +} - // For every rate() bytes absorbed, the state must be permuted via the F Function. - if (d.absorbed)%d.rate() == 0 { - keccakF(&d.a) +// 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:] + } +} + +// 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) + } +} + +// 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) +} + +// 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() + } } } - // 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) - - // 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) - } - - offset = 0 - } - - // 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) - } - - return toWrite, nil + return } -// 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 -} - -// 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) -} - -// 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. + + return } -// 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) +// 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...) } - -// 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} } diff --git a/sha3/sha3_test.go b/sha3/sha3_test.go index 05e7c95..bdc3695 100644 --- a/sha3/sha3_test.go +++ b/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", - }, - }, -} - -// 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...) +// 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"` } - for _, tc := range testCases { - for alg, want := range tc.want { - d := testDigests[alg] +} + +// 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) + } + + // 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) } diff --git a/sha3/shake.go b/sha3/shake.go new file mode 100644 index 0000000..841f986 --- /dev/null +++ b/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) +}