Unified Kernel Images

A Unified Kernel Image (UKI) is a combination of an UEFI boot stub, a Linux kernel, and further (optional) resources like an initrd, all combined into a single UEFI image. This file can either be directly invoked by the UEFI firmware bootloader or by a bootloader like rEFInd or an OS’ bootloader.

The UEFI boot stub is a small program that can be executed by the UEFI firmware. After the UEFI firmware bootlader has loaded the UKI, it executes the boot stub, which loads the kernel and all other resources from the UKI file into memory, transitions into the kernel and thus handles control over to the kernel.

UKIs come in PE format with COFF sections. UEFI uses a subset of the PE32+ image format with a modified header signature, which distinguishes UEFI images from normal PE32 executables. The “+” addition to PE32 provides the 64-bit relocation fix-up extensions to standard PE32 format.

UKI components

An UKI consists at least of the following two components:

• An UEFI boot stub that forms the initial program and loads the kernel. It contains various PE sections that are required for a program, including .text, .reloc, .data, and others.
• .linux section – containing a Linux kernel.

Additionally, an UKI can contain the following optional components:

• .cmdline section with kernel command line. If absent, the loader implementation may allow local overrides instead.
• .initrd section with initrd.
• osrel section with OS release info as found in /etc/os-release. This can be used for displaying the OS in a bootloader menu.
• .uname section with kernel release info as displayed with uname -r. Like the .osrel section, this info can also be used for displaying the OS in a bootloader menu.
• .ucode section with CPU microcode. This is handed to the kernel before any other initrd.
• .splash section with a splash image that is displayed before transitioning into the Linux kernel.
• .hwids section with hardware identification table (also known as HWID or CHID).
• .dtb section with compiled device tree.
• on or more .dbauto sections with compiled device tree. The first .dtbauto section that matches the current hardware overrides an existing .dtb section. Matching is done either by the first compatible property with one from the firmware-provided device tree or by the SMBIOS fields using the contents of the .hwids section.
• .sbat section with SBAT (Secure Boot Advanced Targeting) metadata, typically in CSV file encoding. SBAT metadata defines revocation policies for components like the kernel or add-ons, allowing to enforce security updates and revoke outdated or vulnerable modules without needing full image hashes, using security generations for efficiency.
• .pcrsig section with PCR 11 hashes, along with signatures of these hashes in JSON encoding. The signatures must match the key pair in the .pcrkey section described below.
• .pcrkey section with the public key of a public-private key pair in PEM format used to sign the expected PCR 11 value of the image.

All sections may appear at most once, except for the .dtbauto section which may appear multiple times.

multi-profile UKIs

An UKI may consist of a base profile with sections like described above and one or more profiles, separated from the base profile and each other by .profile sections. The .profile sections act both as a label for each profile and as delimiters between the base profile and each profile.

Each .profile section introduces and defines a profile, which are numbered from zero, and typically denoted with a @ character before the profile number, i.e. @0, @1, @2, etc..

The UEFI stub combines the PE sections of the selected profile with the PE sections of the base profile that are not specified in the selected profile: sections in the selected profile override those of the same name in the base profile.

profile selection during boot

A profile is (optionally) selected by prefixing the EFI stub’s invocation parameters (“command line”) with @0 , @1 , @2 , etc. (an @ character, the numeric profile index, and a space character) in order to select the desired profile.

Profile @0 is the default profile and is automatically selected if a multi-profile UKI is invoked without any profile selected.

The profile selector prefix of the UKI’s invocation parameters is stripped after parsing, and is not passed to the kernel

example of a multi-profile UKI

tools for building UKIs

The page userspace tools lists some tools for building UKIs.

reference

• The Linux Userspace API (UAPI) Group,, UAPI.5 Unified Kernel Images
• elhacker.info, Visual Studio, Microsoft Portable Executable and Common Object File Format Specification, Revision 8.0 - May 16, 2006