Version: v20.10.11+incompatible Latest Latest

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

Go to latest
Published: Nov 18, 2021 License: Apache-2.0 Imports: 15 Imported by: 507



Package tarsum provides algorithms to perform checksum calculation on filesystem layers.

The transportation of filesystems, regarding Docker, is done with tar(1) archives. There are a variety of tar serialization formats [2], and a key concern here is ensuring a repeatable checksum given a set of inputs from a generic tar archive. Types of transportation include distribution to and from a registry endpoint, saving and loading through commands or Docker daemon APIs, transferring the build context from client to Docker daemon, and committing the filesystem of a container to become an image.

As tar archives are used for transit, but not preserved in many situations, the focus of the algorithm is to ensure the integrity of the preserved filesystem, while maintaining a deterministic accountability. This includes neither constraining the ordering or manipulation of the files during the creation or unpacking of the archive, nor include additional metadata state about the file system attributes.



This section is empty.


View Source
var (
	ErrNotVersion            = errors.New("string does not include a TarSum Version")
	ErrVersionNotImplemented = errors.New("TarSum Version is not yet implemented")

Errors that may be returned by functions in this package

View Source
var DefaultTHash = NewTHash("sha256", sha256.New)

DefaultTHash is default TarSum hashing algorithm - "sha256".


func VersionLabelForChecksum added in v1.5.0

func VersionLabelForChecksum(checksum string) string

VersionLabelForChecksum returns the label for the given tarsum checksum, i.e., everything before the first `+` character in the string or an empty string if no label separator is found.

func WriteV1Header

func WriteV1Header(h *tar.Header, w io.Writer)

WriteV1Header writes a tar header to a writer in V1 tarsum format.


type BuilderContext added in v1.5.0

type BuilderContext interface {

BuilderContext is an interface extending TarSum by adding the Remove method. In general there was concern about adding this method to TarSum itself so instead it is being added just to "BuilderContext" which will then only be used during the .dockerignore file processing - see builder/evaluator.go

type FileInfoSumInterface added in v1.3.0

type FileInfoSumInterface interface {
	// File name
	Name() string
	// Checksum of this particular file and its headers
	Sum() string
	// Position of file in the tar
	Pos() int64

FileInfoSumInterface provides an interface for accessing file checksum information within a tar file. This info is accessed through interface so the actual name and sum cannot be melded with.

type FileInfoSums added in v1.3.0

type FileInfoSums []FileInfoSumInterface

FileInfoSums provides a list of FileInfoSumInterfaces.

func (FileInfoSums) GetAllFile added in v1.3.0

func (fis FileInfoSums) GetAllFile(name string) FileInfoSums

GetAllFile returns a FileInfoSums with all matching names.

func (FileInfoSums) GetDuplicatePaths added in v1.3.0

func (fis FileInfoSums) GetDuplicatePaths() (dups FileInfoSums)

GetDuplicatePaths returns a FileInfoSums with all duplicated paths.

func (FileInfoSums) GetFile added in v1.3.0

func (fis FileInfoSums) GetFile(name string) FileInfoSumInterface

GetFile returns the first FileInfoSumInterface with a matching name.

func (FileInfoSums) Len added in v1.3.0

func (fis FileInfoSums) Len() int

Len returns the size of the FileInfoSums.

func (FileInfoSums) SortByNames added in v1.3.0

func (fis FileInfoSums) SortByNames()

SortByNames sorts FileInfoSums content by name.

func (FileInfoSums) SortByPos added in v1.3.0

func (fis FileInfoSums) SortByPos()

SortByPos sorts FileInfoSums content by position.

func (FileInfoSums) SortBySums added in v1.3.0

func (fis FileInfoSums) SortBySums()

SortBySums sorts FileInfoSums content by sums.

func (FileInfoSums) Swap added in v1.3.0

func (fis FileInfoSums) Swap(i, j int)

Swap swaps two FileInfoSum values if a FileInfoSums list.

type THash added in v1.3.0

type THash interface {
	Hash() hash.Hash
	Name() string

THash provides a hash.Hash type generator and its name.

func NewTHash added in v1.3.0

func NewTHash(name string, h func() hash.Hash) THash

NewTHash is a convenience method for creating a THash.

type TarSum

type TarSum interface {
	GetSums() FileInfoSums
	Sum([]byte) string
	Version() Version
	Hash() THash

TarSum is the generic interface for calculating fixed time checksums of a tar archive.

func NewTarSum added in v1.3.0

func NewTarSum(r io.Reader, dc bool, v Version) (TarSum, error)

NewTarSum creates a new interface for calculating a fixed time checksum of a tar archive.

This is used for calculating checksums of layers of an image, in some cases including the byte payload of the image's json metadata as well, and for calculating the checksums for buildcache.

func NewTarSumForLabel added in v1.5.0

func NewTarSumForLabel(r io.Reader, disableCompression bool, label string) (TarSum, error)

NewTarSumForLabel creates a new TarSum using the provided TarSum version+hash label.

func NewTarSumHash added in v1.3.0

func NewTarSumHash(r io.Reader, dc bool, v Version, tHash THash) (TarSum, error)

NewTarSumHash creates a new TarSum, providing a THash to use rather than the DefaultTHash.

type Version added in v1.3.0

type Version int

Version is used for versioning of the TarSum algorithm based on the prefix of the hash used i.e. "tarsum+sha256:e58fcf7418d4390dec8e8fb69d88c06ec07039d651fedd3aa72af9972e7d046b"

const (
	Version0 Version = iota
	// VersionDev this constant will be either the latest or an unsettled next-version of the TarSum calculation

Prefix of "tarsum"

func GetVersionFromTarsum added in v1.3.0

func GetVersionFromTarsum(tarsum string) (Version, error)

GetVersionFromTarsum returns the Version from the provided string.

func GetVersions added in v1.3.0

func GetVersions() []Version

GetVersions gets a list of all known tarsum versions.

func (Version) String added in v1.3.0

func (tsv Version) String() string

Jump to

Keyboard shortcuts

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