efivarfs

package
v1.12.1 Latest Latest
Warning

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

Go to latest
Published: Jan 5, 2026 License: MPL-2.0, Apache-2.0 Imports: 18 Imported by: 0

README

efivarfs

This package was copied from the upstream repository at efivarfs

There were minimal changes done to comply with the linter and gofmt rules.

The major change was to remove the EFI variable file immutable attribute before writing to it.

Documentation

Overview

Package efivarfs provides functions to read and manipulate UEFI runtime variables. It uses Linux's efivarfs [1] to access the variables and all functions generally require that this is mounted at "/sys/firmware/efi/efivars".

[1] https://www.kernel.org/doc/html/latest/filesystems/efivarfs.html

Index

Constants

View Source
const (
	// Path is the path to the efivarfs mount point.
	Path = "/sys/firmware/efi/efivars"
)

Variables

View Source
var (
	// ScopeGlobal is the scope of variables defined by the EFI specification
	// itself.
	ScopeGlobal = uuid.MustParse("8be4df61-93ca-11d2-aa0d-00e098032b8c")
	// ScopeSystemd is the scope of variables defined by Systemd/bootspec.
	ScopeSystemd = uuid.MustParse("4a67b082-0a4c-41cf-b6c7-440b29bb8c4f")
)

Encoding defines the Unicode encoding used by UEFI, which is UCS-2 Little Endian. For BMP characters UTF-16 is equivalent to UCS-2. See the UEFI Spec 2.9, Sections 33.2.6 and 1.8.1.

Functions

func AddBootEntry

func AddBootEntry(rw ReadWriter, be *LoadOption) (int, error)

AddBootEntry creates an new EFI boot entry variable and returns its non-negative index on success.

func DeleteBootEntry

func DeleteBootEntry(rw ReadWriter, idx int) error

DeleteBootEntry deletes the boot entry at the given index.

func ListBootEntries added in v1.11.2

func ListBootEntries(rw ReadWriter) (map[int]*LoadOption, error)

ListBootEntries lists all EFI boot entries present in the system by their index.

func ReadLoaderDevicePartUUID

func ReadLoaderDevicePartUUID(rw ReadWriter) (uuid.UUID, error)

ReadLoaderDevicePartUUID reads the ESP UUID from an EFI variable.

func SetBootEntry

func SetBootEntry(rw ReadWriter, idx int, be *LoadOption) error

SetBootEntry writes the given boot entry to the given index.

func SetBootNext

func SetBootNext(rw ReadWriter, entryIdx uint16) error

SetBootNext sets the boot entry used for the next boot only. It automatically resets after the next boot.

func SetBootOrder

func SetBootOrder(rw ReadWriter, ord BootOrder) error

SetBootOrder replaces contents of the boot order variable with the order specified in ord.

Types

type Attribute

type Attribute uint32

Attribute contains a bitset of EFI variable attributes.

const (
	// AttrNonVolatile is the attribute for non-volatile variables.
	// If set the value of the variable is is persistent across resets and
	// power cycles. Variables without this set cannot be created or modified
	// after UEFI boot services are terminated.
	AttrNonVolatile Attribute = 1 << iota
	// AttrBootserviceAccess is the attribute for variables that can be
	// accessed from UEFI boot services.
	AttrBootserviceAccess
	// AttrRuntimeAccess is the attribute for variables that can be accessed from
	// an operating system after UEFI boot services are terminated. Variables
	// setting this must also set AttrBootserviceAccess. This is automatically
	// taken care of by Write in this package.
	AttrRuntimeAccess
	// AttrHardwareErrorRecord is the attribute for variables that are used to
	// mark a variable as being a hardware error record. See UEFI 2.10 section
	// 8.2.8 for more information about this.
	AttrHardwareErrorRecord
	// AttrAuthenticatedWriteAccess is the attribute for variables that require
	// authenticated access to write.
	//
	// Deprecated: should not be used for new variables.
	AttrAuthenticatedWriteAccess
	// AttrTimeBasedAuthenticatedWriteAccess is the attribute for variables
	// that require special authentication to write. These variables
	// cannot be written with this package.
	AttrTimeBasedAuthenticatedWriteAccess
	// AttrAppendWrite is the attribute for variables that can be appended to.
	// If set in a Write() call, tries to append the data instead of replacing
	// it completely.
	AttrAppendWrite
	// AttrEnhancedAuthenticatedAccess is the attribute for variables that
	// require special authentication to access and write. These variables
	// cannot be accessed with this package.
	AttrEnhancedAuthenticatedAccess
)

type BootOrder

type BootOrder []uint16

BootOrder represents the contents of the BootOrder EFI variable.

func GetBootOrder

func GetBootOrder(rw ReadWriter) (BootOrder, error)

GetBootOrder returns the current boot order of the system.

func UniqueBootOrder added in v1.11.2

func UniqueBootOrder(bootOrder BootOrder) BootOrder

UniqueBootOrder returns a copy of the given BootOrder with duplicate entries removed, preserving the order of first appearance.

func UnmarshalBootOrder

func UnmarshalBootOrder(d []byte) (BootOrder, error)

UnmarshalBootOrder loads a BootOrder from its binary representation.

func (*BootOrder) Marshal

func (t *BootOrder) Marshal() []byte

Marshal generates the binary representation of a BootOrder.

type DevicePath

type DevicePath []DevicePathElem

DevicePath represents a path consisting of one or more elements to an entity implementing an EFI protocol. It's very broadly used inside EFI for representing all sorts of abstract paths. In the context of this package it is used to represent paths to EFI loaders. See https://uefi.org/specs/UEFI/2.10/10_Protocols_Device_Path_Protocol.html for more information.

func UnmarshalDevicePath

func UnmarshalDevicePath(data []byte) (DevicePath, []byte, error)

UnmarshalDevicePath parses a binary device path until it encounters an end device path structure. It returns that device path (excluding the final end device path marker) as well as all all data following the end marker.

func (DevicePath) Marshal

func (d DevicePath) Marshal() ([]byte, error)

Marshal encodes the device path in binary form.

type DevicePathElem

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

DevicePathElem is a common interface for all UEFI device path elements.

type FilePath

type FilePath string

FilePath contains a backslash-separated path or part of a path to a file on a filesystem.

type FilesystemReaderWriter added in v1.11.2

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

FilesystemReaderWriter implements ReaderWriter using the efivars Linux filesystem.

func NewFilesystemReaderWriter added in v1.11.2

func NewFilesystemReaderWriter(write bool) (*FilesystemReaderWriter, error)

NewFilesystemReaderWriter creates a new FilesystemReaderWriter.

func (*FilesystemReaderWriter) Close added in v1.11.2

func (rw *FilesystemReaderWriter) Close() error

Close unmounts efivarfs if the FilesystemReaderWriter was created with write access.

func (*FilesystemReaderWriter) Delete added in v1.11.2

func (rw *FilesystemReaderWriter) Delete(scope uuid.UUID, varName string) error

Delete deletes the given variable name in the given scope. Use with care, some firmware fails to boot if variables it uses are deleted.

func (*FilesystemReaderWriter) List added in v1.11.2

func (rw *FilesystemReaderWriter) List(scope uuid.UUID) ([]string, error)

List lists all variable names present for a given scope sorted by their names in Go's "native" string sort order.

func (*FilesystemReaderWriter) Read added in v1.11.2

func (rw *FilesystemReaderWriter) Read(scope uuid.UUID, varName string) ([]byte, Attribute, error)

Read reads the value of the named variable in the given scope.

func (*FilesystemReaderWriter) Write added in v1.11.2

func (rw *FilesystemReaderWriter) Write(scope uuid.UUID, varName string, attrs Attribute, value []byte) error

Write writes the value of the named variable in the given scope.

type HardDrivePath

type HardDrivePath struct {
	// Partition number, starting at 1. If zero or unset, the whole drive is
	// selected.
	PartitionNumber uint32
	// Block address at which the partition starts. Not used for matching
	// partitions in EDK2.
	PartitionStartBlock uint64
	// Number of blocks occupied by the partition starting from the
	// PartitionStartBlock. Not used for matching partitions in EDK2.
	PartitionSizeBlocks uint64
	// PartitionMatch is used to match drive or partition signatures.
	// Use PartitionMBR and PartitionGPT types here.
	PartitionMatch PartitionMatch
}

HardDrivePath matches whole drives or partitions on GPT/MBR formatted drives.

type LoadOption

type LoadOption struct {
	// Human-readable description of what this load option loads.
	// This is what's being shown by the firmware when selecting a boot option.
	Description string
	// If set, firmware will skip this load option when it is in BootOrder.
	// It is unspecificed whether this prevents the user from booting the entry
	// manually.
	Inactive bool
	// If set, this load option will not be shown in any menu for load option
	// selection. This does not affect other functionality.
	Hidden bool
	// Category contains the category of the load entry. The selected category
	// affects various firmware behaviors, see the individual value
	// descriptions for more information.
	Category LoadOptionCategory
	// Path to the UEFI PE executable to execute when this load option is being
	// loaded.
	FilePath DevicePath
	// ExtraPaths contains additional device paths with vendor-specific
	// behavior. Can generally be left empty.
	ExtraPaths []DevicePath
	// OptionalData gets passed as an argument to the executed PE executable.
	// If zero-length a NULL value is passed to the executable.
	OptionalData []byte
}

LoadOption contains information on a payload to be loaded by EFI.

func GetBootEntry

func GetBootEntry(rw ReadWriter, idx int) (*LoadOption, error)

GetBootEntry returns the boot entry at the given index.

func UnmarshalLoadOption

func UnmarshalLoadOption(data []byte) (*LoadOption, error)

UnmarshalLoadOption decodes a binary EFI_LOAD_OPTION into a LoadOption.

func (*LoadOption) Marshal

func (e *LoadOption) Marshal() ([]byte, error)

Marshal encodes a LoadOption into a binary EFI_LOAD_OPTION.

type LoadOptionCategory

type LoadOptionCategory uint8

LoadOptionCategory defines the category of a load option. This is used to differentiate between different types of boot options.

const (
	// LoadOptionCategoryBoot is the default category for boot entries.
	LoadOptionCategoryBoot LoadOptionCategory = 0x0
	// LoadOptionCategoryApp is the category for boot entries that are
	// not booted as part of the normal boot order, but are only launched via menu or hotkey.
	// This category is optional for bootloaders to support, before creating
	// new boot entries of this category firmware support needs to be
	// confirmed.
	LoadOptionCategoryApp LoadOptionCategory = 0x1
)

type Mock added in v1.11.2

type Mock struct {
	Variables map[uuid.UUID]map[string]MockVariable
}

Mock is a mock implementation of ReaderWriter interface for testing purposes.

func (*Mock) Delete added in v1.11.2

func (mock *Mock) Delete(scope uuid.UUID, varName string) error

Delete deletes a variable from the given scope.

func (*Mock) List added in v1.11.2

func (mock *Mock) List(scope uuid.UUID) ([]string, error)

List lists all variable names in the given scope.

func (*Mock) Read added in v1.11.2

func (mock *Mock) Read(scope uuid.UUID, varName string) ([]byte, Attribute, error)

Read reads a variable from the given scope.

func (*Mock) Write added in v1.11.2

func (mock *Mock) Write(scope uuid.UUID, varName string, attrs Attribute, value []byte) error

Write writes a variable to the given scope.

type MockVariable added in v1.11.2

type MockVariable struct {
	Attrs Attribute
	Data  []byte
}

MockVariable represents a mock EFI variable with its attributes and data.

type PartitionGPT

type PartitionGPT struct {
	// UUID of the partition to be matched. Conversion into mixed-endian format
	// is taken care of, a standard big-endian UUID can be put in here.
	PartitionUUID uuid.UUID
}

PartitionGPT matches a partition on a drive formatted with GPT.

type PartitionMBR

type PartitionMBR struct {
	// DiskSignature contains a 4-byte signature identifying the drive, located
	// just after the 440 bytes of boot sector loading code.
	// Note that since MBR does not have per-partition signatures, this is
	// combined with PartitionNumber to select a partition.
	DiskSignature [4]byte
}

PartitionMBR matches a drive or partition formatted with legacy MBR (Master Boot Record).

type PartitionMatch

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

PartitionMatch is an interface that defines methods for matching partitions on drives or filepaths.

type PartitionUnknown

type PartitionUnknown struct {
	PartitionSignature [16]byte
	PartitionFormat    uint8
	SignatureType      uint8
}

PartitionUnknown is being used to represent unknown partitioning schemas or combinations of PartitionFormat/SignatureType. It contains raw uninterpreted data.

type ReadWriter added in v1.11.2

type ReadWriter interface {
	Write(scope uuid.UUID, varName string, attrs Attribute, value []byte) error
	Delete(scope uuid.UUID, varName string) error
	Read(scope uuid.UUID, varName string) ([]byte, Attribute, error)
	List(scope uuid.UUID) ([]string, error)
}

ReadWriter is an interface for reading and writing EFI variables.

type UnknownPath

type UnknownPath struct {
	TypeVal    uint8
	SubTypeVal uint8
	DataVal    []byte
}

UnknownPath is a generic structure for all types of path elements not understood by this library. The UEFI-specified set of path element types is vast and mostly unused, this generic type allows for parsing as well as pass-through of not-understood path elements.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL