digest

package
v2.5.0-rc.1+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 14, 2016 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package digest provides a generalized type to opaquely represent message digests and their operations within the registry. The Digest type is designed to serve as a flexible identifier in a content-addressable system. More importantly, it provides tools and wrappers to work with hash.Hash-based digests with little effort.

Basics

The format of a digest is simply a string with two parts, dubbed the "algorithm" and the "digest", separated by a colon:

<algorithm>:<digest>

An example of a sha256 digest representation follows:

sha256:7173b809ca12ec5dee4506cd86be934c4596dd234ee82c0662eac04a8c2c71dc

In this case, the string "sha256" is the algorithm and the hex bytes are the "digest".

Because the Digest type is simply a string, once a valid Digest is obtained, comparisons are cheap, quick and simple to express with the standard equality operator.

Verification

The main benefit of using the Digest type is simple verification against a given digest. The Verifier interface, modeled after the stdlib hash.Hash interface, provides a common write sink for digest verification. After writing is complete, calling the Verifier.Verified method will indicate whether or not the stream of bytes matches the target digest.

Missing Features

In addition to the above, we intend to add the following features to this package:

1. A Digester type that supports write sink digest calculation.

2. Suspend and resume of ongoing digest calculations to support efficient digest verification in the registry.

Index

Constants

View Source
const (
	// DigestSha256EmptyTar is the canonical sha256 digest of empty data
	DigestSha256EmptyTar = "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
)

Variables

View Source
var (
	// ErrDigestInvalidFormat returned when digest format invalid.
	ErrDigestInvalidFormat = fmt.Errorf("invalid checksum digest format")

	// ErrDigestInvalidLength returned when digest has invalid length.
	ErrDigestInvalidLength = fmt.Errorf("invalid checksum digest length")

	// ErrDigestUnsupported returned when the digest algorithm is unsupported.
	ErrDigestUnsupported = fmt.Errorf("unsupported digest algorithm")
)
View Source
var (
	// ErrDigestNotFound is used when a matching digest
	// could not be found in a set.
	ErrDigestNotFound = errors.New("digest not found")

	// ErrDigestAmbiguous is used when multiple digests
	// are found in a set. None of the matching digests
	// should be considered valid matches.
	ErrDigestAmbiguous = errors.New("ambiguous digest string")
)
View Source
var DigestRegexp = regexp.MustCompile(`[a-zA-Z0-9-_+.]+:[a-fA-F0-9]+`)

DigestRegexp matches valid digest types.

View Source
var DigestRegexpAnchored = regexp.MustCompile(`^` + DigestRegexp.String() + `$`)

DigestRegexpAnchored matches valid digest types, anchored to the start and end of the match.

Functions

func ShortCodeTable

func ShortCodeTable(dst *Set, length int) map[Digest]string

ShortCodeTable returns a map of Digest to unique short codes. The length represents the minimum value, the maximum length may be the entire value of digest if uniqueness cannot be achieved without the full value. This function will attempt to make short codes as short as possible to be unique.

Types

type Algorithm

type Algorithm string

Algorithm identifies and implementation of a digester by an identifier. Note the that this defines both the hash algorithm used and the string encoding.

const (
	SHA256 Algorithm = "sha256" // sha256 with hex encoding
	SHA384 Algorithm = "sha384" // sha384 with hex encoding
	SHA512 Algorithm = "sha512" // sha512 with hex encoding

	// Canonical is the primary digest algorithm used with the distribution
	// project. Other digests may be used but this one is the primary storage
	// digest.
	Canonical = SHA256
)

supported digest types

func (Algorithm) Available

func (a Algorithm) Available() bool

Available returns true if the digest type is available for use. If this returns false, New and Hash will return nil.

func (Algorithm) FromBytes

func (a Algorithm) FromBytes(p []byte) Digest

FromBytes digests the input and returns a Digest.

func (Algorithm) FromReader

func (a Algorithm) FromReader(rd io.Reader) (Digest, error)

FromReader returns the digest of the reader using the algorithm.

func (Algorithm) Hash

func (a Algorithm) Hash() hash.Hash

Hash returns a new hash as used by the algorithm. If not available, the method will panic. Check Algorithm.Available() before calling.

func (Algorithm) New

func (a Algorithm) New() Digester

New returns a new digester for the specified algorithm. If the algorithm does not have a digester implementation, nil will be returned. This can be checked by calling Available before calling New.

func (*Algorithm) Set

func (a *Algorithm) Set(value string) error

Set implemented to allow use of Algorithm as a command line flag.

func (Algorithm) Size

func (a Algorithm) Size() int

Size returns number of bytes returned by the hash.

func (Algorithm) String

func (a Algorithm) String() string

type Digest

type Digest string

Digest allows simple protection of hex formatted digest strings, prefixed by their algorithm. Strings of type Digest have some guarantee of being in the correct format and it provides quick access to the components of a digest string.

The following is an example of the contents of Digest types:

sha256:7173b809ca12ec5dee4506cd86be934c4596dd234ee82c0662eac04a8c2c71dc

This allows to abstract the digest behind this type and work only in those terms.

func FromBytes

func FromBytes(p []byte) Digest

FromBytes digests the input and returns a Digest.

func FromReader

func FromReader(rd io.Reader) (Digest, error)

FromReader returns the most valid digest for the underlying content using the canonical digest algorithm.

func NewDigest

func NewDigest(alg Algorithm, h hash.Hash) Digest

NewDigest returns a Digest from alg and a hash.Hash object.

func NewDigestFromBytes

func NewDigestFromBytes(alg Algorithm, p []byte) Digest

NewDigestFromBytes returns a new digest from the byte contents of p. Typically, this can come from hash.Hash.Sum(...) or xxx.SumXXX(...) functions. This is also useful for rebuilding digests from binary serializations.

func NewDigestFromHex

func NewDigestFromHex(alg, hex string) Digest

NewDigestFromHex returns a Digest from alg and a the hex encoded digest.

func ParseDigest

func ParseDigest(s string) (Digest, error)

ParseDigest parses s and returns the validated digest object. An error will be returned if the format is invalid.

func (Digest) Algorithm

func (d Digest) Algorithm() Algorithm

Algorithm returns the algorithm portion of the digest. This will panic if the underlying digest is not in a valid format.

func (Digest) Hex

func (d Digest) Hex() string

Hex returns the hex digest portion of the digest. This will panic if the underlying digest is not in a valid format.

func (Digest) String

func (d Digest) String() string

func (Digest) Validate

func (d Digest) Validate() error

Validate checks that the contents of d is a valid digest, returning an error if not.

type Digester

type Digester interface {
	Hash() hash.Hash // provides direct access to underlying hash instance.
	Digest() Digest
}

Digester calculates the digest of written data. Writes should go directly to the return value of Hash, while calling Digest will return the current value of the digest.

type Set

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

Set is used to hold a unique set of digests which may be easily referenced by easily referenced by a string representation of the digest as well as short representation. The uniqueness of the short representation is based on other digests in the set. If digests are omitted from this set, collisions in a larger set may not be detected, therefore it is important to always do short representation lookups on the complete set of digests. To mitigate collisions, an appropriately long short code should be used.

func NewSet

func NewSet() *Set

NewSet creates an empty set of digests which may have digests added.

func (*Set) Add

func (dst *Set) Add(d Digest) error

Add adds the given digest to the set. An error will be returned if the given digest is invalid. If the digest already exists in the set, this operation will be a no-op.

func (*Set) All

func (dst *Set) All() []Digest

All returns all the digests in the set

func (*Set) Lookup

func (dst *Set) Lookup(d string) (Digest, error)

Lookup looks for a digest matching the given string representation. If no digests could be found ErrDigestNotFound will be returned with an empty digest value. If multiple matches are found ErrDigestAmbiguous will be returned with an empty digest value.

func (*Set) Remove

func (dst *Set) Remove(d Digest) error

Remove removes the given digest from the set. An err will be returned if the given digest is invalid. If the digest does not exist in the set, this operation will be a no-op.

type Verifier

type Verifier interface {
	io.Writer

	// Verified will return true if the content written to Verifier matches
	// the digest.
	Verified() bool
}

Verifier presents a general verification interface to be used with message digests and other byte stream verifications. Users instantiate a Verifier from one of the various methods, write the data under test to it then check the result with the Verified method.

func NewDigestVerifier

func NewDigestVerifier(d Digest) (Verifier, error)

NewDigestVerifier returns a verifier that compares the written bytes against a passed in digest.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL