github.com/turingchain2020/turingchain@v1.1.21/common/crypto/sha3/doc.go (about)

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