efi

package
v0.0.17 Latest Latest
Warning

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

 Go to latest Published: Nov 12, 2022 License: GPL-3.0 Imports: 22 Imported by: 1

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddBootManagerProfile 

func AddBootManagerProfile(profile *secboot_tpm2.PCRProtectionProfile, params *BootManagerProfileParams) error

AddBootManagerProfile adds the UEFI boot manager code and boot attempts profile to the provided PCR protection profile, in order to generate a PCR policy that restricts access to a sealed key to a specific set of binaries started from the UEFI boot manager and which are measured to PCR 4. Events that are measured to this PCR are detailed in section 2.3.4.5 of the "TCG PC Client Platform Firmware Profile Specification".

If the firmware supports executing system preparation applications before the transition to "OS present", events corresponding to the launch of these applications will be measured to PCR 4. If the event log indicates that any system preparation applications were executed during the current boot, this function will automatically include these binaries in the generated PCR profile. Note that it is not possible to pre-compute PCR values for system preparation applications using this function, and so it is not possible to update these in a way that is atomic (if any of them are changed, a new PCR profile can only be generated after performing a reboot).

The sequences of binaries for which to generate a PCR profile for is supplied via the LoadSequences field of params. Note that this function does not use the Source field of EFIImageLoadEvent. Each bootloader stage in each load sequence must perform a measurement of any subsequent stage to PCR 4 in the same format as the events measured by the UEFI boot manager.

Section 2.3.4.5 of the "TCG PC Client Platform Firmware Profile Specification" specifies that EFI applications that load additional pre-OS environment code must measure this to PCR 4 using the EV_COMPACT_HASH event type. This function does not support EFI applications that load additional pre-OS environment code that isn't otherwise authenticated via the secure boot mechanism, and will generate PCR profiles that aren't correct for applications that do this.

If the EV_OMIT_BOOT_DEVICE_EVENTS is not recorded to PCR 4, the platform firmware will perform meaurements of all boot attempts, even if they fail. The generated PCR policy will not be satisfied if the platform firmware performs boot attempts that fail, even if the successful boot attempt is of a sequence of binaries included in this PCR profile.

func AddSecureBootPolicyProfile 

func AddSecureBootPolicyProfile(profile *secboot_tpm2.PCRProtectionProfile, params *SecureBootPolicyProfileParams) error

AddSecureBootPolicyProfile adds the UEFI secure boot policy profile to the provided PCR protection profile, in order to generate a PCR policy that restricts access to a sealed key to a set of UEFI secure boot policies measured to PCR 7. The secure boot policy information that is measured to PCR 7 is defined in section 2.3.4.8 of the "TCG PC Client Platform Firmware Profile Specification".

This function can only be called if the current boot was performed with secure boot enabled. An error will be returned if the current boot was performed with secure boot disabled. It can only generate a PCR profile that will work when secure boot is enabled.

The secure boot policy measurements include events that correspond to the authentication of loaded EFI images, and those events record the certificate of the authorities used to authenticate these images. The params argument allows the generated PCR policy to be restricted to a specific set of chains of trust by specifying EFI image load sequences via the LoadSequences field. This function will compute the measurements associated with the authentication of these load sequences. Each of the Image instances reachable from the LoadSequences field of params must correspond to an EFI image with one or more Authenticode signatures. These signatures are used to determine the CA certificate that will be used to authenticate them in order to compute authentication meausurement events. The digest algorithm of the Authenticode signatures must be SHA256. If there are no signatures, or the binary's certificate table contains non-Authenticode entries, or contains any Authenticode signatures with a digest algorithm other than SHA256, then an error will be returned. Note that this function assumes that any signatures are correct and does not ensure that they are so - it only determines if there is a chain of trust beween the signing certificate and a CA certificate in order to determine which certificate will be used for authentication, and what the source of that certificate is (for UEFI images that are loaded by shim).

If none of the sequences in the LoadSequences field of params can be authenticated by the current authorized signature database contents, then an error will be returned.

This function does not support computing measurements for images that are authenticated by an image digest rather than an Authenticode signature. If an image has a signature where the signer has a chain of trust to a CA certificate in the authorized signature database (or shim's vendor certificate) but that image is authenticated because an image digest is present in the authorized signature database instead, then this function will generate a PCR profile that is incorrect.

If an image has a signature that can be authenticated by multiple CA certificates in the authorized signature database, this function assumes that the firmware will try the CA certificates in the order in which they appear in the database and authenticate the image with the first valid certificate. If the firmware does not do this, then this function may generate a PCR profile that is incorrect for binaries that have a signature that can be authenticated by more than one CA certificate. Note that the structure of the signature database means that it can only really be iterated in one direction anyway.

For images with multiple Authenticode signatures, this function assumes that the device's firmware will iterate over the signatures in the order in which they appear in the binary's certificate table in an outer loop during image authentication (ie, for each signature, attempt to authenticate the binary using one of the CA certificates). If a device's firmware iterates over the authorized signature database in an outer loop instead (ie, for each CA certificate, attempt to authenticate the binary using one of its signatures), then this function may generate a PCR profile that is incorrect for binaries that have multiple signatures where both signers have a chain of trust to a different CA certificate but the signatures appear in a different order to which their CA certificates are enrolled.

This function does not consider the contents of the forbidden signature database. This is most relevant for images with multiple signatures. If an image has more than one signature where the signing certificates have chains of trust to different CA certificates, but the first signature is not used to authenticate the image because one of the certificates in its chain is blacklisted, then this function will generate a PCR profile that is incorrect.

In determining whether a signing certificate has a chain of trust to a CA certificate, this function expects there to be a direct relationship between the CA certificate and signing certificate. It does not currently detect that there is a chain of trust if intermediate certificates form part of the chain. This is most relevant for images with multiple signatures. If an image has more than one signature where the signing certificate have chains of trust to different CA certificate, but the first signature's chain involves intermediate certificates, then this function will generate a PCR profile that is incorrect.

This function does not support computing measurements for images that are authenticated by shim using a machine owner key (MOK).

The secure boot policy measurements include the secure boot configuration, which includes the contents of the UEFI signature databases. In order to support atomic updates of these databases with the sbkeysync tool, it is possible to generate a PCR policy computed from pending signature database updates. This can be done by supplying the keystore directories passed to sbkeysync via the SignatureDbUpdateKeystores field of the params argument. This function assumes that sbkeysync is executed with the "--no-default-keystores" option. When there are pending updates in the specified directories, this function will generate a PCR policy that is compatible with the current database contents and the database contents computed for each individual update. Note that sbkeysync ignores errors when applying updates - if any of the pending updates don't apply for some reason, the generated PCR profile will be invalid.

For the most common case where there are no signature database updates pending in the specified keystore directories and each image load event sequence corresponds to loads of images that are all verified with the same chain of trust, this is a complicated way of adding a single PCR digest to the provided secboot.PCRProtectionProfile.

func AddSystemdStubProfile 

func AddSystemdStubProfile(profile *secboot_tpm2.PCRProtectionProfile, params *SystemdStubProfileParams) error

AddSystemdStubProfile adds the systemd EFI linux loader stub profile to the PCR protection profile, in order to generate a PCR policy that restricts access to a key to a defined set of kernel commandlines when booting a linux kernel using the systemd EFI stub.

The PCR index that the EFI stub measures the kernel commandline too can be specified via the PCRIndex field of params.

The set of kernel commandlines to add to the PCRProtectionProfile is specified via the KernelCmdlines field of params.

Types

type BootManagerProfileParams 

type BootManagerProfileParams struct {
	// PCRAlgorithm is the algorithm for which to compute PCR digests for. TPMs compliant with the "TCG PC Client Platform TPM Profile
	// (PTP) Specification" Level 00, Revision 01.03 v22, May 22 2017 are required to support tpm2.HashAlgorithmSHA1 and
	// tpm2.HashAlgorithmSHA256. Support for other digest algorithms is optional.
	PCRAlgorithm tpm2.HashAlgorithmId

	// LoadSequences is a list of EFI image load sequences for which to compute PCR digests for.
	LoadSequences []*ImageLoadEvent

	// Environment is an optional parameter that allows the caller to provide
	// a custom EFI environment. If not set, the host's normal environment will
	// be used
	Environment HostEnvironment
}

BootManagerProfileParams provide the arguments to AddBootManagerProfile.

type FileImage 

type FileImage string

FileImage corresponds to a file on disk that is loaded, verified and executed before ExitBootServices.

func (FileImage) Open 

func (p FileImage) Open() (interface {
	io.ReaderAt
	io.Closer
	Size() int64
}, error)

func (FileImage) String 

func (p FileImage) String() string

type HostEnvironment 

type HostEnvironment interface {
	ReadVar(name string, guid efi.GUID) ([]byte, efi.VariableAttributes, error)

	ReadEventLog() (*tcglog.Log, error)
}

HostEnvironment is an interface that abstracts out an EFI environment, so that consumers of the API can provide a custom mechanism to read EFI variables or parse the TCG event log.

type Image 

type Image interface {
	fmt.Stringer
	Open() (interface {
		io.ReaderAt
		io.Closer
		Size() int64
	}, error) // Open a handle to the image for reading
}

Image corresponds to a binary that is loaded, verified and executed before ExitBootServices.

type ImageLoadEvent 

type ImageLoadEvent struct {
	Source ImageLoadEventSource // The source of the event
	Image  Image                // The image
	Next   []*ImageLoadEvent    // A list of possible subsequent ImageLoadEvents
}

ImageLoadEvent corresponds to the execution of a verified Image.

type ImageLoadEventSource 

type ImageLoadEventSource int

ImageLoadEventSource corresponds to the source of a ImageLoadEvent. 

const (
	// Firmware indicates that the source of a ImageLoadEvent was platform firmware, via the EFI_BOOT_SERVICES.LoadImage()
	// and EFI_BOOT_SERVICES.StartImage() functions, with the subsequently executed image being verified against the signatures
	// in the EFI authorized signature database.
	Firmware ImageLoadEventSource = iota

	// Shim indicates that the source of a ImageLoadEvent was shim, without relying on EFI boot services for loading, verifying
	// and executing the subsequently executed image. The image is verified by shim against the signatures in the EFI authorized
	// signature database, the MOK database or shim's built-in vendor certificate before being executed directly.
	Shim
)

type SecureBootPolicyProfileParams 

type SecureBootPolicyProfileParams struct {
	// PCRAlgorithm is the algorithm for which to compute PCR digests for. TPMs compliant with the "TCG PC Client Platform TPM Profile
	// (PTP) Specification" Level 00, Revision 01.03 v22, May 22 2017 are required to support tpm2.HashAlgorithmSHA1 and
	// tpm2.HashAlgorithmSHA256. Support for other digest algorithms is optional.
	PCRAlgorithm tpm2.HashAlgorithmId

	// LoadSequences is a list of EFI image load sequences for which to compute PCR digests for.
	LoadSequences []*ImageLoadEvent

	// SignatureDbUpdateKeystores is a list of directories containing EFI signature database updates for which to compute PCR digests
	// for. These directories are passed to sbkeysync using the --keystore option.
	SignatureDbUpdateKeystores []string

	// Environment is an optional parameter that allows the caller to provide
	// a custom EFI environment. If not set, the host's normal environment will
	// be used
	Environment HostEnvironment
}

SecureBootPolicyProfileParams provide the arguments to AddSecureBootPolicyProfile.

type SnapFileImage 

type SnapFileImage struct {
	Container snap.Container
	FileName  string // The filename within the snap squashfs
}

SnapFileImage corresponds to a binary contained within a snap file that is loaded, verified and executed before ExitBootServices.

func (SnapFileImage) Open 

func (f SnapFileImage) Open() (interface {
	io.ReaderAt
	io.Closer
	Size() int64
}, error)

func (SnapFileImage) String 

func (f SnapFileImage) String() string

type SystemdStubProfileParams 

type SystemdStubProfileParams struct {
	// PCRAlgorithm is the algorithm for which to compute PCR digests for. TPMs compliant with the "TCG PC Client Platform TPM Profile
	// (PTP) Specification" Level 00, Revision 01.03 v22, May 22 2017 are required to support tpm2.HashAlgorithmSHA1 and
	// tpm2.HashAlgorithmSHA256. Support for other digest algorithms is optional.
	PCRAlgorithm tpm2.HashAlgorithmId

	// PCRIndex is the PCR that the systemd EFI stub measures the kernel commandline to.
	PCRIndex int

	// KernelCmdlines is the set of kernel commandlines to add to the PCR profile.
	KernelCmdlines []string
}

SystemdStubProfileParams provides the parameters to AddSystemdStubProfile.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.