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 ¶
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 ¶
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") )
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") )
var DigestRegexp = regexp.MustCompile(`[a-zA-Z0-9-_+.]+:[a-fA-F0-9]+`)
DigestRegexp matches valid digest types.
var DigestRegexpAnchored = regexp.MustCompile(`^` + DigestRegexp.String() + `$`)
DigestRegexpAnchored matches valid digest types, anchored to the start and end of the match.
var TarsumRegexp = regexp.MustCompile("tarsum(?:.[a-z0-9]+)?\\+[a-zA-Z0-9]+:[A-Fa-f0-9]+")
TarSumRegexp defines a regular expression to match tarsum identifiers.
var TarsumRegexpCapturing = regexp.MustCompile("(tarsum)(.([a-z0-9]+))?\\+([a-zA-Z0-9]+):([A-Fa-f0-9]+)")
TarsumRegexpCapturing defines a regular expression to match tarsum identifiers with capture groups corresponding to each component.
Functions ¶
func ShortCodeTable ¶
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 TarsumV1SHA256 Algorithm = "tarsum+v1+sha256" // supported tarsum version, verification only // 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 ¶
Available returns true if the digest type is available for use. If this returns false, New and Hash will return nil.
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 FromReader ¶
FromReader returns the most valid digest for the underlying content.
func FromTarArchive ¶
FromTarArchive produces a tarsum digest from reader rd.
func NewDigestFromHex ¶
NewDigestFromHex returns a Digest from alg and a the hex encoded digest.
func ParseDigest ¶
ParseDigest parses s and returns the validated digest object. An error will be returned if the format is invalid.
func (Digest) Algorithm ¶
Algorithm returns the algorithm portion of the digest. This will panic if the underlying digest is not in a valid format.
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 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 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 ommited 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 ¶
Add adds the given digests to the set. An error will be returned if the given digest is invalid. If the digest already exists in the table, this operation will be a no-op.
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 ¶
NewDigestVerifier returns a verifier that compares the written bytes against a passed in digest.
func NewLengthVerifier ¶
NewLengthVerifier returns a verifier that returns true when the number of read bytes equals the expected parameter.
Source Files