1// Copyright 2009 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 hash provides interfaces for hash functions.
6package hash
7
8import "io"
9
10// Hash is the common interface implemented by all hash functions.
11//
12// Hash implementations in the standard library (e.g. hash/crc32 and
13// crypto/sha256) implement the encoding.BinaryMarshaler and
14// encoding.BinaryUnmarshaler interfaces. Marshaling a hash implementation
15// allows its internal state to be saved and used for additional processing
16// later, without having to re-write the data previously written to the hash.
17// The hash state may contain portions of the input in its original form,
18// which users are expected to handle for any possible security implications.
19//
20// Compatibility: Any future changes to hash or crypto packages will endeavor
21// to maintain compatibility with state encoded using previous versions.
22// That is, any released versions of the packages should be able to
23// decode data written with any previously released version,
24// subject to issues such as security fixes.
25// See the Go compatibility document for background: https://golang.org/doc/go1compat
26type Hash interface {
27	// Write (via the embedded io.Writer interface) adds more data to the running hash.
28	// It never returns an error.
29	io.Writer
30
31	// Sum appends the current hash to b and returns the resulting slice.
32	// It does not change the underlying hash state.
33	Sum(b []byte) []byte
34
35	// Reset resets the Hash to its initial state.
36	Reset()
37
38	// Size returns the number of bytes Sum will return.
39	Size() int
40
41	// BlockSize returns the hash's underlying block size.
42	// The Write method must be able to accept any amount
43	// of data, but it may operate more efficiently if all writes
44	// are a multiple of the block size.
45	BlockSize() int
46}
47
48// Hash32 is the common interface implemented by all 32-bit hash functions.
49type Hash32 interface {
50	Hash
51	Sum32() uint32
52}
53
54// Hash64 is the common interface implemented by all 64-bit hash functions.
55type Hash64 interface {
56	Hash
57	Sum64() uint64
58}
59