Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

uki: some additions, in particular specify the PE addon concept properly #107

Merged
merged 3 commits into from
Jul 5, 2024
Merged

uki: some additions, in particular specify the PE addon concept properly #107

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a75dadb
uki: document the PE subsystem to use for UKIs
poettering Jul 5, 2024
0f7a19e
uki: add section about PE addons
poettering Jul 5, 2024
6a064fd
uki: make clear that sections at bottom mostly are concerned with loc…
poettering Jul 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 54 additions & 14 deletions specs/unified_kernel_image.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,17 +26,20 @@ This specification defines the format and components (mandatory and optional) of
[systemd-stub](https://www.freedesktop.org/software/systemd/man/systemd-stub.html)
provides the reference implementation of the stub.

## File Format
The file format is PE/COFF (Portable Executable / Common Object File Format).
This is a well-known industry-standard file format, used for example in UEFI environments,
and UKIs follow the standard, so exact details will not be repeated here.
## UKI File Format
The file format for UKIs is PE/COFF (Portable Executable / Common Object File Format). This is a well-known
industry-standard file format, used for example in UEFI environments, and UKIs follow the standard, so exact
details will not be repeated here.

UKIs are a PE/COFF file with various resources, listed below, stored in PE sections.
In principle this file can be created with a relatively simple `objcopy` invocation,
but the recommended way is to use a helper program
([`ukify`](https://www.freedesktop.org/software/systemd/man/ukify.html)),
which takes care of appropriate alignment and facilitates signing for SecureBoot.

UKIs are UEFI applications images, and hence should initialize the `Subsystem` field of the *optional* PE
header to 0x0A (i.e. `IMAGE_SUBSYSTEM_EFI_APPLICATION`).

## UKI Components
UKIs consist of the following resources:

Expand All @@ -60,14 +63,52 @@ they may appear at most once,
except for the `.dtb` section which may appear multiple times.

Only the `.linux` section is required for the image to be considered a Unified *Kernel* Image.

A UKI will generally also contain various sections required for the boot stub,
but we don't document those here.

Boot menus such as [sd-boot](http://www.freedesktop.org/software/systemd/man/sd-boot.html)
and other consumers of UKIs may place additional requirements,
for example only show kernels with the `.osrel` section present.

Note that the same file format is also used for other purposes,
for example addons, which will contain a different subset of sections.
## PE Addons

UKIs are PE executables that may be executed directly in UEFI mode, and contain a variety of resources
built-in, as described above. Sometimes it's useful to provide a minimal level of modularity and extend UKIs
dynamically with additional resources from separate files. For this purpose UKIs can be combined with one or
more "PE Addons". This are regular PE UEFI application binaries, that can be authenticated via the usual UEFI
SecureBoot logic, and may contain additional PE sections from the list above, that shall be used in
combination with any PE sections of the UKI itself. At UKI invocation time, the EFI stub contained in the UKI
may load additional of these PE Addons and apply them (after authenticating them via UEFI APIs), combining
them with the resources of the UKI.

PE Addons may *not* contain `.linux` PE sections (this may be used to distinguish them from UKIs, which must
have this section, see above).

PE Addons must contain at least one section of the following types:

* `.cmdline`
* `.dtb`
* `.ucode`

PE Addons should be sorted by their filename, and applied in this order. In case of `.cmdline` all command
lines provided by addons are suffixed in this order to any command line included in the UKI. In case of
`.dtb` any such section included in the UKI shall be applied first, and those provided by add-ons should then
by applied in order as a fix-up. In case of `.ucode` the contained `cpio` archives should be prefixed to the
regular initrds passed to the kernel, in reverse order.

PE Addons may include sections of multiple types (e.g. both a `.cmdline` and a `.dtb` section), in which case
all of them should be applied.

Just like UKIs PE Addons should have the `Subystem` field of the *optional* PE header set to 0x0A.

The PE header's `Machine` field should be set to the local CPU type for the target machine of the Addon. When
enumerating PE Addons to apply, candidates should be skipped when their header field reports a non-native CPU
architecture.

PE Addons may contain executable code in a `.text` section. This code may be useful to write a friendly error
message to the UEFI console when executed as regular programs. The code should be ignored when the addon is
applied on an UKI.

## UKI TPM PCR Measurements

Expand Down Expand Up @@ -151,7 +192,7 @@ individual resources listed above at once, and their combination. Standard Linux
[`pesign`](https://github.com/rhboot/pesign) can be used to sign UKI files. The signature format and process
again match the ones already used for PE files, so they will not be redefined here.

## Distribution-built UKIs Installed by Package Managers
## Locations for Distribution-built UKIs Installed by Package Managers

UKIs that are built centrally by distributions and installed via the package manager should be installed in
`/usr/lib/modules/$UNAME/`, where `$UNAME` is the output of `uname -r` of the kernel included in the UKI, so
Expand All @@ -160,13 +201,12 @@ that tools staging or consuming UKIs have a common place to store and look for t
The installed UKIs should have a filename `<version format specification>.efi`, i.e. the filename is left to
implementers but must be valid for comparisons according to the [Version Format Specification](version_format_specification.md).

### Auxiliary resources
## Locations and Naming for UKI Auxiliary Resources

Auxiliary UKI resources (such as PE addons for command line extensions and similar,
as well as systemd-sysext and systemd-confext DDIs) built centrally by distributions and
installed via package manager should be installed into locations depending on
whether they should be applied to all UKIs installed in the ESP, or only to a
single specific UKI.
Auxiliary UKI resources (such as PE addons for kernel command line extensions and similar, as well as
systemd-sysext and systemd-confext DDIs) built centrally by distributions and installed via package manager
should be installed into locations depending on whether they should be applied to all UKIs installed in the
ESP, or only to a single specific UKI.

UKI auxiliary resources that apply to *all* installed UKIs should be
installed into `/usr/lib/modules/uki.extra.d/`. UKI auxiliary resources that
Expand All @@ -181,7 +221,7 @@ depends on the resource type:
* `.sysext.raw` for sysext DDIs,
* `.confext.raw` for confext DDIs

#### Example
### Example

Given a UKI `bar_123.efi` that includes a kernel `6.9.1-1.foo`, consider
* a PE addon `machine-id` that should apply to all installed UKIs,
Expand Down
Loading