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
  5package sha3
  6
  7// This file provides functions for creating instances of the SHA-3
  8// and SHAKE hash functions, as well as utility functions for hashing
  9// bytes.
 10
 11import (
 12	"crypto"
 13	"hash"
 14)
 15
 16// New224 creates a new SHA3-224 hash.
 17// Its generic security strength is 224 bits against preimage attacks,
 18// and 112 bits against collision attacks.
 19func New224() hash.Hash {
 20	return new224()
 21}
 22
 23// New256 creates a new SHA3-256 hash.
 24// Its generic security strength is 256 bits against preimage attacks,
 25// and 128 bits against collision attacks.
 26func New256() hash.Hash {
 27	return new256()
 28}
 29
 30// New384 creates a new SHA3-384 hash.
 31// Its generic security strength is 384 bits against preimage attacks,
 32// and 192 bits against collision attacks.
 33func New384() hash.Hash {
 34	return new384()
 35}
 36
 37// New512 creates a new SHA3-512 hash.
 38// Its generic security strength is 512 bits against preimage attacks,
 39// and 256 bits against collision attacks.
 40func New512() hash.Hash {
 41	return new512()
 42}
 43
 44func init() {
 45	crypto.RegisterHash(crypto.SHA3_224, New224)
 46	crypto.RegisterHash(crypto.SHA3_256, New256)
 47	crypto.RegisterHash(crypto.SHA3_384, New384)
 48	crypto.RegisterHash(crypto.SHA3_512, New512)
 49}
 50
 51const (
 52	dsbyteSHA3   = 0b00000110
 53	dsbyteKeccak = 0b00000001
 54	dsbyteShake  = 0b00011111
 55	dsbyteCShake = 0b00000100
 56
 57	// rateK[c] is the rate in bytes for Keccak[c] where c is the capacity in
 58	// bits. Given the sponge size is 1600 bits, the rate is 1600 - c bits.
 59	rateK256  = (1600 - 256) / 8
 60	rateK448  = (1600 - 448) / 8
 61	rateK512  = (1600 - 512) / 8
 62	rateK768  = (1600 - 768) / 8
 63	rateK1024 = (1600 - 1024) / 8
 64)
 65
 66func new224Generic() *state {
 67	return &state{rate: rateK448, outputLen: 28, dsbyte: dsbyteSHA3}
 68}
 69
 70func new256Generic() *state {
 71	return &state{rate: rateK512, outputLen: 32, dsbyte: dsbyteSHA3}
 72}
 73
 74func new384Generic() *state {
 75	return &state{rate: rateK768, outputLen: 48, dsbyte: dsbyteSHA3}
 76}
 77
 78func new512Generic() *state {
 79	return &state{rate: rateK1024, outputLen: 64, dsbyte: dsbyteSHA3}
 80}
 81
 82// NewLegacyKeccak256 creates a new Keccak-256 hash.
 83//
 84// Only use this function if you require compatibility with an existing cryptosystem
 85// that uses non-standard padding. All other users should use New256 instead.
 86func NewLegacyKeccak256() hash.Hash {
 87	return &state{rate: rateK512, outputLen: 32, dsbyte: dsbyteKeccak}
 88}
 89
 90// NewLegacyKeccak512 creates a new Keccak-512 hash.
 91//
 92// Only use this function if you require compatibility with an existing cryptosystem
 93// that uses non-standard padding. All other users should use New512 instead.
 94func NewLegacyKeccak512() hash.Hash {
 95	return &state{rate: rateK1024, outputLen: 64, dsbyte: dsbyteKeccak}
 96}
 97
 98// Sum224 returns the SHA3-224 digest of the data.
 99func Sum224(data []byte) (digest [28]byte) {
100	h := New224()
101	h.Write(data)
102	h.Sum(digest[:0])
103	return
104}
105
106// Sum256 returns the SHA3-256 digest of the data.
107func Sum256(data []byte) (digest [32]byte) {
108	h := New256()
109	h.Write(data)
110	h.Sum(digest[:0])
111	return
112}
113
114// Sum384 returns the SHA3-384 digest of the data.
115func Sum384(data []byte) (digest [48]byte) {
116	h := New384()
117	h.Write(data)
118	h.Sum(digest[:0])
119	return
120}
121
122// Sum512 returns the SHA3-512 digest of the data.
123func Sum512(data []byte) (digest [64]byte) {
124	h := New512()
125	h.Write(data)
126	h.Sum(digest[:0])
127	return
128}