From 6a4f4b6aaa5bdebaac7dfa9fe406b355a402712a Mon Sep 17 00:00:00 2001
From: Arian van Putten <arian.vanputten@gmail.com>
Date: Fri, 14 Nov 2025 15:40:26 +0100
Subject: [PATCH] Add note about canonical order of UKI components
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Zbigniew Jędrzejewski-Szmek <zbyszek@amutable.com>
---
 specs/unified_kernel_image.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/specs/unified_kernel_image.md b/specs/unified_kernel_image.md
index 06551d5e..396b8d43 100644
--- a/specs/unified_kernel_image.md
+++ b/specs/unified_kernel_image.md
@@ -47,6 +47,10 @@ header to 0x0A (i.e. `IMAGE_SUBSYSTEM_EFI_APPLICATION`).
 ## UKI Components
 UKIs consist of the following resources:
 
+<!--
+NOTE: these components are in canonical order for predictable PCR measurements.
+Please add any new components at the bottom of the list and NEVER reorder anything in this list.
+-->
 * An UEFI boot stub that forms the initial program.
   It contains various PE sections normally required for a program,
   including `.text`, `.reloc`, `.data`, and others.
@@ -64,6 +68,10 @@ 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 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.
 
+This list specifies the canonical order of sections.
+Items will not be reordered and new sections will be added at the end only.
+This is required for predicatable PCR measurements.
+
 Note that all of the sections defined above are singletons:
 they may appear at most once,
 except for the `.dtbauto` section which may appear multiple times.