package sha3

Import Path
	vendor/golang.org/x/crypto/sha3 (on go.dev)

Dependency Relation
	imports 7 packages, and imported by 2 packages

Involved Source Files

	  d doc.go
		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.

	    hashes.go
	    hashes_noasm.go
	    keccakf_amd64.go
	    register.go
	    sha3.go
	    shake.go
	    shake_noasm.go
	    xor.go
	    keccakf_amd64.s
Package-Level Type Names (total 4, in which 1 is exported)

	/* sort exporteds by: alphabet | popularity */
	 type ShakeHash (interface)
		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.

		Methods (total 7, all are exported)
			( ShakeHash) BlockSize() int
				BlockSize returns the hash's underlying block size.
				The Write method must be able to accept any amount
				of data, but it may operate more efficiently if all writes
				are a multiple of the block size.

			( ShakeHash) Clone() ShakeHash
				Clone returns a copy of the ShakeHash in its current state.

			( ShakeHash) Read(p []byte) (n int, err error)
			( ShakeHash) Reset()
				Reset resets the Hash to its initial state.

			( ShakeHash) Size() int
				Size returns the number of bytes Sum will return.

			( ShakeHash) Sum(b []byte) []byte
				Sum appends the current hash to b and returns the resulting slice.
				It does not change the underlying hash state.

			( ShakeHash) Write([]byte) (int, error)
		Implemented By (at least 2, neither is exported)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			*cshakeState
			*state
		Implements (at least 6, in which 5 are exported)
			 ShakeHash : hash.Hash
			 ShakeHash : internal/bisect.Writer
			 ShakeHash : io.Reader
			 ShakeHash : io.ReadWriter
			 ShakeHash : io.Writer
			/* at least one unexported ... *//* at least one unexported: */
			 ShakeHash : crypto/tls.transcriptHash
		As Outputs Of (at least 6, in which 5 are exported)
			func NewCShake128(N, S []byte) ShakeHash
			func NewCShake256(N, S []byte) ShakeHash
			func NewShake128() ShakeHash
			func NewShake256() ShakeHash
			func ShakeHash.Clone() ShakeHash
			/* at least one unexported ... *//* at least one unexported: */
			func newCShake(N, S []byte, rate, outputLen int, dsbyte byte) ShakeHash

	/* 3 unexporteds ... *//* 3 unexporteds: */
	 type cshakeState (struct)
		cSHAKE specific context

		Fields (total 9, none are exported)
			/* 9 unexporteds ... *//* 9 unexporteds: */
			initBlock []byte
				initBlock is the cSHAKE specific initialization set of bytes. It is initialized
				by newCShake function and stores concatenation of N followed by S, encoded
				by the method specified in 3.3 of [1].
				It is stored here in order for Reset() to be able to put context into
				initial state.

			state *state
				// SHA-3 state context and Read/Write operations

			state.a [25]uint64
				Generic sponge components.
				// main state of the hash

			state.dsbyte byte
				dsbyte contains the "domain separation" bits and the first bit of
				the padding. Sections 6.1 and 6.2 of [1] separate the outputs of the
				SHA-3 and SHAKE functions by appending bitstrings to the message.
				Using a little-endian bit-ordering convention, these are "01" for SHA-3
				and "1111" for SHAKE, or 00000010b and 00001111b, respectively. Then the
				padding rule from section 5.1 is applied to pad the message to a multiple
				of the rate, which involves adding a "1" bit, zero or more "0" bits, and
				a final "1" bit. We merge the first "1" bit from the padding into dsbyte,
				giving 00000110b (0x06) and 00011111b (0x1f).
				[1] http://csrc.nist.gov/publications/drafts/fips-202/fips_202_draft.pdf
				    "Draft FIPS 202: SHA-3 Standard: Permutation-Based Hash and
				     Extendable-Output Functions (May 2014)"

			state.i int
				// storage[i:n] is the buffer, i is only used while squeezing

			state.n int
				// storage[i:n] is the buffer, i is only used while squeezing

			state.outputLen int
				Specific to SHA-3 and SHAKE.
				// the default output size in bytes

			state.rate int
				// the number of bytes of state to use

			state.storage [168]byte
		Methods (total 10, in which 7 are exported)
			( cshakeState) BlockSize() int
				BlockSize returns the rate of sponge underlying this hash function.

			(*cshakeState) Clone() ShakeHash
				Clone returns copy of a cSHAKE context within its current state.

			( cshakeState) Read(out []byte) (n int, err error)
				Read squeezes an arbitrary number of bytes from the sponge.

			(*cshakeState) Reset()
				Reset resets the hash to initial state.

			( cshakeState) Size() int
				Size returns the output size of the hash function in bytes.

			( cshakeState) 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.

			( cshakeState) Write(p []byte) (written int, err error)
				Write absorbs more data into the hash's state. It panics if any
				output has already been read.

			/* 3 unexporteds ... *//* 3 unexporteds: */
			( cshakeState) clone() *state
			( cshakeState) padAndPermute()
				pads appends the domain separation bits in dsbyte, applies
				the multi-bitrate 10..1 padding rule, and permutes the state.

			( cshakeState) permute()
				permute applies the KeccakF-1600 permutation. It handles
				any input-output buffering.

		Implements (at least 7, in which 6 are exported)
			*cshakeState : ShakeHash
			*cshakeState : hash.Hash
			 cshakeState : internal/bisect.Writer
			 cshakeState : io.Reader
			 cshakeState : io.ReadWriter
			 cshakeState : io.Writer
			/* at least one unexported ... *//* at least one unexported: */
			 cshakeState : crypto/tls.transcriptHash

	 type spongeDirection int (basic type)
		spongeDirection indicates the direction bytes are flowing through the sponge.

		As Types Of (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			const spongeAbsorbing
			const spongeSqueezing

	 type state (struct)

		Fields (total 8, none are exported)
			/* 8 unexporteds ... *//* 8 unexporteds: */
			a [25]uint64
				Generic sponge components.
				// main state of the hash

			dsbyte byte
				dsbyte contains the "domain separation" bits and the first bit of
				the padding. Sections 6.1 and 6.2 of [1] separate the outputs of the
				SHA-3 and SHAKE functions by appending bitstrings to the message.
				Using a little-endian bit-ordering convention, these are "01" for SHA-3
				and "1111" for SHAKE, or 00000010b and 00001111b, respectively. Then the
				padding rule from section 5.1 is applied to pad the message to a multiple
				of the rate, which involves adding a "1" bit, zero or more "0" bits, and
				a final "1" bit. We merge the first "1" bit from the padding into dsbyte,
				giving 00000110b (0x06) and 00011111b (0x1f).
				[1] http://csrc.nist.gov/publications/drafts/fips-202/fips_202_draft.pdf
				    "Draft FIPS 202: SHA-3 Standard: Permutation-Based Hash and
				     Extendable-Output Functions (May 2014)"

			i int
				// storage[i:n] is the buffer, i is only used while squeezing

			n int
				// storage[i:n] is the buffer, i is only used while squeezing

			outputLen int
				Specific to SHA-3 and SHAKE.
				// the default output size in bytes

			rate int
				// the number of bytes of state to use

			state spongeDirection
				// whether the sponge is absorbing or squeezing

			storage [168]byte
		Methods (total 10, in which 7 are exported)
			(*state) BlockSize() int
				BlockSize returns the rate of sponge underlying this hash function.

			(*state) Clone() ShakeHash
				Clone returns copy of SHAKE context within its current state.

			(*state) Read(out []byte) (n int, err error)
				Read squeezes an arbitrary number of bytes from the sponge.

			(*state) Reset()
				Reset clears the internal state by zeroing the sponge state and
				the buffer indexes, and setting Sponge.state to absorbing.

			(*state) Size() int
				Size returns the output size of the hash function in bytes.

			(*state) 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.

			(*state) Write(p []byte) (written int, err error)
				Write absorbs more data into the hash's state. It panics if any
				output has already been read.

			/* 3 unexporteds ... *//* 3 unexporteds: */
			(*state) clone() *state
			(*state) padAndPermute()
				pads appends the domain separation bits in dsbyte, applies
				the multi-bitrate 10..1 padding rule, and permutes the state.

			(*state) permute()
				permute applies the KeccakF-1600 permutation. It handles
				any input-output buffering.

		Implements (at least 7, in which 6 are exported)
			*state : ShakeHash
			*state : hash.Hash
			*state : internal/bisect.Writer
			*state : io.Reader
			*state : io.ReadWriter
			*state : io.Writer
			/* at least one unexported ... *//* at least one unexported: */
			*state : crypto/tls.transcriptHash
		As Outputs Of (at least 12, none are exported)
			/* 12+ unexporteds ... *//* 12+ unexporteds: */
			func new224() *state
			func new224Generic() *state
			func new256() *state
			func new256Generic() *state
			func new384() *state
			func new384Generic() *state
			func new512() *state
			func new512Generic() *state
			func newShake128() *state
			func newShake128Generic() *state
			func newShake256() *state
			func newShake256Generic() *state
		As Inputs Of (at least 2, neither is exported)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func copyOut(d *state, b []byte)
			func xorIn(d *state, buf []byte)


Package-Level Functions (total 35, in which 16 are exported)

	 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() 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() 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() 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 NewCShake128(N, S []byte) ShakeHash
		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(N, S []byte) ShakeHash
		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.

	 func NewLegacyKeccak256() hash.Hash
		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() hash.Hash
		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 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() 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.

	 func ShakeSum128(hash, data []byte)
		ShakeSum128 writes an arbitrary-length digest of data into hash.

	 func ShakeSum256(hash, data []byte)
		ShakeSum256 writes an arbitrary-length digest of data into hash.

	 func Sum224(data []byte) (digest [28]byte)
		Sum224 returns the SHA3-224 digest of the data.

	 func Sum256(data []byte) (digest [32]byte)
		Sum256 returns the SHA3-256 digest of the data.

	 func Sum384(data []byte) (digest [48]byte)
		Sum384 returns the SHA3-384 digest of the data.

	 func Sum512(data []byte) (digest [64]byte)
		Sum512 returns the SHA3-512 digest of the data.

	/* 19 unexporteds ... *//* 19 unexporteds: */
	 func bytepad(input []byte, w int) []byte
	 func copyOut(d *state, b []byte)
		copyOut copies uint64s to a byte buffer.

	 func init()
	 func keccakF1600(a *[25]uint64)
	 func leftEncode(value uint64) []byte
	 func new224() *state
	 func new224Generic() *state
	 func new256() *state
	 func new256Generic() *state
	 func new384() *state
	 func new384Generic() *state
	 func new512() *state
	 func new512Generic() *state
	 func newCShake(N, S []byte, rate, outputLen int, dsbyte byte) ShakeHash
	 func newShake128() *state
	 func newShake128Generic() *state
	 func newShake256() *state
	 func newShake256Generic() *state
	 func xorIn(d *state, buf []byte)
		xorIn xors the bytes in buf into the state.


Package-Level Constants (total 7, none are exported)

	/* 7 unexporteds ... *//* 7 unexporteds: */
	const dsbyteCShake = 4
		Consts for configuring initial SHA-3 state

	const dsbyteShake = 31
		Consts for configuring initial SHA-3 state

	const maxRate = 168
		maxRate is the maximum size of the internal buffer. SHAKE-256
		currently needs the largest buffer.

	const rate128 = 168
		Consts for configuring initial SHA-3 state

	const rate256 = 136
		Consts for configuring initial SHA-3 state

	const spongeAbsorbing spongeDirection = 0
		spongeAbsorbing indicates that the sponge is absorbing input.

	const spongeSqueezing spongeDirection = 1
		spongeSqueezing indicates that the sponge is being squeezed.

The pages are generated with Golds v0.7.6. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.