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

sha3/shake.go

 // 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"
 )
 
-// Shake defines the interface to hash functions that
+// 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 never returns an error.
+        // Write absorbs more data into the hash's state. It returns an
+        // error is input is written to it after output has been read from

[coruus, 2014/09/03 03:58:08]

*if

+        // it.
         io.Writer
         // Read reads more output from the hash; reading affects the hash's
-        // state. (Shake.Read is thus very different from Hash.Sum)
+        // state. (ShakeHash.Read is thus very different from Hash.Sum)
         // It never returns an error.
         io.Reader
 
-        // Barrier overwrites (200 - rate) bytes of the hash's state
-        // with zeros, making it computationally infeasible to recover
-        // previous inputs.
-        Barrier()
+        // Clone returns a copy of the ShakeHash in its current state.
+        Clone() ShakeHash
 
-        // Reset resets the Hash to its initial state.
+        // Reset resets the ShakeHash to its initial state.
         Reset()
 }
 
-// NewShake128 creates a new SHAKE128 variable-output-length Sponge.
+// Clone returns a copy of the ShakeHash.
+func (d *state) Clone() ShakeHash {
+        // Make a copy of the original hash so that caller can keep writing
+        // and summing.
+        dup := *d
+        return &dup
+}
+
+// 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 Sponge.
+// 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)
 }