conformance

type BlobFetcher ¶

type BlobFetcher func(digest string) ([]byte, error)

BlobFetcher supplies a blob by digest.

The digest is the caller's to verify or not; this package verifies every blob it receives regardless, which is what lets the same code check a layout on disk and a response from a registry.

type FileRecord ¶

type FileRecord struct {
	Path   string
	Mode   uint32
	Size   int64
	Digest string
}

FileRecord is one canonical file.

type Level ¶ added in v0.4.0

type Level int

Level selects how much of the specification a verification applies.

The three levels answer three different questions, and conflating them is how an implementation ends up claiming more than it checked:

• LevelStructure asks whether the artifact is intact and internally consistent, and whether expanding it is safe. Every digest is recomputed, the inventory is compared against what the layer actually held, and no path may escape the destination.
• LevelCanonical asks whether these are the only bytes a conforming writer could have produced for this tree. Entry order, fixed header fields, the extended-header restriction, the frozen gzip header, RFC 8785 member order, and the portable path rules are all in this level and none of them affect whether the artifact can be read.
• LevelBytes asks whether a writer reproduces the published vectors exactly. That is a property of an implementation rather than of an artifact: it is checked by building the documented input tree and comparing the result with vectors/format/v1. VerifyVectors runs the comparison for the published files themselves.

A deviation found above the requested level is reported in Report.Deviations rather than discarded, so a level-1 pass still says what it tolerated.

const (
	// LevelStructure verifies structure and integrity.
	LevelStructure Level = iota + 1
	// LevelCanonical adds every rule that makes the encoding the only one.
	LevelCanonical
	// LevelBytes adds agreement with the published byte vectors.
	LevelBytes
)

func (l Level) String() string

type Report ¶

type Report struct {
	// Level is the level the read was performed at.
	Level Level
	// Deviations are canonical-encoding differences found while reading.
	//
	// At [LevelCanonical] a read fails on the first one, so this is empty or
	// the read returned an error. At [LevelStructure] it is the list of things
	// the pass tolerated, which is the difference between "verified" and
	// "verified, and here is what a stricter reader would have said".
	Deviations []string

	// ManifestDigest is the subject identity: sha256 over the manifest bytes.
	ManifestDigest string
	// TreeDigest is recomputed here from the layer, not read from the config.
	TreeDigest string
	// ConfigTreeDigest is what the config claimed.
	ConfigTreeDigest string
	FileCount        int64
	TotalSize        int64
	// Files is the inventory as recomputed from the layer.
	Files []FileRecord
}

Report is what an independent read established.

func VerifyLayout(dir, reference string, level Level) (*Report, error)

func VerifyManifest(manifestBytes []byte, fetch BlobFetcher, level Level) (*Report, error)

func VerifyVectors(fsys fs.FS) (*Report, error)

type Vector ¶ added in v0.4.0

type Vector string

Vector names one published byte vector.

const (
	VectorManifest      Vector = "manifest.json"
	VectorConfig        Vector = "config.json"
	VectorLayer         Vector = "layer.tar.gz"
	VectorLayerTar      Vector = "layer.tar"
	VectorTreeRecords   Vector = "tree-records.bin"
	VectorTreeDigest    Vector = "tree-digest.txt"
	VectorSubjectDigest Vector = "subject-digest.txt"
	VectorGzipSample    Vector = "gzip-sample.gz"
)