Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
specs/uki: say that only the .linux section is required, mention addons
Browse files Browse the repository at this point in the history
People requested clarification as to what sections are "required"
in a UKI. Say that if .linux is present, it's a UKI.
This is intentionally vague: depending on the use of the UKI, some other
sections will almost always be present, but also depending on the
intended use, those might be different sections. So let's keep the
specification simple and only define the minimum necessary.

When we have a proper specificiation for addons, we shall link it here.
(Or maybe we'll add it here?)

Closes #74.
keszybz committed Nov 24, 2023
1 parent 757262f commit a9d27cc
Showing 1 changed file with 15 additions and 5 deletions.
20 changes: 15 additions & 5 deletions specs/unified_kernel_image.md
Original file line number Diff line number Diff line change
@@ -8,7 +8,7 @@ SPDX-License-Identifier: CC-BY-4.0
# Unified Kernel Image (UKI)

A Unified Kernel Image (UKI) is a combination of an UEFI boot stub program,
a Linux kernel image, an initrd, and further resources in a single UEFI PE file.
a Linux kernel image, an optional initrd, and further resources in a single UEFI PE file.
This file can either be directly invoked by the UEFI firmware
(which is useful in particular in some cloud/Confidential Computing environments)
or through a boot loader
@@ -46,17 +46,27 @@ UKIs consist of the following resources:
* The Linux kernel in the `.linux` PE section.
* Optionally, information describing the OS this kernel is intended for, in the `.osrel` section. The contents of this section are derived from `/etc/os-release` of the target OS. They can be useful for presentation of the UKI in the boot loader menu, and ordering it against other entries using the included version information.
* Optionally, the kernel command line in the `.cmdline` section. If this is absent, the loader implementation may allow local overrides instead.
* The initrd that the kernel shall unpack and invoke, in the `.initrd` section.
* Optionally, the initrd that the kernel shall unpack and invoke, in the `.initrd` section.
* Optionally, a splash image to bring to screen before transitioning into the Linux kernel, in the `.splash` section.
* Optionally, one or more compiled Device Trees, for systems which need it, each in its separate `.dtb` section. If multiple `.dtb` sections exist then one of them is selected according to an implementation-specific algorithm.
* Optionally, information describing kernel release information (i.e. `uname -r` output) in the `.uname` section. This is also useful for presentation of the UKI in the boot loader menu, and ordering it against other entries.
* Optionally, a CSV file encoding the SBAT metadata for the image, in the `.sbat` section. The [SBAT format is defined by the Shim project](https://github.com/rhboot/shim/blob/main/SBAT.md), and used for UEFI revocation purposes.
* Optionally, a JSON file encoding expected PCR 11 hash values seen from userspace once the UKI has booted up, along with signatures of these expected PCR 11 hash values, in the `.pcrsig` section. The signatures must also match the key pair described below.
* Optionally, the public part of a public-private key pair in PEM format used to sign the expected PCR 11 value of the image, in the `.pcrpkey` section.

Note that all of the sections defined above are singletons: they may
appear once at most – except for the `.dtb` section which may
appear more than once.
Note that all of the sections defined above are singletons:
they may appear at most once,
except for the `.dtb` section which may be 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.

## UKI TPM PCR Measurements

0 comments on commit a9d27cc

Please sign in to comment.