seed

Documentation

Overview

Package seed implements loading and validating of seed data.

Index

• Constants
• Variables
• func MockTrusted(mockTrusted []asserts.Assertion) (restore func())
• func ValidateFromYaml(seedYamlFile string) error
• type AutoImportAssertionsLoaderSeed
• type Copier
• type PreseedCapable
• type Seed
  • func Open(seedDir, label string) (Seed, error)
  • func ReadSeedAndBetterEarliestTime(seedDir, label string, earliestTime time.Time, numJobs int, ...) (Seed, time.Time, error)
• type Snap
  • func ReadSystemEssential(seedDir, label string, essentialTypes []snap.Type, tm timings.Measurer) (*asserts.Model, []*Snap, error)
  • func (s *Snap) ID() string
  • func (s *Snap) PlaceInfo() snap.PlaceInfo
  • func (s *Snap) SnapName() string
• type SnapHandler
• type ValidationError
  • func (e *ValidationError) Error() string

Constants

const AllModes = ""

AllModes can be passed to Seed.LoadMeta to load metadata for snaps for all modes.

Variables

var (
	ErrNoAssertions       = errors.New("no seed assertions")
	ErrNoPreseedAssertion = errors.New("no seed preseed assertion")
	ErrNoMeta             = errors.New("no seed metadata")
)

Functions

func MockTrusted

func MockTrusted(mockTrusted []asserts.Assertion) (restore func())

func ValidateFromYaml

func ValidateFromYaml(seedYamlFile string) error

ValidateFromYaml validates the given seed.yaml file and surrounding seed.

Types

type AutoImportAssertionsLoaderSeed

type AutoImportAssertionsLoaderSeed interface {
	// LoadAutoImportAssertions attempts to loads all auto import assertions
	// from the root of the seed.
	LoadAutoImportAssertions(commitTo func(*asserts.Batch) error) error
}

A AutoImportAssertionsLoaderSeed can be used to import all auto import assertions via LoadAutoImportAssertions.

type Copier

type Copier interface {
	Seed
	// Copy copies the seed to the given seedDir with the label provided. If
	// label is empty, then the label of the seed that implements Copier is
	// used. This interface only makes sense to implement for UC20+ seeds. Copy
	// requires you to call the LoadAssertions method first. Note that LoadMeta
	// for all modes will be called by Copy. If LoadMeta was called previously
	// on this Seed with a different mode, then that metadata will be
	// overwritten by the metadata for all modes.
	Copy(seedDir string, label string, tm timings.Measurer) error
}

Copier can be implemented by a seed that supports copying itself to a given destination.

type PreseedCapable

type PreseedCapable interface {
	Seed
	// HasArtifact returns whether the given artifact file is present in the seed.
	HasArtifact(relName string) bool
	// ArtifactPath returns the path of an artifact file in the seed.
	ArtifactPath(relName string) string
	// LoadPreesdAssertion tries to load the preseed assertion from the seed
	// if any. It returns ErrNoPressedAssertion if there is none.
	// It will panic if called before LoadAssertions.
	// Any assertion will be committed using the commitTo provided
	// to LoadAssertions.
	LoadPreseedAssertion() (*asserts.Preseed, error)
}

PreseedCapable seeds can support preseeding data in them.

type Seed

type Seed interface {
	// LoadAssertions loads all assertions from the seed with
	// cross-checks.  A read-only view on an assertions database
	// can be passed in together with a commitTo function which
	// will be used to commit the assertions to the underlying
	// database. If db is nil an internal temporary database will
	// be setup instead. ErrNoAssertions will be returned if there
	// is no assertions directory in the seed, this is legitimate
	// only on classic.
	LoadAssertions(db asserts.RODatabase, commitTo func(*asserts.Batch) error) error

	// Model returns the seed provided model assertion.
	// It will panic if called before LoadAssertions.
	Model() *asserts.Model

	// Brand returns the brand information of the seed.
	// It will panic if called before LoadAssertions.
	Brand() (*asserts.Account, error)

	// SetParallelism suggests that n parallel jobs should be used
	// to load and verify snap metadata by Load*Meta operations.
	// The default is one single job.
	SetParallelism(n int)

	// LoadEssentialMeta loads the seed's snaps metadata for the
	// essential snaps with types in the essentialTypes set while
	// verifying them against assertions. It can return ErrNoMeta
	// if there is no metadata nor snaps in the seed, this is
	// legitimate only on classic. It can be called multiple times
	// if needed before invoking LoadMeta.
	// It will panic if called before LoadAssertions.
	LoadEssentialMeta(essentialTypes []snap.Type, tm timings.Measurer) error

	// LoadEssentialMetaWithSnapHandler loads the seed's snaps metadata
	// for the essential snaps with types in the essentialTypes
	// set while verifying them against assertions. It can return
	// ErrNoMeta if there is no metadata nor snaps in the seed,
	// this is legitimate only on classic. It can be called
	// multiple times if needed before invoking LoadMeta.
	// It will panic if called before LoadAssertions.
	// A SnapHandler can be passed to perform dedicated seed snap
	// handling at the same time as digest computation.
	// No caching of essential snaps across Load*Meta* methods is
	// performed if a handler is provided.
	LoadEssentialMetaWithSnapHandler(essentialTypes []snap.Type, handler SnapHandler, tm timings.Measurer) error

	// LoadMeta loads the seed and seed's snaps metadata while
	// verifying the underlying snaps against assertions. It can
	// return ErrNoMeta if there is no metadata nor snaps in the
	// seed, this is legitimate only on classic.
	// It will panic if called before LoadAssertions.
	// If a precise mode is passed and not AllModes it will
	// load the metadata only for the snaps of that mode.
	// At which point ModeSnaps will only accept that mode
	// and Iter and NumSnaps only consider the snaps for that mode.
	// An optional SnapHandler can be passed to perform dedicated
	// seed snap handling at the same time as digest computation.
	// No caching of essential snaps across Load*Meta* methods is
	// performed if a handler is provided.
	LoadMeta(mode string, handler SnapHandler, tm timings.Measurer) error

	// UsesSnapdSnap returns whether the system as defined by the
	// seed will use the snapd snap, after LoadMeta.
	UsesSnapdSnap() bool

	// EssentialSnaps returns the essential snaps as defined by
	// the seed, after LoadMeta.
	EssentialSnaps() []*Snap

	// ModeSnaps returns the snaps that should be available
	// in the given mode as defined by the seed, after LoadMeta.
	// If LoadMeta was passed a precise mode, passing a different
	// mode here will result in error.
	ModeSnaps(mode string) ([]*Snap, error)

	// NumSnaps returns the total number of snaps for which
	// LoadMeta loaded their metadata.
	NumSnaps() int

	// Iter provides a way to iterately perform a function on
	// each of the snaps for which LoadMeta loaded their metadata.
	Iter(f func(sn *Snap) error) error
}

Seed supports loading assertions and seed snaps' metadata.

func Open

func Open(seedDir, label string) (Seed, error)

Open returns a Seed implementation for the seed at seedDir. label if not empty is used to identify a Core 20 recovery system seed.

func ReadSeedAndBetterEarliestTime

func ReadSeedAndBetterEarliestTime(seedDir, label string, earliestTime time.Time, numJobs int, tm timings.Measurer) (Seed, time.Time, error)

ReadSeedAndBetterEarliestTime retrieves in one go the seed and assertions for the Core 20 recovery system seed specified by seedDir and label (which cannot be empty). numJobs specifies the suggested number of jobs to run in parallel (0 disables parallelism). It can operate even if current system time is unreliable by taking a earliestTime lower bound for current time. It returns as well an improved lower bound by considering appropriate assertions in the seed.

type Snap

type Snap struct {
	Path string

	SideInfo *snap.SideInfo

	// EssentialType is the type of the snap as specified by the model.
	// Provided only for essential snaps (Essential = true).
	EssentialType snap.Type

	Essential bool
	Required  bool

	// options
	Channel string
	DevMode bool
	Classic bool
}

Snap holds the details of a snap in a seed.

func ReadSystemEssential

func ReadSystemEssential(seedDir, label string, essentialTypes []snap.Type, tm timings.Measurer) (*asserts.Model, []*Snap, error)

ReadSystemEssential retrieves in one go information about the model and essential snaps of the given types for the Core 20 recovery system seed specified by seedDir and label (which cannot be empty).

func (*Snap) ID

func (s *Snap) ID() string

func (*Snap) PlaceInfo

func (s *Snap) PlaceInfo() snap.PlaceInfo

PlaceInfo returns a PlaceInfo for the seed snap.

func (*Snap) SnapName

func (s *Snap) SnapName() string

type SnapHandler

type SnapHandler interface {
	// HandleAndDigestAssertedSnap should compute the digest of
	// the given snap and perform any dedicated
	// handling. essentialType is provided only for essential
	// snaps.
	// snapRev is provided by UC20+ seeds.
	// deriveRev is provided by UC16/18 seeds, it can be used
	// to get early access to the snap revision based on the digest.
	// A different path can be returned if the snap has been copied
	// elsewhere.
	HandleAndDigestAssertedSnap(name, path string, essentialType snap.Type, snapRev *asserts.SnapRevision, deriveRev func(snapSHA3_384 string, snapSize uint64) (snap.Revision, error), tm timings.Measurer) (newPath, snapSHA3_384 string, snapSize uint64, err error)

	// HandleUnassertedSnap should perfrom any dedicated handling
	// for the given unasserted snap.
	// A different path can be returned if the snap has been copied
	// elsewhere.
	HandleUnassertedSnap(name, path string, tm timings.Measurer) (newPath string, err error)
}

A SnapHandler can be used to perform any dedicated handling of seed snaps and their digest computation while seed snap metadata loading and verification is being performed.

type ValidationError

type ValidationError struct {
	// SystemErrors maps system labels ("" for UC16/18) to their validation errors.
	SystemErrors map[string][]error
}

func (*ValidationError) Error

func (e *ValidationError) Error() string