measurements

Documentation

Overview

Measurements

Defines default expected measurements for the current release, as well as functions for comparing, updating and marshalling measurements.

This package should not include TPM specific code.

Index

• Constants
• type ImageMeasurementsV2
  • func MergeImageMeasurementsV2(measurements ...ImageMeasurementsV2) (ImageMeasurementsV2, error)
• type ImageMeasurementsV2Entry
• type M
  • func ApplyOverrides(in M, csp cloudprovider.Provider, attestationVariant string) (M, error)
  • func DefaultsFor(provider cloudprovider.Provider, attestationVariant variant.Variant) M
  • func (m M) Compare(other map[uint32][]byte) (warnings []string, errs []error)
  • func (m *M) Copy() M
  • func (m *M) CopyFrom(other M)
  • func (m *M) EqualTo(other M) bool
  • func (m *M) FetchAndVerify(ctx context.Context, client *http.Client, verifier cosignVerifier, ...) (string, error)
  • func (m *M) FetchNoVerify(ctx context.Context, client *http.Client, measurementsURL *url.URL, ...) error
  • func (m *M) GetEnforced() []uint32
  • func (m M) MarshalYAML() (any, error)
  • func (m *M) SetEnforced(enforced []uint32) error
  • func (m M) String() string
  • func (m *M) UnmarshalJSON(b []byte) error
  • func (m *M) UnmarshalYAML(unmarshal func(any) error) error
• type Measurement
  • func PlaceHolderMeasurement(len int) Measurement
  • func WithAllBytes(b byte, validationOpt MeasurementValidationOption, len int) Measurement
  • func (m Measurement) MarshalJSON() ([]byte, error)
  • func (m Measurement) MarshalYAML() (any, error)
  • func (m *Measurement) UnmarshalJSON(b []byte) error
  • func (m *Measurement) UnmarshalYAML(unmarshal func(any) error) error
• type MeasurementValidationOption
• type RekorError
  • func (e *RekorError) Error() string
  • func (e *RekorError) Unwrap() error
• type VerifyFetcher
  • func NewVerifyFetcher(newCosignVerifier func([]byte) (sigstore.Verifier, error), rekor rekorVerifier, ...) *VerifyFetcher
  • func (m *VerifyFetcher) FetchAndVerifyMeasurements(ctx context.Context, image string, csp cloudprovider.Provider, ...) (M, error)

Constants

const (
	// PCRIndexClusterID is a PCR we extend to mark the node as initialized.
	// The value used to extend is a random generated 32 Byte value.
	PCRIndexClusterID = tpmutil.Handle(15)
	// PCRIndexOwnerID is a PCR we extend to mark the node as initialized.
	// The value used to extend is derived from Constellation's master key.
	// TODO(daniel-weisse): move to stable, non-debug PCR before use.
	PCRIndexOwnerID = tpmutil.Handle(16)

	// TDXIndexClusterID is the measurement used to mark the node as initialized.
	// The value is the index of the RTMR + 1, since index 0 of the TDX measurements is reserved for MRTD.
	TDXIndexClusterID = RTMRIndexClusterID + 1
	// RTMRIndexClusterID is the RTMR we extend to mark the node as initialized.
	RTMRIndexClusterID = 2

	// PCRMeasurementLength holds the length for valid PCR measurements (SHA256).
	PCRMeasurementLength = 32
	// TDXMeasurementLength holds the length for valid TDX measurements (SHA384).
	TDXMeasurementLength = 48
)

Types

type ImageMeasurementsV2

type ImageMeasurementsV2 struct {
	Version string                     `json:"version" yaml:"version"`
	Ref     string                     `json:"ref" yaml:"ref"`
	Stream  string                     `json:"stream" yaml:"stream"`
	List    []ImageMeasurementsV2Entry `json:"list" yaml:"list"`
}

ImageMeasurementsV2 is a struct to hold measurements for a specific image. .List contains measurements for all variants of the image.

func MergeImageMeasurementsV2

func MergeImageMeasurementsV2(measurements ...ImageMeasurementsV2) (ImageMeasurementsV2, error)

MergeImageMeasurementsV2 combines the image measurement entries from multiple sources into a single ImageMeasurementsV2 object.

type ImageMeasurementsV2Entry

type ImageMeasurementsV2Entry struct {
	CSP                cloudprovider.Provider `json:"csp" yaml:"csp"`
	AttestationVariant string                 `json:"attestationVariant" yaml:"attestationVariant"`
	Measurements       M                      `json:"measurements" yaml:"measurements"`
}

ImageMeasurementsV2Entry is a struct to hold measurements for one variant of a specific image.

type M

type M map[uint32]Measurement

M are Platform Configuration Register (PCR) values that make up the Measurements.

func ApplyOverrides

func ApplyOverrides(in M, csp cloudprovider.Provider, attestationVariant string) (M, error)

ApplyOverrides applies overrides to the given measurements.

func DefaultsFor

func DefaultsFor(provider cloudprovider.Provider, attestationVariant variant.Variant) M

DefaultsFor provides the default measurements for given cloud provider.

func (M) Compare

func (m M) Compare(other map[uint32][]byte) (warnings []string, errs []error)

Compare compares the expected measurements to the given list of measurements. It returns a list of warnings for non matching measurements for WarnOnly entries, and a list of errors for non matching measurements for Enforce entries.

func (*M) Copy

func (m *M) Copy() M

Copy creates a new map with the same values as the original.

func (*M) CopyFrom

func (m *M) CopyFrom(other M)

CopyFrom copies over all values from other. Overwriting existing values, but keeping not specified values untouched.

func (*M) EqualTo

func (m *M) EqualTo(other M) bool

EqualTo tests whether the provided other Measurements are equal to these measurements.

func (*M) FetchAndVerify

func (m *M) FetchAndVerify(
	ctx context.Context, client *http.Client, verifier cosignVerifier,
	measurementsURL, signatureURL *url.URL,
	version versionsapi.Version, csp cloudprovider.Provider, attestationVariant variant.Variant,
) (string, error)

FetchAndVerify fetches measurement and signature files via provided URLs, using client for download. The hash of the fetched measurements is returned.

func (*M) FetchNoVerify

func (m *M) FetchNoVerify(ctx context.Context, client *http.Client, measurementsURL *url.URL,
	version versionsapi.Version, csp cloudprovider.Provider, attestationVariant variant.Variant,
) error

FetchNoVerify fetches measurement via provided URLs, using client for download. Measurements are not verified.

func (*M) GetEnforced

func (m *M) GetEnforced() []uint32

GetEnforced returns a list of all enforced Measurements, i.e. all Measurements that are not marked as WarnOnly.

func (M) MarshalYAML

func (m M) MarshalYAML() (any, error)

MarshalYAML returns the YAML encoding of m.

func (*M) SetEnforced

func (m *M) SetEnforced(enforced []uint32) error

SetEnforced sets the WarnOnly flag to true for all Measurements that are NOT included in the provided list of enforced measurements.

func (M) String

func (m M) String() string

String returns a string representation of the measurements.

func (*M) UnmarshalJSON

func (m *M) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals measurements from json. This function enforces all measurements to be of equal length.

func (*M) UnmarshalYAML

func (m *M) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML unmarshals measurements from yaml. This function enforces all measurements to be of equal length.

type Measurement

type Measurement struct {
	// Expected measurement value.
	// 32 bytes for vTPM attestation, 48 for TDX.
	Expected []byte `json:"expected" yaml:"expected"`
	// ValidationOpt indicates how measurement mismatches should be handled.
	ValidationOpt MeasurementValidationOption `json:"warnOnly" yaml:"warnOnly"`
}

Measurement wraps expected PCR value and whether it is enforced.

func PlaceHolderMeasurement

func PlaceHolderMeasurement(len int) Measurement

PlaceHolderMeasurement returns a measurement with placeholder values for Expected.

func WithAllBytes

func WithAllBytes(b byte, validationOpt MeasurementValidationOption, len int) Measurement

WithAllBytes returns a measurement value where all bytes are set to b. Takes a dynamic length as input. Expected are either 32 bytes (PCRMeasurementLength) or 48 bytes (TDXMeasurementLength). Over inputs are possible in this function, but potentially rejected elsewhere.

func (Measurement) MarshalJSON

func (m Measurement) MarshalJSON() ([]byte, error)

MarshalJSON writes out a Measurement with Expected encoded as a hex string.

func (Measurement) MarshalYAML

func (m Measurement) MarshalYAML() (any, error)

MarshalYAML writes out a Measurement with Expected encoded as a hex string.

func (*Measurement) UnmarshalJSON

func (m *Measurement) UnmarshalJSON(b []byte) error

UnmarshalJSON reads a Measurement either as json object, or as a simple hex or base64 encoded string.

func (*Measurement) UnmarshalYAML

func (m *Measurement) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML reads a Measurement either as yaml object, or as a simple hex or base64 encoded string.

type MeasurementValidationOption

type MeasurementValidationOption bool

MeasurementValidationOption indicates how measurement mismatches should be handled.

const (
	// WarnOnly will only result in a warning in case of a mismatching measurement.
	WarnOnly MeasurementValidationOption = true
	// Enforce will result in an error in case of a mismatching measurement, and operation will be aborted.
	Enforce MeasurementValidationOption = false
)

type RekorError

type RekorError struct {
	// contains filtered or unexported fields
}

RekorError is returned when verifying measurements with Rekor fails.

func (*RekorError) Error

func (e *RekorError) Error() string

Error returns the error message.

func (*RekorError) Unwrap

func (e *RekorError) Unwrap() error

Unwrap returns the wrapped error.

type VerifyFetcher

type VerifyFetcher struct {
	// contains filtered or unexported fields
}

VerifyFetcher is a high-level fetcher that fetches measurements and verifies them.

func NewVerifyFetcher

func NewVerifyFetcher(newCosignVerifier func([]byte) (sigstore.Verifier, error), rekor rekorVerifier, client *http.Client) *VerifyFetcher

NewVerifyFetcher creates a new MeasurementFetcher.

func (*VerifyFetcher) FetchAndVerifyMeasurements

func (m *VerifyFetcher) FetchAndVerifyMeasurements(ctx context.Context,
	image string, csp cloudprovider.Provider, attestationVariant variant.Variant,
	noVerify bool,
) (M, error)

FetchAndVerifyMeasurements fetches and verifies measurements for the given version and attestation variant.