sha3

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.

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.

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 ShakeHash
  • func NewShake128() ShakeHash
  • func NewShake256() ShakeHash

Functions

func New224

func New224() hash.Hash

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

func New256() hash.Hash

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

func New384() hash.Hash

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

func New512() hash.Hash

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.

func Sum224

func Sum224(data []byte) (digest [28]byte)

Sum224 returns the SHA3-224 digest of the data.

func Sum256

func Sum256(data []byte) (digest [32]byte)

Sum256 returns the SHA3-256 digest of the data.

func Sum384

func Sum384(data []byte) (digest [48]byte)

Sum384 returns the SHA3-384 digest of the data.

func Sum512

func Sum512(data []byte) (digest [64]byte)

Sum512 returns the SHA3-512 digest of the data.

Types

type ShakeHash

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()
}

ShakeHash defines the interface to hash functions that support arbitrary-length output.

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 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.