digest

package
Version: v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Jun 18, 2015 License: Apache-2.0, Apache-2.0 Imports: 13 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 tarsums and 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". A tarsum example will be more illustrative of the use case involved in the registry:

tarsum+sha256:e58fcf7418d4390dec8e8fb69d88c06ec07039d651fedd3aa72af9972e7d046b

For this, we consider the algorithm to be "tarsum+sha256". Prudent applications will favor the ParseDigest function to verify the format over using simple type casts. However, a normal string can be cast as a digest with a simple type conversion:

Digest("tarsum+sha256:e58fcf7418d4390dec8e8fb69d88c06ec07039d651fedd3aa72af9972e7d046b")

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 (
	// DigestTarSumV1EmptyTar is the digest for the empty tar file.
	DigestTarSumV1EmptyTar = "tarsum.v1+sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
	// 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")

	// ErrDigestUnsupported returned when the digest algorithm is unsupported.
	ErrDigestUnsupported = fmt.Errorf("unsupported digest algorithm")
)
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.

View Source
var TarsumRegexp = regexp.MustCompile("tarsum(?:.[a-z0-9]+)?\\+[a-zA-Z0-9]+:[A-Fa-f0-9]+")

TarSumRegexp defines a reguler expression to match tarsum identifiers.

View Source
var TarsumRegexpCapturing = regexp.MustCompile("(tarsum)(.([a-z0-9]+))?\\+([a-zA-Z0-9]+):([A-Fa-f0-9]+)")

TarsumRegexpCapturing defines a reguler expression to match tarsum identifiers with capture groups corresponding to each component.

Functions

This section is empty.

Types

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

More important for this code base, this type is compatible with tarsum digests. For example, the following would be a valid Digest:

tarsum+sha256:e58fcf7418d4390dec8e8fb69d88c06ec07039d651fedd3aa72af9972e7d046b

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

func FromBytes

func FromBytes(p []byte) (Digest, error)

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.

func FromTarArchive

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

FromTarArchive produces a tarsum digest from reader rd.

func NewDigest

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

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

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() string

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 struct {
	hash.Hash
	// contains filtered or unexported fields
}

Digester calculates the digest of written data. It is functionally equivalent to hash.Hash but provides methods for returning the Digest type rather than raw bytes.

func NewCanonicalDigester

func NewCanonicalDigester() Digester

NewCanonicalDigester is a convenience function to create a new Digester with our default settings.

func NewDigester

func NewDigester(alg string, h hash.Hash) Digester

NewDigester create a new Digester with the given hashing algorithm and instance of that algo's hasher.

func (*Digester) Digest

func (d *Digester) Digest() Digest

Digest returns the current digest for this digester.

type InvalidTarSumError

type InvalidTarSumError string

InvalidTarSumError provides informations about a TarSum that cannot be parsed by ParseTarSum.

func (InvalidTarSumError) Error

func (e InvalidTarSumError) Error() string

type ResumableDigester added in v0.5.1

type ResumableDigester interface {
	ResumableHash
	Digest() Digest
}

ResumableDigester is a digester that can export its internal state and be restored from saved state.

func NewCanonicalResumableDigester added in v0.5.1

func NewCanonicalResumableDigester() ResumableDigester

NewCanonicalResumableDigester creates a ResumableDigester using the default digest algorithm.

func NewResumableDigester added in v0.5.1

func NewResumableDigester(alg string) (ResumableDigester, error)

NewResumableDigester creates a new ResumableDigester with the given hashing algorithm.

type ResumableHash added in v0.5.1

type ResumableHash interface {
	// ResumableHash is a superset of hash.Hash
	hash.Hash
	// Len returns the number of bytes written to the Hash so far.
	Len() uint64
	// State returns a snapshot of the state of the Hash.
	State() ([]byte, error)
	// Restore resets the Hash to the given state.
	Restore(state []byte) error
}

ResumableHash is the common interface implemented by all resumable hash functions.

type TarSumInfo

type TarSumInfo struct {
	// Version contains the version of the tarsum.
	Version string

	// Algorithm contains the algorithm for the final digest
	Algorithm string

	// Digest contains the hex-encoded digest.
	Digest string
}

TarSumInfo contains information about a parsed tarsum.

func ParseTarSum

func ParseTarSum(tarSum string) (tsi TarSumInfo, err error)

ParseTarSum parses a tarsum string into its components of interest. For example, this method may receive the tarsum in the following format:

tarsum.v1+sha256:220a60ecd4a3c32c282622a625a54db9ba0ff55b5ba9c29c7064a2bc358b6a3e

The function will return the following:

TarSumInfo{
	Version: "v1",
	Algorithm: "sha256",
	Digest: "220a60ecd4a3c32c282622a625a54db9ba0ff55b5ba9c29c7064a2bc358b6a3e",
}

func (TarSumInfo) String

func (tsi TarSumInfo) String() string

String returns the valid, string representation of the tarsum info.

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.

func NewLengthVerifier

func NewLengthVerifier(expected int64) Verifier

NewLengthVerifier returns a verifier that returns true when the number of read bytes equals the expected parameter.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL