libgo/go/hash/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 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
  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 }