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 5 // Package sha3 implements the SHA-3 fixed-output-length hash functions and 6 // the SHAKE variable-output-length hash functions defined by FIPS-202. 7 // 8 // All types in this package also implement [encoding.BinaryMarshaler], 9 // [encoding.BinaryAppender] and [encoding.BinaryUnmarshaler] to marshal and 10 // unmarshal the internal state of the hash. 11 // 12 // Both types of hash function use the "sponge" construction and the Keccak 13 // permutation. For a detailed specification see http://keccak.noekeon.org/ 14 // 15 // # Guidance 16 // 17 // If you aren't sure what function you need, use SHAKE256 with at least 64 18 // bytes of output. The SHAKE instances are faster than the SHA3 instances; 19 // the latter have to allocate memory to conform to the hash.Hash interface. 20 // 21 // If you need a secret-key MAC (message authentication code), prepend the 22 // secret key to the input, hash with SHAKE256 and read at least 32 bytes of 23 // output. 24 // 25 // # Security strengths 26 // 27 // The SHA3-x (x equals 224, 256, 384, or 512) functions have a security 28 // strength against preimage attacks of x bits. Since they only produce "x" 29 // bits of output, their collision-resistance is only "x/2" bits. 30 // 31 // The SHAKE-256 and -128 functions have a generic security strength of 256 and 32 // 128 bits against all attacks, provided that at least 2x bits of their output 33 // is used. Requesting more than 64 or 32 bytes of output, respectively, does 34 // not increase the collision-resistance of the SHAKE functions. 35 // 36 // # The sponge construction 37 // 38 // A sponge builds a pseudo-random function from a public pseudo-random 39 // permutation, by applying the permutation to a state of "rate + capacity" 40 // bytes, but hiding "capacity" of the bytes. 41 // 42 // A sponge starts out with a zero state. To hash an input using a sponge, up 43 // to "rate" bytes of the input are XORed into the sponge's state. The sponge 44 // is then "full" and the permutation is applied to "empty" it. This process is 45 // repeated until all the input has been "absorbed". The input is then padded. 46 // The digest is "squeezed" from the sponge in the same way, except that output 47 // is copied out instead of input being XORed in. 48 // 49 // A sponge is parameterized by its generic security strength, which is equal 50 // to half its capacity; capacity + rate is equal to the permutation's width. 51 // Since the KeccakF-1600 permutation is 1600 bits (200 bytes) wide, this means 52 // that the security strength of a sponge instance is equal to (1600 - bitrate) / 2. 53 // 54 // # Recommendations 55 // 56 // The SHAKE functions are recommended for most new uses. They can produce 57 // output of arbitrary length. SHAKE256, with an output length of at least 58 // 64 bytes, provides 256-bit security against all attacks. The Keccak team 59 // recommends it for most applications upgrading from SHA2-512. (NIST chose a 60 // much stronger, but much slower, sponge instance for SHA3-512.) 61 // 62 // The SHA-3 functions are "drop-in" replacements for the SHA-2 functions. 63 // They produce output of the same length, with the same security strengths 64 // against all attacks. This means, in particular, that SHA3-256 only has 65 // 128-bit collision resistance, because its output length is 32 bytes. 66 package sha3 67