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.
6 package hash
7 8 import "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], [encoding.BinaryAppender],
14 // [encoding.BinaryUnmarshaler] and [Cloner] 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
26 type 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.
49 type Hash32 interface {
50 Hash
51 Sum32() uint32
52 }
53 54 // Hash64 is the common interface implemented by all 64-bit hash functions.
55 type Hash64 interface {
56 Hash
57 Sum64() uint64
58 }
59 60 // A Cloner is a hash function whose state can be cloned, returning a value with
61 // equivalent and independent state.
62 //
63 // All [Hash] implementations in the standard library implement this interface,
64 // unless GOFIPS140=v1.0.0 is set.
65 //
66 // If a hash can only determine at runtime if it can be cloned (e.g. if it wraps
67 // another hash), Clone may return an error wrapping [errors.ErrUnsupported].
68 // Otherwise, Clone must always return a nil error.
69 type Cloner interface {
70 Hash
71 Clone() (Cloner, error)
72 }
73 74 // XOF (extendable output function) is a hash function with arbitrary or unlimited output length.
75 type XOF interface {
76 // Write absorbs more data into the XOF's state. It panics if called
77 // after Read.
78 io.Writer
79 80 // Read reads more output from the XOF. It may return io.EOF if there
81 // is a limit to the XOF output length.
82 io.Reader
83 84 // Reset resets the XOF to its initial state.
85 Reset()
86 87 // BlockSize returns the XOF's underlying block size.
88 // The Write method must be able to accept any amount
89 // of data, but it may operate more efficiently if all writes
90 // are a multiple of the block size.
91 BlockSize() int
92 }
93