hash.go

     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.
    61  //
    62  // All [Hash] implementations in the standard library implement this interface,
    63  // unless GOFIPS140=v1.0.0 is set.
    64  //
    65  // If a hash can only determine at runtime if it can be cloned,
    66  // (e.g., if it wraps another hash), it may return [errors.ErrUnsupported].
    67  type Cloner interface {
    68  	Hash
    69  	Clone() (Cloner, error)
    70  }
    71  
    72  // XOF (extendable output function) is a hash function with arbitrary or unlimited output length.
    73  type XOF interface {
    74  	// Write absorbs more data into the XOF's state. It panics if called
    75  	// after Read.
    76  	io.Writer
    77  
    78  	// Read reads more output from the XOF. It may return io.EOF if there
    79  	// is a limit to the XOF output length.
    80  	io.Reader
    81  
    82  	// Reset resets the XOF to its initial state.
    83  	Reset()
    84  
    85  	// BlockSize returns the XOF's underlying block size.
    86  	// The Write method must be able to accept any amount
    87  	// of data, but it may operate more efficiently if all writes
    88  	// are a multiple of the block size.
    89  	BlockSize() int
    90  }
    91
View as plain text