1// Copyright 2014 The Go Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE file.
4
5package sha3
6
7// This file defines the ShakeHash interface, and provides
8// functions for creating SHAKE instances, as well as utility
9// functions for hashing bytes to arbitrary-length output.
10
11import (
12	"io"
13)
14
15// ShakeHash defines the interface to hash functions that
16// support arbitrary-length output.
17type ShakeHash interface {
18	// Write absorbs more data into the hash's state. It panics if input is
19	// written to it after output has been read from it.
20	io.Writer
21
22	// Read reads more output from the hash; reading affects the hash's
23	// state. (ShakeHash.Read is thus very different from Hash.Sum)
24	// It never returns an error.
25	io.Reader
26
27	// Clone returns a copy of the ShakeHash in its current state.
28	Clone() ShakeHash
29
30	// Reset resets the ShakeHash to its initial state.
31	Reset()
32}
33
34func (d *state) Clone() ShakeHash {
35	return d.clone()
36}
37
38// NewShake128 creates a new SHAKE128 variable-output-length ShakeHash.
39// Its generic security strength is 128 bits against all attacks if at
40// least 32 bytes of its output are used.
41func NewShake128() ShakeHash { return &state{rate: 168, dsbyte: 0x1f} }
42
43// NewShake256 creates a new SHAKE128 variable-output-length ShakeHash.
44// Its generic security strength is 256 bits against all attacks if
45// at least 64 bytes of its output are used.
46func NewShake256() ShakeHash { return &state{rate: 136, dsbyte: 0x1f} }
47
48// ShakeSum128 writes an arbitrary-length digest of data into hash.
49func ShakeSum128(hash, data []byte) {
50	h := NewShake128()
51	h.Write(data)
52	h.Read(hash)
53}
54
55// ShakeSum256 writes an arbitrary-length digest of data into hash.
56func ShakeSum256(hash, data []byte) {
57	h := NewShake256()
58	h.Write(data)
59	h.Read(hash)
60}
61