doc.go 3.1 KB

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