README
¶
sha3
Exported version of golang.org/x/crypto/sha3 for better escape analysis and prevent Write/Read heap allocations.
Documentation
¶
Overview ¶
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. The SHAKE instances are faster than the SHA3 instances; the latter have to allocate memory to conform to the hash.Hash interface.
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 (x equals 224, 256, 384, or 512) 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-256 and -128 functions have a generic security strength of 256 and 128 bits against all attacks, provided that at least 2x bits of their output is used. Requesting more than 64 or 32 bytes of output, respectively, does not increase the collision-resistance of the SHAKE functions.
The sponge construction ¶
A sponge builds a pseudo-random function from a public 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 is then "full" and the permutation is applied to "empty" it. This process is repeated until all the input has been "absorbed". The input is then padded. The digest is "squeezed" from the sponge in the same way, except that output is copied out instead of input being XORed in.
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 the security strength of a sponge instance is equal to (1600 - bitrate) / 2.
Recommendations ¶
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 it 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.
Example (Mac) ¶
k := []byte("this is a secret key; you should generate a strong random key that's at least 32 bytes long")
buf := []byte("and this is some data to authenticate")
// A MAC with 32 bytes of output has 256-bit security strength -- if you use at least a 32-byte-long key.
h := make([]byte, 32)
d := NewShake256()
// Write the key into the hash.
d.Write(k)
// Now write the data.
d.Write(buf)
// Read 32 bytes of output from the hash into h.
d.Read(h)
fmt.Printf("%x\n", h)
Output: 78de2974bd2711d5549ffd32b753ef0f5fa80a0db2556db60f0987eb8a9218ff
Example (Sum) ¶
buf := []byte("some data to hash")
// A hash needs to be 64 bytes long to have 256-bit collision resistance.
h := make([]byte, 64)
// Compute a 64-byte hash of buf and put it in h.
ShakeSum256(h, buf)
fmt.Printf("%x\n", h)
Output: 0f65fe41fc353e52c55667bb9e2b27bfcc8476f2c413e9437d272ee3194a4e3146d05ec04a25d16b8f577c19b82d16b1424c3e022e783d2b4da98de3658d363d
Index ¶
- func New224() hash.Hash
- func New256() hash.Hash
- func New384() hash.Hash
- func New512() hash.Hash
- func ShakeSum128(hash, data []byte)
- func ShakeSum256(hash, data []byte)
- func Sum224(data []byte) (digest [28]byte)
- func Sum256(data []byte) (digest [32]byte)
- func Sum384(data []byte) (digest [48]byte)
- func Sum512(data []byte) (digest [64]byte)
- type HasherState
- func (d *HasherState) BlockSize() int
- func (c *HasherState) Clone() ShakeHash
- func (d *HasherState) Read(out []byte) (n int, err error)
- func (d *HasherState) Reset()
- func (d *HasherState) Size() int
- func (d *HasherState) Sum(in []byte) []byte
- func (d *HasherState) Write(p []byte) (written int, err error)
- type ShakeHash
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New224 ¶
New224 creates a new SHA3-224 hash. Its generic security strength is 224 bits against preimage attacks, and 112 bits against collision attacks.
func New256 ¶
New256 creates a new SHA3-256 hash. Its generic security strength is 256 bits against preimage attacks, and 128 bits against collision attacks.
func New384 ¶
New384 creates a new SHA3-384 hash. Its generic security strength is 384 bits against preimage attacks, and 192 bits against collision attacks.
func New512 ¶
New512 creates a new SHA3-512 hash. Its generic security strength is 512 bits against preimage attacks, and 256 bits against collision attacks.
func ShakeSum128 ¶
func ShakeSum128(hash, data []byte)
ShakeSum128 writes an arbitrary-length digest of data into hash.
func ShakeSum256 ¶
func ShakeSum256(hash, data []byte)
ShakeSum256 writes an arbitrary-length digest of data into hash.
Types ¶
type HasherState ¶
type HasherState struct {
// contains filtered or unexported fields
}
func NewLegacyKeccak256 ¶
func NewLegacyKeccak256() *HasherState
NewLegacyKeccak256 creates a new Keccak-256 hash.
Only use this function if you require compatibility with an existing cryptosystem that uses non-standard padding. All other users should use New256 instead.
func NewLegacyKeccak512 ¶
func NewLegacyKeccak512() *HasherState
NewLegacyKeccak512 creates a new Keccak-512 hash.
Only use this function if you require compatibility with an existing cryptosystem that uses non-standard padding. All other users should use New512 instead.
func (*HasherState) BlockSize ¶
func (d *HasherState) BlockSize() int
BlockSize returns the rate of sponge underlying this hash function.
func (*HasherState) Clone ¶
func (c *HasherState) Clone() ShakeHash
Clone returns copy of SHAKE context within its current state.
func (*HasherState) Read ¶
func (d *HasherState) Read(out []byte) (n int, err error)
Read squeezes an arbitrary number of bytes from the sponge.
func (*HasherState) Reset ¶
func (d *HasherState) Reset()
Reset clears the internal state by zeroing the sponge state and the byte buffer, and setting Sponge.state to absorbing.
func (*HasherState) Size ¶
func (d *HasherState) Size() int
Size returns the output size of the hash function in bytes.
func (*HasherState) Sum ¶
func (d *HasherState) Sum(in []byte) []byte
Sum applies padding to the hash state and then squeezes out the desired number of output bytes. It panics if any output has already been read.
type ShakeHash ¶
type ShakeHash interface {
hash.Hash
// 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, but subsequent calls to Write or Sum
// will panic.
io.Reader
// Clone returns a copy of the ShakeHash in its current state.
Clone() ShakeHash
}
ShakeHash defines the interface to hash functions that support arbitrary-length output. When used as a plain hash.Hash, it produces minimum-length outputs that provide full-strength generic security.
func NewCShake128 ¶
NewCShake128 creates a new instance of cSHAKE128 variable-output-length ShakeHash, a customizable variant of SHAKE128. N is used to define functions based on cSHAKE, it can be empty when plain cSHAKE is desired. S is a customization byte string used for domain separation - two cSHAKE computations on same input with different S yield unrelated outputs. When N and S are both empty, this is equivalent to NewShake128.
func NewCShake256 ¶
NewCShake256 creates a new instance of cSHAKE256 variable-output-length ShakeHash, a customizable variant of SHAKE256. N is used to define functions based on cSHAKE, it can be empty when plain cSHAKE is desired. S is a customization byte string used for domain separation - two cSHAKE computations on same input with different S yield unrelated outputs. When N and S are both empty, this is equivalent to NewShake256.
Example ¶
out := make([]byte, 32)
msg := []byte("The quick brown fox jumps over the lazy dog")
// Example 1: Simple cshake
c1 := NewCShake256([]byte("NAME"), []byte("Partition1"))
c1.Write(msg)
c1.Read(out)
fmt.Println(hex.EncodeToString(out))
// Example 2: Different customization string produces different digest
c1 = NewCShake256([]byte("NAME"), []byte("Partition2"))
c1.Write(msg)
c1.Read(out)
fmt.Println(hex.EncodeToString(out))
// Example 3: Longer output length produces longer digest
out = make([]byte, 64)
c1 = NewCShake256([]byte("NAME"), []byte("Partition1"))
c1.Write(msg)
c1.Read(out)
fmt.Println(hex.EncodeToString(out))
// Example 4: Next read produces different result
c1.Read(out)
fmt.Println(hex.EncodeToString(out))
Output: a90a4c6ca9af2156eba43dc8398279e6b60dcd56fb21837afe6c308fd4ceb05b a8db03e71f3e4da5c4eee9d28333cdd355f51cef3c567e59be5beb4ecdbb28f0 a90a4c6ca9af2156eba43dc8398279e6b60dcd56fb21837afe6c308fd4ceb05b9dd98c6ee866ca7dc5a39d53e960f400bcd5a19c8a2d6ec6459f63696543a0d8 85e73a72228d08b46515553ca3a29d47df3047e5d84b12d6c2c63e579f4fd1105716b7838e92e981863907f434bfd4443c9e56ea09da998d2f9b47db71988109
func NewShake128 ¶
func NewShake128() ShakeHash
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 NewShake256 ¶
func NewShake256() ShakeHash
NewShake256 creates a new SHAKE256 variable-output-length ShakeHash. Its generic security strength is 256 bits against all attacks if at least 64 bytes of its output are used.
Source Files