3cfe9aede5
The Digest type will be fairly central for blob and layer management. The type presented in this package provides a number of core features that should enable reliable use within the registry. This commit will be followed by others that convert the storage layer and webapp to use this type as the primary layer/blob CAS identifier.
52 lines
2.1 KiB
Go
52 lines
2.1 KiB
Go
// This package 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.
|
|
//
|
|
package digest
|