hash

Documentation

Overview

The hash package provides utilities that support use of the stdlib hash.Hash. Most notably is the Fingerprint type that wraps the checksum of a hash.

Conversion between checksums and strings are facailitated through Fingerprint.

Here are some hash-related recipes that bring it all together:

• Extract the SHA384 hash while writing to elsewhere, then get the raw checksum:

  newHash, _ := hash.SHA384() h := newHash() hashingWriter := io.MultiWriter(writer, h) if err := writeAll(hashingWriter); err != nil { ... } fp := hash.NewValidFingerprint(h) checksum := fp.Bytes()

• Extract the SHA384 hash while reading from elsewhere, then get the hex-encoded checksum to send over the wire:

  newHash, _ := hash.SHA384() h := newHash() hashingReader := io.TeeReader(reader, h) if err := processStream(hashingReader); err != nil { ... } fp := hash.NewValidFingerprint(h) hexSum := fp.Hex() req.Header.Set("Content-Sha384", hexSum)

* Turn a checksum sent over the wire back into a fingerprint:

_, validate := hash.SHA384()
hexSum := req.Header.Get("Content-Sha384")
var fp hash.Fingerprint
if len(hexSum) != 0 {
    fp, err = hash.ParseHexFingerprint(hexSum, validate)
    ...
}
if fp.IsZero() {
    ...
}

Index

• func SHA384() (newHash func() hash.Hash, validate func([]byte) error)
• type Fingerprint
  • func GenerateFingerprint(reader io.Reader, newHash func() hash.Hash) (Fingerprint, error)
  • func NewFingerprint(sum []byte, validate func([]byte) error) (Fingerprint, error)
  • func NewValidFingerprint(hash hash.Hash) Fingerprint
  • func ParseBase64Fingerprint(b64Sum string, validate func([]byte) error) (Fingerprint, error)
  • func ParseHexFingerprint(hexSum string, validate func([]byte) error) (Fingerprint, error)
  • func (fp Fingerprint) Base64() string
  • func (fp Fingerprint) Bytes() []byte
  • func (fp Fingerprint) Hex() string
  • func (fp Fingerprint) IsZero() bool
  • func (fp Fingerprint) String() string
  • func (fp Fingerprint) Validate() error
• type HashingWriter
  • func NewHashingWriter(writer io.Writer, hasher hash.Hash) *HashingWriter
  • func (hw HashingWriter) Base64Sum() string
  • func (hw *HashingWriter) Write(data []byte) (int, error)

Functions

func SHA384

func SHA384() (newHash func() hash.Hash, validate func([]byte) error)

SHA384 returns the newHash and validate functions for use with SHA384 hashes. SHA384 is used in several key places in Juju.

Types

type Fingerprint

type Fingerprint struct {
	// contains filtered or unexported fields
}

Fingerprint represents the checksum for some data.

func GenerateFingerprint

func GenerateFingerprint(reader io.Reader, newHash func() hash.Hash) (Fingerprint, error)

GenerateFingerprint returns the fingerprint for the provided data.

func NewFingerprint

func NewFingerprint(sum []byte, validate func([]byte) error) (Fingerprint, error)

NewFingerprint returns wraps the provided raw hash sum. This function roundtrips with Fingerprint.Bytes().

func NewValidFingerprint

func NewValidFingerprint(hash hash.Hash) Fingerprint

NewValidFingerprint returns a Fingerprint corresponding to the current of the provided hash.

func ParseBase64Fingerprint

func ParseBase64Fingerprint(b64Sum string, validate func([]byte) error) (Fingerprint, error)

ParseBase64Fingerprint returns wraps the provided raw fingerprint string. This function roundtrips with Fingerprint.Base64().

func ParseHexFingerprint

func ParseHexFingerprint(hexSum string, validate func([]byte) error) (Fingerprint, error)

ParseHexFingerprint returns wraps the provided raw fingerprint string. This function roundtrips with Fingerprint.Hex().

func (Fingerprint) Base64

func (fp Fingerprint) Base64() string

Base64 returns the base64 encoded fingerprint.

func (Fingerprint) Bytes

func (fp Fingerprint) Bytes() []byte

Bytes returns the raw (sum) bytes of the fingerprint.

func (Fingerprint) Hex

func (fp Fingerprint) Hex() string

Hex returns the hex string representation of the fingerprint.

func (Fingerprint) IsZero

func (fp Fingerprint) IsZero() bool

IsZero returns whether or not the fingerprint is the zero value.

func (Fingerprint) String

func (fp Fingerprint) String() string

String implements fmt.Stringer.

func (Fingerprint) Validate

func (fp Fingerprint) Validate() error

Validate returns an error if the fingerprint is invalid.

type HashingWriter

type HashingWriter struct {
	// contains filtered or unexported fields
}

HashingWriter wraps an io.Writer, providing the checksum of all data written to it. A HashingWriter may be used in place of the writer it wraps.

Note: HashingWriter is deprecated. Please do not use it. We will remove it ASAP.

func NewHashingWriter

func NewHashingWriter(writer io.Writer, hasher hash.Hash) *HashingWriter

NewHashingWriter returns a new HashingWriter that wraps the provided writer and the hasher.

Example:

hw := NewHashingWriter(w, sha1.New())
io.Copy(hw, reader)
hash := hw.Base64Sum()

Note: NewHashingWriter is deprecated. Please do not use it. We will remove it ASAP.

func (HashingWriter) Base64Sum

func (hw HashingWriter) Base64Sum() string

Base64Sum returns the base64 encoded hash.

func (*HashingWriter) Write

func (hw *HashingWriter) Write(data []byte) (int, error)

Write writes to both the wrapped file and the hash.