Skip to content

Commit

Permalink
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. We now 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
specificiation 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?)
  • Loading branch information
keszybz committed Oct 4, 2023
1 parent 3d1b337 commit daa613b
Showing 1 changed file with 12 additions and 3 deletions.
15 changes: 12 additions & 3 deletions specs/unified_kernel_image.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -45,7 +45,7 @@ UKIs consist of the following resources:
It contains various sections normally required for a program,
including `.text`, `.reloc`, `.data`, and others.
* The Linux kernel in the `.linux` section.
* 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, the kernel command line in the `.cmdline` section. If this is absent, the loader implementation may allow local overrides instead.
* 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, 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.
Expand All @@ -55,7 +55,16 @@ UKIs consist of the following resources:
* 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 abovementioned key pair.
* 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.

Note that all of the sections defined above are singletons: they may appear once at most – except for the `.dtb` section which may be 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 many 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.
Note that the same file format is also used for other purposes,
for example addons,
which will contain a different subset of sections.

### JSON Format for `.pcrsig`
The format is a single JSON object, encoded as a zero-terminated `UTF-8` string. Each name in the object
Expand Down

0 comments on commit daa613b

Please sign in to comment.