1SYSTEMD-STUB(7) systemd-stub SYSTEMD-STUB(7)
2
6 systemd-stub, sd-stub, linuxx64.efi.stub, linuxia32.efi.stub,
7 linuxaa64.efi.stub - A simple UEFI kernel boot stub
8
10 /usr/lib/systemd/boot/efi/linuxx64.efi.stub
11 /usr/lib/systemd/boot/efi/linuxia32.efi.stub
13 /usr/lib/systemd/boot/efi/linuxaa64.efi.stub
15 ESP/.../foo.efi.extra.d/*.addon.efi
17 ESP/.../foo.efi.extra.d/*.cred
19 ESP/.../foo.efi.extra.d/*.raw
21 ESP/loader/addons/*.addon.efi
23 ESP/loader/credentials/*.cred
25
27 systemd-stub (stored in per-architecture files linuxx64.efi.stub,
28 linuxia32.efi.stub, linuxaa64.efi.stub on disk) is a simple UEFI boot
29 stub. An UEFI boot stub is attached to a Linux kernel binary image, and
30 is a piece of code that runs in the UEFI firmware environment before
31 transitioning into the Linux kernel environment. The UEFI boot stub
32 ensures a Linux kernel is executable as regular UEFI binary, and is
33 able to do various preparations before switching the system into the
34 Linux world.
35 The UEFI boot stub looks for various resources for the kernel
37 invocation inside the UEFI PE binary itself. This allows combining
38 various resources inside a single PE binary image (usually called
39 "Unified Kernel Image", or "UKI" for short), which may then be signed
40 via UEFI SecureBoot as a whole, covering all individual resources at
41 once. Specifically it may include:
42 • The ELF Linux kernel images will be looked for in the ".linux" PE
44 section of the executed image.
45 • OS release information, i.e. the os-release(5) file of the OS the
47 kernel belongs to, in the ".osrel" PE section.
48 • Kernel version information, i.e. the output of uname -r for the
50 kernel included in the UKI, in the ".uname" PE section.
51 • The initrd will be loaded from the ".initrd" PE section.
53 • A compiled binary DeviceTree will be looked for in the ".dtb" PE
55 section.
56 • Kernel version information, i.e. the output of uname -r for the
58 kernel included in the UKI, in the ".uname" PE section.
59 • The kernel command line to pass to the invoked kernel will be
61 looked for in the ".cmdline" PE section.
62 • A boot splash (in Windows .BMP format) to show on screen before
64 invoking the kernel will be looked for in the ".splash" PE section.
65 • A set of cryptographic signatures for expected TPM2 PCR values when
67 this kernel is booted, in JSON format, in the ".pcrsig" section.
68 This is useful for implementing TPM2 policies that bind disk
69 encryption and similar to kernels that are signed by a specific
70 key.
71 • A public key in PEM format matching this TPM2 PCR signature data in
73 the ".pcrpkey" section.
74 If UEFI SecureBoot is enabled and the ".cmdline" section is present in
76 the executed image, any attempts to override the kernel command line by
77 passing one as invocation parameters to the EFI binary are ignored.
78 Thus, in order to allow overriding the kernel command line, either
79 disable UEFI SecureBoot, or don't include a kernel command line PE
80 section in the kernel image file. If a command line is accepted via EFI
81 invocation parameters to the EFI binary it is measured into TPM PCR 12
82 (if a TPM is present).
83 If a DeviceTree is embedded in the ".dtb" section, it replaces an
85 existing DeviceTree in the corresponding EFI configuration table.
86 systemd-stub will ask the firmware via the "EFI_DT_FIXUP_PROTOCOL" for
87 hardware specific fixups to the DeviceTree.
88 The contents of seven of these eight PE sections are measured into TPM
90 PCR 11, that is otherwise not used. Thus, it can be pre-calculated
91 without too much effort. The ".pcrsig" section is not included in this
92 PCR measurement, since it's supposed to contain signatures for the
93 expected results for these measurements, i.e. of the outputs of the
94 measurement operation, and thus cannot also be input to it.
95 When ".pcrsig" and/or ".pcrpkey" are present in a unified kernel image
97 their contents are passed to the booted kernel in an synthetic initrd
98 cpio archive that places them in the /.extra/tpm2-pcr-signature.json
99 and /.extra/tpm2-pcr-public-key.pem files. Typically, a tmpfiles.d(5)
100 line then ensures they are copied into
101 /run/systemd/tpm2-pcr-signature.json and
102 /run/systemd/tpm2-pcr-public-key.pem where they remain accessible even
103 after the system transitions out of the initrd environment into the
104 host file system. Tools such systemd-cryptsetup@.service(8), systemd-
105 cryptenroll(1) and systemd-creds(1) will automatically use files
106 present under these paths to unlock protected resources (encrypted
107 storage or credentials) or bind encryption to booted kernels.
108
110 The systemd-stub UEFI boot stub automatically collects two types of
111 auxiliary companion files optionally placed in drop-in directories on
112 the same partition as the EFI binary, dynamically generates cpio initrd
113 archives from them, and passes them to the kernel. Specifically:
114 • For a kernel binary called foo.efi, it will look for files with the
116 .cred suffix in a directory named foo.efi.extra.d/ next to it. If
117 the kernel binary uses a counter for the purpose of Automatic Boot
118 Assessment[1], this counter will be ignored. For example,
119 foo+3-0.efi will look in directory foo.efi.extra.d/. A cpio archive
120 is generated from all files found that way, placing them in the
121 /.extra/credentials/ directory of the initrd file hierarchy. The
122 main initrd may then access them in this directory. This is
123 supposed to be used to store auxiliary, encrypted, authenticated
124 credentials for use with LoadCredentialEncrypted= in the UEFI
125 System Partition. See systemd.exec(5) and systemd-creds(1) for
126 details on encrypted credentials. The generated cpio archive is
127 measured into TPM PCR 12 (if a TPM is present).
128 • Similarly, files foo.efi.extra.d/*.raw are packed up in a cpio
130 archive and placed in the /.extra/sysext/ directory in the initrd
131 file hierarchy. This is supposed to be used to pass additional
132 system extension images to the initrd. See systemd-sysext(8) for
133 details on system extension images. The generated cpio archive
134 containing these system extension images is measured into TPM PCR
135 13 (if a TPM is present).
136 • Similarly, files foo.efi.extra.d/*.addon.efi are loaded and
138 verified as PE binaries, and a ".cmdline" section is parsed from
139 them. In case Secure Boot is enabled, these files will be validated
140 using keys in UEFI DB, Shim's DB or Shim's MOK, and will be
141 rejected otherwise. Additionally, if the both the addon and the UKI
142 contain a a ".uname" section, the addon will be rejected if they do
143 not exactly match. It is recommended to always add a ".sbat"
144 section to all signed addons, so that they may be revoked with a
145 SBAT policy update, without requiring blocklisting via DBX/MOKX.
146 The ukify(1) tool will add a SBAT policy by default if none is
147 passed when building addons. For more information on SBAT see
148 Shim's documentation[2]. Addons are supposed to be used to pass
149 additional kernel command line parameters, regardless of the kernel
150 image being booted, for example to allow platform vendors to ship
151 platform-specific configuration. The loaded command line addon
152 files are sorted, loaded, measured into TPM PCR 12 (if a TPM is
153 present) and appended to the kernel command line. UKI command line
154 options are listed first, then options from addons in
155 /loader/addons/*.addon.efi are appended next, and finally
156 UKI-specific addons are appended last. Addons are always loaded in
157 the same order based on the filename, so that, given the same set
158 of addons, the same set of measurements can be expected in PCR12,
159 however note that the filename is not protected by the PE
160 signature, and as such an attacker with write access to the ESP
161 could potentially rename these files to change the order in which
162 they are loaded, in a way that could alter the functionality of the
163 kernel, as some options might be order dependent. If you sign such
164 addons, you should pay attention to the PCR12 values and make use
165 of an attestation service so that improper use of your signed
166 addons can be detected and dealt with using one of the
167 aforementioned revocation mechanisms.
168 • Files /loader/credentials/*.cred are packed up in a cpio archive
170 and placed in the /.extra/global_credentials/ directory of the
171 initrd file hierarchy. This is supposed to be used to pass
172 additional credentials to the initrd, regardless of the kernel
173 being booted. The generated cpio archive is measured into TPM PCR
174 12 (if a TPM is present).
175 • Additionally, files /loader/addons/*.addon.efi are loaded and
177 verified as PE binaries, and a ".cmdline" section is parsed from
178 them. This is supposed to be used to pass additional command line
179 parameters to the kernel, regardless of the kernel being booted.
180 These mechanisms may be used to parameterize and extend trusted (i.e.
182 signed), immutable initrd images in a reasonably safe way: all data
183 they contain is measured into TPM PCRs. On access they should be
184 further validated: in case of the credentials case by
185 encrypting/authenticating them via TPM, as exposed by systemd-creds
186 encrypt -T (see systemd-creds(1) for details); in case of the system
187 extension images by using signed Verity images.
188
190 Note that when a unified kernel using systemd-stub is invoked the
191 firmware will measure it as a whole to TPM PCR 4, covering all embedded
192 resources, such as the stub code itself, the core kernel, the embedded
193 initrd and kernel command line (see above for a full list).
194 Also note that the Linux kernel will measure all initrds it receives
196 into TPM PCR 9. This means every type of initrd will be measured two or
197 three times: the initrd embedded in the kernel image will be measured
198 to PCR 4, PCR 9 and PCR 11; the initrd synthesized from credentials
199 will be measured to both PCR 9 and PCR 12; the initrd synthesized from
200 system extensions will be measured to both PCR 4 and PCR 9. Let's
201 summarize the OS resources and the PCRs they are measured to:
202 Table 1. OS Resource PCR Summary
204 ┌───────────────────────────┬─────────────────┐
205 │OS Resource │ Measurement PCR │
206 ├───────────────────────────┼─────────────────┤
207 │systemd-stub code (the │ 4 │
208 │entry point of the unified │ │
209 │PE binary) │ │
210 ├───────────────────────────┼─────────────────┤
211 │Core kernel code (embedded │ 4 + 11 │
212 │in unified PE binary) │ │
213 ├───────────────────────────┼─────────────────┤
214 │OS release information │ 4 + 11 │
215 │(embedded in the unified │ │
216 │PE binary) │ │
217 ├───────────────────────────┼─────────────────┤
218 │Main initrd (embedded in │ 4 + 9 + 11 │
219 │unified PE binary) │ │
220 ├───────────────────────────┼─────────────────┤
221 │Default kernel command │ 4 + 11 │
222 │line (embedded in unified │ │
223 │PE binary) │ │
224 ├───────────────────────────┼─────────────────┤
225 │Overridden kernel command │ 12 │
226 │line │ │
227 ├───────────────────────────┼─────────────────┤
228 │Boot splash (embedded in │ 4 + 11 │
229 │the unified PE binary) │ │
230 ├───────────────────────────┼─────────────────┤
231 │TPM2 PCR signature JSON │ 4 + 9 │
232 │(embedded in unified PE │ │
233 │binary, synthesized into │ │
234 │initrd) │ │
235 ├───────────────────────────┼─────────────────┤
236 │TPM2 PCR PEM public key │ 4 + 9 + 11 │
237 │(embedded in unified PE │ │
238 │binary, synthesized into │ │
239 │initrd) │ │
240 ├───────────────────────────┼─────────────────┤
241 │Credentials (synthesized │ 9 + 12 │
242 │initrd from companion │ │
243 │files) │ │
244 ├───────────────────────────┼─────────────────┤
245 │System Extensions │ 9 + 13 │
246 │(synthesized initrd from │ │
247 │companion files) │ │
248 └───────────────────────────┴─────────────────┘
249
251 The following EFI variables are defined, set and read by systemd-stub,
252 under the vendor UUID "4a67b082-0a4c-41cf-b6c7-440b29bb8c4f", for
253 communication between the boot stub and the OS:
254 LoaderDevicePartUUID
256 Contains the partition UUID of the EFI System Partition the EFI
257 image was run from. systemd-gpt-auto-generator(8) uses this
258 information to automatically find the disk booted from, in order to
259 discover various other partitions on the same disk automatically.
260 LoaderFirmwareInfo, LoaderFirmwareType
262 Brief firmware information. Use bootctl(1) to view this data.
263 LoaderImageIdentifier
265 The path of EFI executable, relative to the EFI System Partition's
266 root directory. Use bootctl(1) to view this data.
267 StubInfo
269 Brief stub information. Use bootctl(1) to view this data.
270 StubPcrKernelImage
272 The PCR register index the kernel image, initrd image, boot splash,
273 devicetree database, and the embedded command line are measured
274 into, formatted as decimal ASCII string (e.g. "11"). This variable
275 is set if a measurement was successfully completed, and remains
276 unset otherwise.
277 StubPcrKernelParameters
279 The PCR register index the kernel command line and credentials are
280 measured into, formatted as decimal ASCII string (e.g. "12"). This
281 variable is set if a measurement was successfully completed, and
282 remains unset otherwise.
283 StubPcrInitRDSysExts
285 The PCR register index the systemd extensions for the initrd, which
286 are picked up from the file system the kernel image is located on.
287 Formatted as decimal ASCII string (e.g. "13"). This variable is
288 set if a measurement was successfully completed, and remains unset
289 otherwise.
290 Note that some of the variables above may also be set by the boot
292 loader. The stub will only set them if they aren't set already. Some of
293 these variables are defined by the Boot Loader Interface[3].
294
296 The following resources are passed as initrd cpio archives to the
297 booted kernel, and thus make up the initial file system hierarchy in
298 the initrd execution environment:
299 /
301 The main initrd from the ".initrd" PE section of the unified kernel
302 image.
303 /.extra/credentials/*.cred
305 Credential files (suffix ".cred") that are placed next to the
306 unified kernel image (as described above) are copied into the
307 /.extra/credentials/ directory in the initrd execution environment.
308 /.extra/global_credentials/*.cred
310 Similar, credential files in the /loader/credentials/ directory in
311 the file system the unified kernel image is placed in are copied
312 into the /.extra/global_credentials/ directory in the initrd
313 execution environment.
314 /.extra/sysext/*.raw
316 System extension image files (suffix ".raw") that are placed next
317 to the unified kernel image (as described above) are copied into
318 the /.extra/sysext/ directory in the initrd execution environment.
319 /.extra/tpm2-pcr-signature.json
321 The TPM2 PCR signature JSON object included in the ".pcrsig" PE
322 section of the unified kernel image is copied into the
323 /.extra/tpm2-pcr-signature.json file in the initrd execution
324 environment.
325 /.extra/tpm2-pcr-pkey.pem
327 The PEM public key included in the ".pcrpkey" PE section of the
328 unified kernel image is copied into the
329 /.extra/tpm2-pcr-public-key.pem file in the initrd execution
330 environment.
331 Note that all these files are located in the "tmpfs" file system the
333 kernel sets up for the initrd file hierarchy and are thus lost when the
334 system transitions from the initrd execution environment into the host
335 file system. If these resources shall be kept around over this
336 transition they need to be copied to a place that survives the
337 transition first, for example via a suitable tmpfiles.d(5) line. By
338 default, this is done for the TPM2 PCR signature and public key files.
339
341 systemd-stub can be configured using SMBIOS Type 11 strings. Applicable
342 strings consist of a name, followed by "=", followed by the value.
343 systemd-stub will search the table for a string with a specific name,
344 and if found, use its value. The following strings are read:
345 io.systemd.stub.kernel-cmdline-extra
347 If set, the value of this string is added to the list of kernel
348 command line arguments that are measured in PCR12 and passed to the
349 kernel.
350
352 In order to assemble a bootable Unified Kernel Image from various
353 components as described above, use ukify(1).
354
356 systemd-boot(7), systemd.exec(5), systemd-creds(1), systemd-sysext(8),
357 Boot Loader Specification[4], Boot Loader Interface[3], ukify(1),
358 systemd-measure(1)
359
361 1. Automatic Boot Assessment
362 https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT
363 2. Shim's documentation
365 https://github.com/rhboot/shim/blob/main/SBAT.md
366 3. Boot Loader Interface
368 https://systemd.io/BOOT_LOADER_INTERFACE
369 4. Boot Loader Specification
371 https://uapi-group.org/specifications/specs/boot_loader_specification
372systemd 254 SYSTEMD-STUB(7)