← Back to branch summary

~nskaggs/+junk/xenial-test

« back to all changes in this revision

Viewing changes to src/golang.org/x/crypto/sha3/doc.go

  • Committer: Nicholas Skaggs
  • Date: 2016-10-24 20:56:05 UTC
  • Revision ID: nicholas.skaggs@canonical.com-20161024205605-z8lta0uvuhtxwzwl
Initi with beta15

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/golang.org/x/crypto/sha3/doc.go
 
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
// Both types of hash function use the "sponge" construction and the Keccak
 
9
// permutation. For a detailed specification see http://keccak.noekeon.org/
 
10
//
 
11
//
 
12
// Guidance
 
13
//
 
14
// If you aren't sure what function you need, use SHAKE256 with at least 64
 
15
// bytes of output. The SHAKE instances are faster than the SHA3 instances;
 
16
// the latter have to allocate memory to conform to the hash.Hash interface.
 
17
//
 
18
// If you need a secret-key MAC (message authentication code), prepend the
 
19
// secret key to the input, hash with SHAKE256 and read at least 32 bytes of
 
20
// output.
 
21
//
 
22
//
 
23
// Security strengths
 
24
//
 
25
// The SHA3-x (x equals 224, 256, 384, or 512) functions have a security
 
26
// strength against preimage attacks of x bits. Since they only produce "x"
 
27
// bits of output, their collision-resistance is only "x/2" bits.
 
28
//
 
29
// The SHAKE-256 and -128 functions have a generic security strength of 256 and
 
30
// 128 bits against all attacks, provided that at least 2x bits of their output
 
31
// is used.  Requesting more than 64 or 32 bytes of output, respectively, does
 
32
// not increase the collision-resistance of the SHAKE functions.
 
33
//
 
34
//
 
35
// The sponge construction
 
36
//
 
37
// A sponge builds a pseudo-random function from a public pseudo-random
 
38
// permutation, by applying the permutation to a state of "rate + capacity"
 
39
// bytes, but hiding "capacity" of the bytes.
 
40
//
 
41
// A sponge starts out with a zero state. To hash an input using a sponge, up
 
42
// to "rate" bytes of the input are XORed into the sponge's state. The sponge
 
43
// is then "full" and the permutation is applied to "empty" it. This process is
 
44
// repeated until all the input has been "absorbed". The input is then padded.
 
45
// The digest is "squeezed" from the sponge in the same way, except that output
 
46
// output is copied out instead of input being XORed in.
 
47
//
 
48
// A sponge is parameterized by its generic security strength, which is equal
 
49
// to half its capacity; capacity + rate is equal to the permutation's width.
 
50
// Since the KeccakF-1600 permutation is 1600 bits (200 bytes) wide, this means
 
51
// that the security strength of a sponge instance is equal to (1600 - bitrate) / 2.
 
52
//
 
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 // import "golang.org/x/crypto/sha3"