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/*.cred
17 ESP/.../foo.efi.extra.d/*.raw
19 ESP/loader/credentials/*.cred
21
23 systemd-stub (stored in per-architecture files linuxx64.efi.stub,
24 linuxia32.efi.stub, linuxaa64.efi.stub on disk) is a simple UEFI boot
25 stub. An UEFI boot stub is attached to a Linux kernel binary image, and
26 is a piece of code that runs in the UEFI firmware environment before
27 transitioning into the Linux kernel environment. The UEFI boot stub
28 ensures a Linux kernel is executable as regular UEFI binary, and is
29 able to do various preparations before switching the system into the
30 Linux world.
31 The UEFI boot stub looks for various resources for the kernel
33 invocation inside the UEFI PE binary itself. This allows combining
34 various resources inside a single PE binary image (usually called
35 "Unified Kernel Image", or "UKI" for short), which may then be signed
36 via UEFI SecureBoot as a whole, covering all individual resources at
37 once. Specifically it may include:
38 • The ELF Linux kernel images will be looked for in the ".linux" PE
40 section of the executed image.
41 • OS release information, i.e. the os-release(5) file of the OS the
43 kernel belongs to, in the ".osrel" PE section.
44 • The initrd will be loaded from the ".initrd" PE section.
46 • A compiled binary DeviceTree will be looked for in the ".dtb" PE
48 section.
49 • The kernel command line to pass to the invoked kernel will be
51 looked for in the ".cmdline" PE section.
52 • A boot splash (in Windows .BMP format) to show on screen before
54 invoking the kernel will be looked for in the ".splash" PE section.
55 • A set of cryptographic signatures for expected TPM2 PCR values when
57 this kernel is booted, in JSON format, in the ".pcrsig" section.
58 This is useful for implementing TPM2 policies that bind disk
59 encryption and similar to kernels that are signed by a specific
60 key.
61 • A public key in PEM format matching this TPM2 PCR signature data in
63 the ".pcrpkey" section.
64 If UEFI SecureBoot is enabled and the ".cmdline" section is present in
66 the executed image, any attempts to override the kernel command line by
67 passing one as invocation parameters to the EFI binary are ignored.
68 Thus, in order to allow overriding the kernel command line, either
69 disable UEFI SecureBoot, or don't include a kernel command line PE
70 section in the kernel image file. If a command line is accepted via EFI
71 invocation parameters to the EFI binary it is measured into TPM PCR 12
72 (if a TPM is present).
73 If a DeviceTree is embedded in the ".dtb" section, it replaces an
75 existing DeviceTree in the corresponding EFI configuration table.
76 systemd-stub will ask the firmware via the "EFI_DT_FIXUP_PROTOCOL" for
77 hardware specific fixups to the DeviceTree.
78 The contents of seven of these eight PE sections are measured into TPM
80 PCR 11, that is otherwise not used. Thus, it can be pre-calculated
81 without too much effort. The ".pcrsig" section is not included in this
82 PCR measurement, since it's supposed to contain signatures for the
83 expected results for these measurements, i.e. of the outputs of the
84 measurement operation, and thus cannot also be input to it.
85 When ".pcrsig" and/or ".pcrpkey" are present in a unified kernel image
87 their contents are passed to the booted kernel in an synthetic initrd
88 cpio archive that places them in the /.extra/tpm2-pcr-signature.json
89 and /.extra/tpm2-pcr-public-key.pem files. Typically, a tmpfiles.d(5)
90 line then ensures they are copied into
91 /run/systemd/tpm2-pcr-signature.json and
92 /run/systemd/tpm2-pcr-public-key.pem where they remain accessible even
93 after the system transitions out of the initrd environment into the
94 host file system. Tools such systemd-cryptsetup@.service(8), systemd-
95 cryptenroll(1) and systemd-creds(1) will automatically use files
96 present under these paths to unlock protected resources (encrypted
97 storage or credentials) or bind encryption to booted kernels.
98
100 The systemd-stub UEFI boot stub automatically collects two types of
101 auxiliary companion files optionally placed in drop-in directories on
102 the same partition as the EFI binary, dynamically generates cpio initrd
103 archives from them, and passes them to the kernel. Specifically:
104 • For a kernel binary called foo.efi, it will look for files with the
106 .cred suffix in a directory named foo.efi.extra.d/ next to it. A
107 cpio archive is generated from all files found that way, placing
108 them in the /.extra/credentials/ directory of the initrd file
109 hierarchy. The main initrd may then access them in this directory.
110 This is supposed to be used to store auxiliary, encrypted,
111 authenticated credentials for use with LoadCredentialEncrypted= in
112 the UEFI System Partition. See systemd.exec(5) and systemd-creds(1)
113 for details on encrypted credentials. The generated cpio archive is
114 measured into TPM PCR 12 (if a TPM is present).
115 • Similarly, files foo.efi.extra.d/*.raw are packed up in a cpio
117 archive and placed in the /.extra/sysext/ directory in the initrd
118 file hierarchy. This is supposed to be used to pass additional
119 system extension images to the initrd. See systemd-sysext(8) for
120 details on system extension images. The generated cpio archive
121 containing these system extension images is measured into TPM PCR
122 13 (if a TPM is present).
123 • Files /loader/credentials/*.cred are packed up in a cpio archive
125 and placed in the /.extra/global_credentials/ directory of the
126 initrd file hierarchy. This is supposed to be used to pass
127 additional credentials to the initrd, regardless of the kernel
128 being booted. The generated cpio archive is measured into TPM PCR
129 12 (if a TPM is present)
130 These mechanisms may be used to parameterize and extend trusted (i.e.
132 signed), immutable initrd images in a reasonably safe way: all data
133 they contain is measured into TPM PCRs. On access they should be
134 further validated: in case of the credentials case by
135 encrypting/authenticating them via TPM, as exposed by systemd-creds
136 encrypt -T (see systemd-creds(1) for details); in case of the system
137 extension images by using signed Verity images.
138
140 Note that when a unified kernel using systemd-stub is invoked the
141 firmware will measure it as a whole to TPM PCR 4, covering all embedded
142 resources, such as the stub code itself, the core kernel, the embedded
143 initrd and kernel command line (see above for a full list).
144 Also note that the Linux kernel will measure all initrds it receives
146 into TPM PCR 9. This means every type of initrd will be measured two or
147 three times: the initrd embedded in the kernel image will be measured
148 to PCR 4, PCR 9 and PCR 11; the initrd synthesized from credentials
149 will be measured to both PCR 9 and PCR 12; the initrd synthesized from
150 system extensions will be measured to both PCR 4 and PCR 9. Let's
151 summarize the OS resources and the PCRs they are measured to:
152 Table 1. OS Resource PCR Summary
154 ┌───────────────────────────┬─────────────────┐
155 │OS Resource │ Measurement PCR │
156 ├───────────────────────────┼─────────────────┤
157 │systemd-stub code (the │ 4 │
158 │entry point of the unified │ │
159 │PE binary) │ │
160 ├───────────────────────────┼─────────────────┤
161 │Core kernel code (embedded │ 4 + 11 │
162 │in unified PE binary) │ │
163 ├───────────────────────────┼─────────────────┤
164 │OS release information │ 4 + 11 │
165 │(embedded in the unified │ │
166 │PE binary) │ │
167 ├───────────────────────────┼─────────────────┤
168 │Main initrd (embedded in │ 4 + 9 + 11 │
169 │unified PE binary) │ │
170 ├───────────────────────────┼─────────────────┤
171 │Default kernel command │ 4 + 11 │
172 │line (embedded in unified │ │
173 │PE binary) │ │
174 ├───────────────────────────┼─────────────────┤
175 │Overridden kernel command │ 12 │
176 │line │ │
177 ├───────────────────────────┼─────────────────┤
178 │Boot splash (embedded in │ 4 + 11 │
179 │the unified PE binary) │ │
180 ├───────────────────────────┼─────────────────┤
181 │TPM2 PCR signature JSON │ 4 + 9 │
182 │(embedded in unified PE │ │
183 │binary, synthesized into │ │
184 │initrd) │ │
185 ├───────────────────────────┼─────────────────┤
186 │TPM2 PCR PEM public key │ 4 + 9 + 11 │
187 │(embedded in unified PE │ │
188 │binary, synthesized into │ │
189 │initrd) │ │
190 ├───────────────────────────┼─────────────────┤
191 │Credentials (synthesized │ 9 + 12 │
192 │initrd from companion │ │
193 │files) │ │
194 ├───────────────────────────┼─────────────────┤
195 │System Extensions │ 9 + 13 │
196 │(synthesized initrd from │ │
197 │companion files) │ │
198 └───────────────────────────┴─────────────────┘
199
201 The following EFI variables are defined, set and read by systemd-stub,
202 under the vendor UUID "4a67b082-0a4c-41cf-b6c7-440b29bb8c4f", for
203 communication between the boot stub and the OS:
204 LoaderDevicePartUUID
206 Contains the partition UUID of the EFI System Partition the EFI
207 image was run from. systemd-gpt-auto-generator(8) uses this
208 information to automatically find the disk booted from, in order to
209 discover various other partitions on the same disk automatically.
210 LoaderFirmwareInfo, LoaderFirmwareType
212 Brief firmware information. Use bootctl(1) to view this data.
213 LoaderImageIdentifier
215 The path of EFI executable, relative to the EFI System Partition's
216 root directory. Use bootctl(1) to view this data.
217 StubInfo
219 Brief stub information. Use bootctl(1) to view this data.
220 StubPcrKernelImage
222 The PCR register index the kernel image, initrd image, boot splash,
223 devicetree database, and the embedded command line are measured
224 into, formatted as decimal ASCII string (e.g. "11"). This variable
225 is set if a measurement was successfully completed, and remains
226 unset otherwise.
227 StubPcrKernelParameters
229 The PCR register index the kernel command line and credentials are
230 measured into, formatted as decimal ASCII string (e.g. "12"). This
231 variable is set if a measurement was successfully completed, and
232 remains unset otherwise.
233 StubPcrInitRDSysExts
235 The PCR register index the systemd extensions for the initrd, which
236 are picked up from the file system the kernel image is located on.
237 Formatted as decimal ASCII string (e.g. "13"). This variable is
238 set if a measurement was successfully completed, and remains unset
239 otherwise.
240 Note that some of the variables above may also be set by the boot
242 loader. The stub will only set them if they aren't set already. Some of
243 these variables are defined by the Boot Loader Interface[1].
244
246 The following resources are passed as initrd cpio archives to the
247 booted kernel, and thus make up the initial file system hierarchy in
248 the initrd execution environment:
249 /
251 The main initrd from the ".initrd" PE section of the unified kernel
252 image.
253 /.extra/credentials/*.cred
255 Credential files (suffix ".cred") that are placed next to the
256 unified kernel image (as described above) are copied into the
257 /.extra/credentials/ directory in the initrd execution environment.
258 /.extra/global_credentials/*.cred
260 Similar, credential files in the /loader/credentials/ directory in
261 the file system the unified kernel image is placed in are copied
262 into the /.extra/global_credentials/ directory in the initrd
263 execution environment.
264 /.extra/sysext/*.raw
266 System extension image files (suffix ".raw") that are placed next
267 to the unified kernel image (as described above) are copied into
268 the /.extra/sysext/ directory in the initrd execution environment.
269 /.extra/tpm2-pcr-signature.json
271 The TPM2 PCR signature JSON object included in the ".pcrsig" PE
272 section of the unified kernel image is copied into the
273 /.extra/tpm2-pcr-signature.json file in the initrd execution
274 environment.
275 /.extra/tpm2-pcr-pkey.pem
277 The PEM public key included in the ".pcrpkey" PE section of the
278 unified kernel image is copied into the
279 /.extra/tpm2-pcr-public-key.pem file in the initrd execution
280 environment.
281 Note that all these files are located in the "tmpfs" file system the
283 kernel sets up for the initrd file hierarchy and are thus lost when the
284 system transitions from the initrd execution environment into the host
285 file system. If these resources shall be kept around over this
286 transition they need to be copied to a place that survives the
287 transition first, for example via a suitable tmpfiles.d(5) line. By
288 default, this is done for the TPM2 PCR signature and public key files.
289
291 In order to assemble a bootable Unified Kernel Image from various
292 components as described above, use ukify(1).
293
295 systemd-boot(7), systemd.exec(5), systemd-creds(1), systemd-sysext(8),
296 Boot Loader Specification[2], Boot Loader Interface[1], ukify(1),
297 systemd-measure(1)
298
300 1. Boot Loader Interface
301 https://systemd.io/BOOT_LOADER_INTERFACE
302 2. Boot Loader Specification
304 https://uapi-group.org/specifications/specs/boot_loader_specification
305systemd 253 SYSTEMD-STUB(7)