endorse

Documentation

Overview

Package endorse defines functions for producing and signing golden measurements of a UEFI.

Index

• Variables
• func GoldenMeasurement(ctx context.Context) (*epb.VMGoldenMeasurement, error)
• func NewContext(ctx context.Context, ec *Context) context.Context
• func RetrySubmit(ctx context.Context, f func(context.Context, ChangeOps) (string, error)) error
• func SignDoc(ctx context.Context, doc *epb.VMGoldenMeasurement) (*epb.VMLaunchEndorsement, error)
• func VirtualFirmware(ctx context.Context) error
• type ChangeOps
• type Context
  • func FromContext(ctx context.Context) (*Context, error)
• type File
• type VersionControl

Variables

var (

	// ErrNoRetries is returned when submit fails too many times to continue attempting submission.
	// The retry amount is settable through Options.
	ErrNoRetries = errors.New("ran out of submit retries")
	// ErrNoEndorseContext is returned when the context.Context object does not contain the
	// EndorseContext.
	ErrNoEndorseContext = errors.New("no EndorseContext found")
	// ManifestFile is the basename of the VMEndorsementMap signature manifest.
	ManifestFile = "manifest.textproto"
	// DefaultEndorsementBasename is used for the file basename (minus file extension) of the signed
	// UEFI golden measurement, AKA the UEFI endorsement.
	DefaultEndorsementBasename = "endorsement"
)

var ErrNoContext = errors.New("no endorse context found")

ErrNoContext is returned when a function requires an endorse.Context is needed but is missing from the context.

Functions

func GoldenMeasurement

func GoldenMeasurement(ctx context.Context) (*epb.VMGoldenMeasurement, error)

GoldenMeasurement produces the unsigned GoldenMeasurement for a given request and all GCE-supported vCPU counts.

func NewContext

func NewContext(ctx context.Context, ec *Context) context.Context

NewContext returns the context extended with the given endorse.Context

func RetrySubmit

func RetrySubmit(ctx context.Context, f func(context.Context, ChangeOps) (string, error)) error

RetrySubmit runs f to attempt a submit transaction without merge conflict or service irregularity. Each attempt should use a fresh workspace to work from the most up-to-date source to both avoid a conflict and drop entries in the manifest due to a write-write data race.

func SignDoc

func SignDoc(ctx context.Context, doc *epb.VMGoldenMeasurement) (*epb.VMLaunchEndorsement, error)

SignDoc returns a signed endorsement of a given golden measurement.

func VirtualFirmware

func VirtualFirmware(ctx context.Context) error

VirtualFirmware calculates the golden measurement of the given OVMF and (if supplied) SVSM image, signs a document with the measurement and associated metadata, and submits it.

Types

type ChangeOps

type ChangeOps interface {
	// WriteOrCreateFiles creates or overwrites all given files with their paired contents, or returns
	// an error.
	WriteOrCreateFiles(ctx context.Context, files ...*File) error
	// ReadFile returns the content of the given file, or an error.
	ReadFile(ctx context.Context, path string) ([]byte, error)
	// SetBinaryWritable sets the metadata of the given file to denote it as binary and writable, and
	// returns nil on success.
	SetBinaryWritable(ctx context.Context, path string) error
	// IsNotFound returns if any errors returned by the implementation should be interpreted as file
	// not found.
	IsNotFound(err error) bool
	// Destroy reclaims any resources this object is using.
	Destroy()
	// TryCommit returns a representation of the successful commit or an error.
	TryCommit(ctx context.Context) (any, error)
}

ChangeOps abstracts file IO for reading, writing, querying files, and committing to the EndorseInterface.

type Context

type Context struct {
	// SevSnp is an optional request for endorsing SEV-SNP-specific information for the image.
	SevSnp *sev.SnpEndorsementRequest
	// Tdx is an optional request for endorsing TDX-specific information for the image.
	Tdx *tdx.EndorsementRequest
	// Image is the full contents of the UEFI binary to endorse.
	Image  []byte
	ClSpec uint64
	// Commit is the git commit hash that corresponds to the ClSpec.
	Commit []byte
	// CandidateName is the name of the candidate from which the image was built.
	CandidateName string
	// ReleaseBranch is the name of the piper branch on which the image was build.
	ReleaseBranch string
	// Timestamp is what time will be reported in the golden measurement document.
	Timestamp time.Time
	VCS       VersionControl
	// VCSs is an array of VCSs to use to commit the signatures. The is seeded for
	// transitioning between systems. This array feeds values to `VCS` for multiple passes
	// through the commit phase after signing. This array is therefore ONLY meant to be accessed
	// in VirtualFirmware. This field WILL be removed after a successful internal transition
	// to the snapshot-to-release-branch-only model.
	VCSs []VersionControl
	// Fields used by VCS when committing an endorsement.
	CommitRetries int
	// OutDir is the VCS-root-relative location in which to write the endorsement files.
	OutDir string
	// DryRun true means that no endorsements will get written to version control.
	DryRun          bool
	MeasurementOnly bool
	// SnapshotDir is the VCS-root-relative location in which to write the snapshot files.
	// Snapshotting is a different VCS commitment method that submits the firmware and its signature
	// to the VCS with related paths. This is in addition to the manifest method to allow for older
	// releases to still get signatures in a way the VMM can parse.
	SnapshotDir string
	// ImageName is the path under SnapshotDir to write the firmware and its endorsement.
	ImageName string
	// SvsmImage is the full contents of the SVSM IGVM, if supplied.
	SvsmImage []byte
	// SvsmSnpMeasurement is expected SEV-SNP measurement of the SVSM, if supplied.
	SvsmSnpMeasurement []byte
}

Context encapsulates all information needed to generate an endorsement for a UEFI binary.

func FromContext

func FromContext(ctx context.Context) (*Context, error)

FromContext returns the endorse.Context in the context or an error.

type File

type File struct {
	Path     string
	Contents []byte
}

File represents a file's path and contents.

type VersionControl

type VersionControl interface {
	// GetChangeOps returns a filesystem abstraction within the context of a commit attempt.
	GetChangeOps(ctx context.Context) (ChangeOps, error)
	// RetriableError returns true if TryCommit's provided error is retriable.
	RetriableError(err error) bool
	// Result stores a successful commit's representation given a successful TryCommit's result and
	// the path to the created endorsement.
	Result(commit any, endorsementPath string)
	// ReleasePath translates a path to its expected full path for WriteOrCreateFiles/ReadFile.
	ReleasePath(ctx context.Context, certPath string) string
}

VersionControl abstracts the necessary operations for transacting signature files into a version control system.