efi

package
v0.0.0-...-33c8514 Latest Latest
Warning

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

 Go to latest Published: Jul 23, 2026 License: GPL-3.0 Imports: 29 Imported by: 9

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// PK is the identity of the Platform Key variable.
	PK = efi.VariableDescriptor{Name: "PK", GUID: efi.GlobalVariable}

	// KEK is the identity of the Key Exchange Key database.
	KEK = efi.VariableDescriptor{Name: "KEK", GUID: efi.GlobalVariable}

	// Db is the identity of the authorized signature database.
	Db = efi.VariableDescriptor{Name: "db", GUID: efi.ImageSecurityDatabaseGuid}

	// Dbx is the identity of the forbidden signature database.
	Dbx = efi.VariableDescriptor{Name: "dbx", GUID: efi.ImageSecurityDatabaseGuid}
)

Functions

func AddPCRProfile 

func AddPCRProfile(pcrAlg tpm2.HashAlgorithmId, branch *secboot_tpm2.PCRProtectionProfileBranch, loadSequences *ImageLoadSequences, options ...PCRProfileOption) error

AddPCRProfile adds a profile defined by the supplied options to the supplied secboot_tpm2.PCRProtectionProfileBranch, using the specified digest algorithm for the PCR digest. The generated profile is defined by the supplied load sequences and options.

func AddSystemdStubProfile deprecated 

func AddSystemdStubProfile(branch *secboot_tpm2.PCRProtectionProfileBranch, 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.

Deprecated: use AddPCRProfile with the WithKernelConfigProfile option.

Types

type FileImage 

type FileImage string

FileImage provides an image from a file that is loaded during the boot process before ExitBootServices.

func NewFileImage 

func NewFileImage(path string) FileImage

NewFileImage creates a new FileImage for the file at the specified path.

func (FileImage) Open 

func (p FileImage) Open() (ImageReader, error)

Open implements [ImageSource.Open].

func (FileImage) String 

func (p FileImage) String() string

String implements fmt.Stringer.

type HostEnvironment 

type HostEnvironment = internal_efi.HostEnvironmentEFI

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() (ImageReader, error) // Open a handle to the image for reading
}

Image provides an image that is loaded during the boot process before ExitBootServices.

type ImageLoadActivity 

type ImageLoadActivity interface {
	// Loads lets one specify a set of images that are permitted to be executed by the
	// image associated with this activity. The supplied images will inherit the
	// parameters associated with this image unless they are overridden explicitly.
	Loads(images ...ImageLoadActivity) ImageLoadActivity
	// contains filtered or unexported methods
}

ImageLoadActivity corresponds to the execution of an image during the boot process, before ExitBootServices. It is associated with an Image and an optional number of ImageLoadParams.

func NewImageLoadActivity 

func NewImageLoadActivity(image Image, params ...ImageLoadParams) ImageLoadActivity

NewImageLoadActivity returns a new ImageLoadActivity for the specified image that will be executed during the boot process, before ExitBootServices. The caller can specify optional parameters that will apply to the specified image and which will be inherited by subsequent images (added by ImageLoadActivity.Loads). The supplied parameters will override any existing ones that would be inherited by this image. Parameters that provide multiple values will automatically create branches in the profile. If a parameter type is supplied more than once, only the last supplied one will be used.

type ImageLoadParams 

type ImageLoadParams interface {
	// contains filtered or unexported methods
}

ImageLoadParams provides one or more values for an external parameter that is supplied to an image which is loaded during the boot process.

func KernelCommandlineParams 

func KernelCommandlineParams(commandlines ...string) ImageLoadParams

KernelCommandlineParams returns a ImageLoadParams for the specified kernel commandlines.

func SnapModelParams 

func SnapModelParams(models ...secboot.SnapModel) ImageLoadParams

SnapModelParams returns a ImageLoadParams for the specifed snap models.

type ImageLoadSequences 

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

ImageLoadSequences corresponds to all of the boot paths for images executed before ExitBootServices.

func NewImageLoadSequences 

func NewImageLoadSequences(params ...ImageLoadParams) *ImageLoadSequences

NewImageLoadSequences returns a new ImageLoadSequences object with the specified parameters, which will be inherited by all of the appended paths.

func (*ImageLoadSequences) Append 

func (a *ImageLoadSequences) Append(images ...ImageLoadActivity) *ImageLoadSequences

Append appends the specified image load activities.

type ImageReader 

type ImageReader interface {
	io.ReaderAt
	io.Closer
	Size() int64
}

ImageReader corresponds to an open handle from which to read a binary image from.

type PCRProfileEnablePCRsOption 

type PCRProfileEnablePCRsOption interface {
	PCRProfileOption
	PCRs() (tpm2.HandleList, error)
}

PCRProfileEnablePCRsOption is an option for AddPCRProfile that adds one or more PCRs.

func WithBootManagerCodeProfile 

func WithBootManagerCodeProfile() PCRProfileEnablePCRsOption

WithBootManagerCodeProfile requests that the UEFI boot manager code and boot attempts profile is added, which restricts access to a resource to a specific set of UEFI applications that are measured to PCR4. Events that are measured to this PCR are detailed in section 2.3.4.5 of the "TCG PC Client Platform Firmware Profile Specification".

There is some variation in behaviour between different platform firmware implementations, and this will generate a policy that is specific for the current host's platform firmware, based on the contents of the TCG event log. This assumes that any events associated with the first boot attempt (other than the EV_EFI_BOOT_SERVICES_APPLICATION containing the image digest) are measured before the EV_SEPARATOR event. There are some inconsistencies in the TCG PC Client PFP spec v1.05r23 here - section 3.3.4.5 mentions a EV_ACTION "Ready to Boot" signal and that the separator must be recorded prior to this event. It also implies EV_EFI_ACTION events associated with each boot attempt occur after the separator. Section 8.2.4 contradicts this - it makes no mention of any EV_ACTION events and says that the EV_EFI_ACTION "Calling EFI Application from Boot Option" event associated with the first boot attempt must be before the separator. In practise, devices we've enabled follow section 8.2.4 when they measure the first EV_EFI_ACTION event (which is optional - firmware should measure a EV_OMIT_BOOT_DEVICE_EVENTS event if they are not measured, although some implementations don't do this either).

Note that on supported platforms, the policy generated by this will include any system preparation applications that were executed during the current boot, as long as they are measured as part of the pre-OS environment (before the EV_SEPARATOR event). Note that the inclusion of these makes a policy inherently fragile because it is not possible to pre-generate policy to accomodate updates of these components.

If the EV_OMIT_BOOT_DEVICE_EVENTS is not recorded to PCR 4, the platform firmware may perform meaurements of all boot attempts, even if they fail. The generated policy will be invalid if the platform firmware performs boot attempts that subsequently fail before performing a successful attempt, even if the images associated with the successful attempt are included in this policy.

func WithDriversAndAppsProfile 

func WithDriversAndAppsProfile() PCRProfileEnablePCRsOption

WithDriversAndAppsProfile adds the UEFI Drivers and UEFI Applications profile (measured to PCR2). This is copied directly from the current host environment configuration.

func WithKernelConfigProfile 

func WithKernelConfigProfile() PCRProfileEnablePCRsOption

WithKernelConfigProfile adds the kernel config profile. This binds a policy to a set of externally supplied commandlines. On Ubuntu Core, this also binds a policy to a set of model assertions and the initrd phase of the boot.

Kernel commandlines can be injected into the profile with KernelCommandlineParams. Snap models can be injected into the profile with SnapModelParams. Note that a model assertion is mandatory for profiles that include a UKI for Ubuntu Core.

func WithPlatformFirmwareProfile 

func WithPlatformFirmwareProfile() PCRProfileEnablePCRsOption

WithPlatformFirmwareProfile adds the SRTM, POST BIOS and Embedded Drivers profile (measured to PCR0). This is copied directly from the current host environment configuration.

It is suitable in environments where platform firmware is measured by a hardware root of trust as opposed to being verified as authentic and prevented from running otherwise.

func WithSecureBootPolicyProfile 

func WithSecureBootPolicyProfile() PCRProfileEnablePCRsOption

WithSecureBootPolicyProfile requests that the UEFI secure boot policy profile is added, which restricts access to a resource based on a set of secure boot policies measured to PCR7. The secure boot policy that is measured to PCR7 is defined in section 2.3.4.8 of the "TCG PC Client Platform Firmware Profile Specification".

This will only generate a policy that works for devices with secure boot enabled, deployed mode enabled (for UEFI >= 2.5), without a debugger enabled and which measure the secure boot configuration events in the correct order (SecureBoot -> PK -> KEK -> db -> dbx).

The secure boot policy includes events that correspond to the authentication of EFI applications. All images supplied to AddPCRProfile must have one ore more Authenticode signatures that have a trust anchor in the host environment's signature database, else an error will be returned. If any image has a non Authenticode signature or an Authenticode signature with a digest algorithm other than SHA-256, then an error will be returned.

This does not support generating policy for images that are authenticated by adding their digests to the signature database. If a supplied image has a valid Authenticode signature with a trust anchor in the signature database but it is subsequently authenticated by its image digest, the generated policy will be incorrect.

If an image has an Authenticode signature with more than one trust anchor in the signature database, this assumes that the platform firmware will try them in the order in which they appear and authenticate the image with the first one.

If an image has multiple Authenticode signatures, this assumes that the platform firmware will test each Authenticode signature in the order they appear in the image against the signature database, as opposed to testing each entry in the signature database against each Authenticode signature, ie: 

for each signature in image {
  for each certificate sigdb {
    <test>
  }
}

If the platform firmware doesn't behave like this, then this may generate a policy that is incorrect in some specific circumstances - ie, if an image contains 2 Authenticode signatures with their own trust anchors in the signature database, but the signatures are in reverse order with respect to how their trust anchors are enrolled.

Note that AddPCRProfile does not consider the host's revocation policy.

The secure boot policy includes information about the secure boot configuration, including signature databases. In order to support atomic updates to these databases, it is possible to pre-generate a policy that includes these updates by supplying details of the updates to AddPCRProfile using WithSignatureDBUpdates.

Note that the policy generated by this will include authentication events associated with UEFI drivers and system preparation applications that were included in the current boot, as long as they are measured as part of the pre-OS environment (before the EV_SEPARATOR events are measured to PCRs 0-6). Note that the inclusion of these makes a policy inherently fragile because it is not possible to pre-generate policy to accomodate updates of these components.

type PCRProfileOption 

type PCRProfileOption interface {
	ApplyOptionTo(visitor internal_efi.PCRProfileOptionVisitor) error
}

PCRProfileOption is an option for AddPCRProfile

func WithAllowInsufficientDmaProtection 

func WithAllowInsufficientDmaProtection() PCRProfileOption

WithAllowInsufficientDMAProtection can be supplied to AddPCRProfile to allow for PCR7 including the "DMA Protection Disabled" event. While this reduces security, it is required on some devices. If this string is present in the event log, this option results in a creation of a branched PCR profile that has two branches at the Firmware load stage one including the event with the string, the another not.

func WithAllowSecureBootUserMode 

func WithAllowSecureBootUserMode() PCRProfileOption

WithAllowSecureBootUserMode can be supplied to AddPCRProfile to allow for secure boot PCR profiles that support user mode to be generated on systems where user mode is currently enabled. This is opt-in to ensure that a system that was originally in deployed mode doesn't automatically regenerate a PCR profile for user mode in the case where the firmware settings are inadvertently degraded.

If the system is in user mode, PCR profile branches will be generated both for user mode and deployed mode to allow a system to be placed back into deployed mode without making the generated policy invalid. If the system is in deployed mode, this option has no effect.

func WithHostEnvironment 

func WithHostEnvironment(env HostEnvironment) PCRProfileOption

WithHostEnvironment overrides the EFI host environment for a PCR profile with the supplied environment. This is useful when generating a profile for a device other than the current host.

func WithShimSbatPolicyLatest 

func WithShimSbatPolicyLatest() PCRProfileOption

WithShimSbatPolicyLatest can be supplied to AddPCRProfile to compute the profile with the value of the SbatLevel EFI variable set to "latest" (uint(1)), in addition to the current value of the variable.

func WithSignatureDBUpdates 

func WithSignatureDBUpdates(updates ...*SignatureDBUpdate) PCRProfileOption

WithSignatureDBUpdates can be supplied to AddPCRProfile to compute the profile for each of the supplied signature database updates in turn, in addition to the current signature database contents. This should only be supplied once. If a profile needs to be computed for more than one signature database update, provide them all in a single option.

type SignatureDBUpdate 

type SignatureDBUpdate struct {
	Name efi.VariableDescriptor // The identity of the signature database
	Data []byte                 // The update payload
}

SignatureDBUpdate corresponds to an update to a signature database, such as dbx.

type SnapFileImage 

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

SnapFileImage provides an image contained within a snap package that is loaded during the boot process before ExitBootServices.

func NewSnapFileImage 

func NewSnapFileImage(container snap.Container, filename string) *SnapFileImage

NewSnapFileImage creates a new SnapFileImage for the file at the specified relative path within the supplied snap.

func (SnapFileImage) Open 

func (f SnapFileImage) Open() (ImageReader, error)

Open implements [ImageSource.Open].

func (SnapFileImage) String 

func (f SnapFileImage) String() string

String implements fmt.Stringer.

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

Directories

Path Synopsis

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.