Debian Codegraph @

upstream/debian-trixie/man1/ukify.1

raw
1 '\" t
2 .TH "UKIFY" "1" "" "systemd 257.13" "ukify"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 ukify \- Combine components into a signed Unified Kernel Image for UEFI systems
24 .SH "SYNOPSIS"
25 .HP \w'\fBukify\fR\ 'u
26 \fBukify\fR [OPTIONS...] build
27 .HP \w'\fBukify\fR\ 'u
28 \fBukify\fR [OPTIONS...] genkey
29 .HP \w'\fBukify\fR\ 'u
30 \fBukify\fR [OPTIONS...] inspect FILE...
31 .SH "DESCRIPTION"
32 .PP
33 \fBukify\fR
34 is a tool whose primary purpose is to combine components (usually a kernel, an initrd, and a UEFI boot stub) to create a
35 \m[blue]\fBUnified Kernel Image (UKI)\fR\m[]\&\s-2\u[1]\d\s+2
36 \(em a PE binary that can be executed by the firmware to start the embedded linux kernel\&. See
37 \fBsystemd-stub\fR(7)
38 for details about the stub\&.
39 .SH "COMMANDS"
40 .PP
41 The following commands are understood:
42 .SS "build"
43 .PP
44 This command creates a Unified Kernel Image\&. The two primary options that should be specified for the
45 \fBbuild\fR
46 verb are
47 \fILinux=\fR/\fB\-\-linux=\fR, and
48 \fIInitrd=\fR/\fB\-\-initrd=\fR\&.
49 \fIInitrd=\fR
50 accepts multiple whitespace\-separated paths and
51 \fB\-\-initrd=\fR
52 can be specified multiple times\&.
53 .PP
54 Additional sections will be inserted into the UKI, either automatically or only if a specific option is provided\&. See the discussions of
55 \fIMicrocode=\fR/\fB\-\-microcode=\fR,
56 \fICmdline=\fR/\fB\-\-cmdline=\fR,
57 \fIOSRelease=\fR/\fB\-\-os\-release=\fR,
58 \fIDeviceTree=\fR/\fB\-\-devicetree=\fR,
59 \fIDeviceTreeAuto=\fR/\fB\-\-devicetree\-auto=\fR,
60 \fIHWIDs=\fR/\fB\-\-hwids=\fR,
61 \fISplash=\fR/\fB\-\-splash=\fR,
62 \fIPCRPKey=\fR/\fB\-\-pcrpkey=\fR,
63 \fIUname=\fR/\fB\-\-uname=\fR,
64 \fISBAT=\fR/\fB\-\-sbat=\fR, and
65 \fB\-\-section=\fR
66 below\&.
67 .PP
68 \fBukify\fR
69 can also be used to assemble a PE binary that is not executable but contains auxiliary data, for example additional kernel command line entries\&.
70 .PP
71 If PCR signing keys are provided via the
72 \fIPCRPrivateKey=\fR/\fB\-\-pcr\-private\-key=\fR
73 and
74 \fIPCRPublicKey=\fR/\fB\-\-pcr\-public\-key=\fR
75 options, PCR values that will be seen after booting with the given kernel, initrd, and other sections, will be calculated, signed, and embedded in the UKI\&.
76 \fBsystemd-measure\fR(1)
77 is used to perform this calculation and signing\&.
78 .PP
79 The calculation of PCR values is done for specific boot phase paths\&. Those can be specified with the
80 \fIPhases=\fR/\fB\-\-phases=\fR
81 option\&. If not specified, the default provided by
82 \fBsystemd\-measure\fR
83 is used\&. It is also possible to specify the
84 \fIPCRPrivateKey=\fR/\fB\-\-pcr\-private\-key=\fR,
85 \fIPCRPublicKey=\fR/\fB\-\-pcr\-public\-key=\fR, and
86 \fIPhases=\fR/\fB\-\-phases=\fR
87 arguments more than once\&. Signatures will then be performed with each of the specified keys\&. On the command line, when both
88 \fB\-\-phases=\fR
89 and
90 \fB\-\-pcr\-private\-key=\fR
91 are used, they must be specified the same number of times, and then the n\-th boot phase path set will be signed by the n\-th key\&. This can be used to build different trust policies for different phases of the boot\&. In the config file,
92 \fIPCRPrivateKey=\fR,
93 \fIPCRPublicKey=\fR, and
94 \fIPhases=\fR
95 are grouped into separate sections, describing separate boot phases\&. If one of
96 \fISigningEngine=\fR/\fB\-\-signing\-engine=\fR
97 or
98 \fISigningProvider=\fR/\fB\-\-signing\-provider=\fR
99 is specified, then the private key arguments will be passed verbatim to
100 \fBopenssl\fR(1)
101 as URIs, and the public key arguments will be loaded as X\&.509 certificates, so that signing can be performed with an OpenSSL engine or provider respectively\&.
102 .PP
103 If a SecureBoot signing key is provided via the
104 \fISecureBootPrivateKey=\fR/\fB\-\-secureboot\-private\-key=\fR
105 option, the resulting PE binary will be signed as a whole, allowing the resulting UKI to be trusted by SecureBoot\&. Also see the discussion of automatic enrollment in
106 \fBsystemd-boot\fR(7)\&.
107 .PP
108 If the stub and/or the kernel contain
109 "\&.sbat"
110 sections they will be merged in the UKI so that revocation updates affecting either are considered when the UKI is loaded by Shim\&. For more information on SBAT see
111 \m[blue]\fBShim documentation\fR\m[]\&\s-2\u[2]\d\s+2\&.
112 .SS "genkey"
113 .PP
114 This command creates the keys for PCR signing and the key and certificate used for SecureBoot signing\&. The same configuration options that determine what keys and in which paths will be needed for signing when
115 \fBbuild\fR
116 is used, here determine which keys will be created\&. See the discussion of
117 \fIPCRPrivateKey=\fR/\fB\-\-pcr\-private\-key=\fR,
118 \fIPCRPublicKey=\fR/\fB\-\-pcr\-public\-key=\fR, and
119 \fISecureBootPrivateKey=\fR/\fB\-\-secureboot\-private\-key=\fR
120 below\&.
121 .PP
122 The output files must not exist\&.
123 .SS "inspect"
124 .PP
125 Display information about the sections in a given binary or binaries\&. If
126 \fB\-\-all\fR
127 is given, all sections are shown\&. Otherwise, if
128 \fB\-\-section=\fR
129 option is specified at least once, only those sections are shown\&. Otherwise, well\-known sections that are typically included in an UKI are shown\&. For each section, its name, size, and sha256\-digest is printed\&. For text sections, the contents are printed\&.
130 .PP
131 Also see the description of
132 \fB\-j\fR/\fB\-\-json=\fR
133 and
134 \fB\-\-section=\fR\&.
135 .PP
136 Other tools that may be useful for inspect UKIs:
137 \fBllvm-objdump\fR(1)
138 \fB\-p\fR
139 and
140 \fBpe\-inspect\fR\&.
141 .SH "CONFIGURATION SETTINGS"
142 .PP
143 Settings can appear in configuration files (the syntax with
144 \fISomeSetting=\fR\fI\fIvalue\fR\fR) and on the command line (the syntax with
145 \fB\-\-some\-setting=\fR\fB\fIvalue\fR\fR)\&. For some command line parameters, a single\-letter shortcut is also allowed\&. In the configuration files, the setting must be in the appropriate section, so the descriptions are grouped by section below\&. When the same setting appears in the configuration file and on the command line, generally the command line setting has higher priority and overwrites the config file setting completely\&. If some setting behaves differently, this is described below\&.
146 .PP
147 If no config file is provided via the option
148 \fB\-\-config=\fR\fB\fIPATH\fR\fR,
149 \fBukify\fR
150 will try to look for a default configuration file in the following paths in this order:
151 /etc/systemd/ukify\&.conf,
152 /run/systemd/ukify\&.conf,
153 /usr/local/lib/systemd/ukify\&.conf, and
154 /usr/lib/systemd/ukify\&.conf, and then load the first one found\&.
155 \fBukify\fR
156 will proceed normally if no configuration file is specified and no default one is found\&.
157 .PP
158 The
159 \fILINUX\fR
160 and
161 \fIINITRD\fR
162 positional arguments, or the equivalent
163 \fILinux=\fR
164 and
165 \fIInitrd=\fR
166 settings, are optional\&. If more than one initrd is specified, they will all be combined into a single PE section\&. This is useful to, for example, prepend microcode before the actual initrd\&.
167 .PP
168 The following options and settings are understood:
169 .SS "Command line\-only options"
170 .PP
171 \fB\-\-config=\fR\fB\fIPATH\fR\fR
172 .RS 4
173 Load configuration from the given config file\&. In general, settings specified in the config file have lower precedence than the settings specified via options\&. In cases where the command line option does not fully override the config file setting are explicitly mentioned in the descriptions of individual options\&.
174 .sp
175 Added in version 254\&.
176 .RE
177 .PP
178 \fB\-\-measure\fR, \fB\-\-no\-measure\fR
179 .RS 4
180 Enable or disable a call to
181 \fBsystemd-measure\fR(1)
182 to print pre\-calculated PCR values\&. Defaults to false\&.
183 .sp
184 Added in version 253\&.
185 .RE
186 .PP
187 \fB\-\-section=\fR\fB\fINAME\fR\fR\fB:\fR\fB\fITEXT\fR\fR\fB|\fR\fB\fI@PATH\fR\fR, \fB\-\-section=\fR\fB\fINAME\fR\fR\fB:text|binary\fR\fB[@\fIPATH\fR]\fR
188 .RS 4
189 For all verbs except
190 \fBinspect\fR, the first syntax is used\&. Specify an arbitrary additional section
191 "\fINAME\fR"\&. The argument may be a literal string, or
192 "@"
193 followed by a path name\&. This option may be specified more than once\&. Any sections specified in this fashion will be inserted (in order) before the
194 "\&.linux"
195 section which is always last\&.
196 .sp
197 For the
198 \fBinspect\fR
199 verb, the second syntax is used\&. The section
200 \fINAME\fR
201 will be inspected (if found)\&. If the second argument is
202 "text", the contents will be printed\&. If the third argument is given, the contents will be saved to the file named
203 \fIPATH\fR\&.
204 .sp
205 Note that the name is used as\-is, and if the section name should start with a dot, it must be included in
206 \fINAME\fR\&.
207 .sp
208 Added in version 253\&.
209 .RE
210 .PP
211 \fB\-\-join\-profile=\fR\fB\fIPATH\fR\fR
212 .RS 4
213 Takes a path to an existing PE file containing an additional profile to add to the unified kernel image\&. The profile can be generated beforehand with
214 \fBukify\fR\&. The profile does not need to be signed or contain PCR measurements\&. All UKI PE sections of the specified PE file are copied into the generated UKI\&. This is useful for generating multi\-profile UKIs\&. Note that this only copies PE sections that are defined by the UKI specification, and ignores any other, for example
215 "\&.text"
216 or similar\&.
217 .sp
218 Added in version 257\&.
219 .RE
220 .PP
221 \fB\-\-tools=\fR\fB\fIDIRS\fR\fR
222 .RS 4
223 Specify one or more directories with helper tools\&.
224 \fBukify\fR
225 will look for helper tools in those directories first, and if not found, try to load them from
226 \fI$PATH\fR
227 in the usual fashion\&.
228 .sp
229 Added in version 253\&.
230 .RE
231 .PP
232 \fB\-\-output=\fR\fB\fIFILENAME\fR\fR
233 .RS 4
234 The output filename\&. If not specified, the name of the
235 \fILINUX\fR
236 argument, with the suffix
237 "\&.unsigned\&.efi"
238 or
239 "\&.signed\&.efi"
240 will be used, depending on whether signing for SecureBoot was performed\&.
241 .sp
242 Added in version 253\&.
243 .RE
244 .PP
245 \fB\-\-summary\fR
246 .RS 4
247 Print a summary of loaded config and exit\&. This is useful to check how the options from the configuration file and the command line are combined\&.
248 .sp
249 Added in version 254\&.
250 .RE
251 .PP
252 \fB\-\-all\fR
253 .RS 4
254 Print all sections (with
255 \fBinspect\fR
256 verb)\&.
257 .sp
258 Added in version 255\&.
259 .RE
260 .PP
261 \fB\-\-json\fR
262 .RS 4
263 Generate JSON output (with
264 \fBinspect\fR
265 verb)\&.
266 .sp
267 Added in version 255\&.
268 .RE
269 .PP
270 \fB\-h\fR, \fB\-\-help\fR
271 .RS 4
272 Print a short help text and exit\&.
273 .RE
274 .PP
275 \fB\-\-version\fR
276 .RS 4
277 Print a short version string and exit\&.
278 .RE
279 .SS "[UKI] section"
280 .PP
281 \fILinux=\fR\fI\fILINUX\fR\fR, \fB\-\-linux=\fR\fB\fILINUX\fR\fR
282 .RS 4
283 A path to the kernel binary\&.
284 .sp
285 Added in version 254\&.
286 .RE
287 .PP
288 \fIOSRelease=\fR\fI\fITEXT\fR\fR\fI|\fR\fI\fI@PATH\fR\fR, \fB\-\-os\-release=\fR\fB\fITEXT\fR\fR\fB|\fR\fB\fI@PATH\fR\fR
289 .RS 4
290 The os\-release description (the
291 "\&.osrel"
292 section)\&. The argument may be a literal string, or
293 "@"
294 followed by a path name\&. If not specified, the
295 \fBos-release\fR(5)
296 file will be picked up from the host system\&. If explicitly set to an empty string, the "\&.osrel" section is omitted from the UKI (this is not recommended in most cases, and causes the resulting artifact to not be recognized as a UKI by other tools like
297 \fBkernel\-install\fR
298 and
299 \fBbootctl\fR)\&.
300 .sp
301 Added in version 253\&.
302 .RE
303 .PP
304 \fICmdline=\fR\fI\fITEXT\fR\fR\fI|\fR\fI\fI@PATH\fR\fR, \fB\-\-cmdline=\fR\fB\fITEXT\fR\fR\fB|\fR\fB\fI@PATH\fR\fR
305 .RS 4
306 The kernel command line (the
307 "\&.cmdline"
308 section)\&. The argument may be a literal string, or
309 "@"
310 followed by a path name\&. If not specified, no command line will be embedded\&.
311 .sp
312 Added in version 253\&.
313 .RE
314 .PP
315 \fIInitrd=\fR\fI\fIINITRD\fR\fR\fI\&.\&.\&.\fR, \fB\-\-initrd=\fR\fB\fILINUX\fR\fR
316 .RS 4
317 Zero or more initrd paths\&. In the configuration file, items are separated by whitespace\&. The initrds are combined in the order of specification, with the initrds specified in the config file first\&.
318 .sp
319 Added in version 254\&.
320 .RE
321 .PP
322 \fIMicrocode=\fR\fI\fIUCODE\fR\fR, \fB\-\-microcode=\fR\fB\fIUCODE\fR\fR
323 .RS 4
324 Path to initrd containing microcode updates\&. If not specified, the section will not be present\&.
325 .sp
326 Added in version 256\&.
327 .RE
328 .PP
329 \fISplash=\fR\fI\fIPATH\fR\fR, \fB\-\-splash=\fR\fB\fIPATH\fR\fR
330 .RS 4
331 A picture to display during boot (the
332 "\&.splash"
333 section)\&. The argument is a path to a BMP file\&. If not specified, the section will not be present\&.
334 .sp
335 Added in version 253\&.
336 .RE
337 .PP
338 \fIDeviceTree=\fR\fI\fIPATH\fR\fR, \fB\-\-devicetree=\fR\fB\fIPATH\fR\fR
339 .RS 4
340 The devicetree description (the
341 "\&.dtb"
342 section)\&. The argument is a path to a compiled binary DeviceTree file\&. If not specified, the section will not be present\&.
343 .sp
344 Added in version 253\&.
345 .RE
346 .PP
347 \fIDeviceTreeAuto=\fR\fI\fIPATH\fR\fR\fI\&.\&.\&.\fR, \fB\-\-devicetree\-auto=\fR\fB\fIPATH\fR\fR
348 .RS 4
349 Zero or more automatically selectable DeviceTree files\&. In the configuration file, items are separated by whitespace\&. Each DeviceTree will be in a separate
350 "\&.dtbauto"
351 section\&.
352 .sp
353 Added in version 257\&.
354 .RE
355 .PP
356 \fIHWIDs=\fR\fI\fIPATH\fR\fR, \fB\-\-hwids=\fR\fB\fIPATH\fR\fR
357 .RS 4
358 The hardware ID device table (the
359 "\&.hwids"
360 section)\&. The argument is a path to a directory with JSON HWID device description files\&. Each file needs to contain a single JSON object with a
361 "name",
362 "compatible"
363 and
364 "hwids"
365 keys\&. The
366 "name"
367 and
368 "compatible"
369 keys must have string values and the
370 "hwids"
371 key must have a list of strings as value, where the strings must be valid UUIDs that represent CHIDs/HWIDs\&. Example:
372 .sp
373 .if n \{\
374 .RS 4
375 .\}
376 .nf
377 {
378 "name": "Example Laptop 16 Gen 7",
379 "compatible": "example,laptop\-16\-g7",
380 "hwids": [
381 "5dc05bf4\-01f6\-4089\-b464\-a08c47ea9295",
382 "3e3f8f3c\-2003\-46f2\-811c\-85554f7d5952"
383 ]
384 }
385 .fi
386 .if n \{\
387 .RE
388 .\}
389 .sp
390 Here
391 "Example Laptop 16 Gen 7"
392 is the device
393 "name"
394 (as defined by the manufacturer),
395 "example,laptop\-16\-g7"
396 is the
397 "compatible"
398 (as defined by the kernel) and
399 "hwids"
400 is an array of CHIDs/HWIDs (extracted i\&.e\&. from
401 \fBfwupdtool hwids\fR
402 output)\&. If not specified, the section will not be present\&. It is recommended to specify this parameter if automatically selectable DeviceTrees are to be used\&.
403 .sp
404 Added in version 257\&.
405 .RE
406 .PP
407 \fIUname=\fR\fI\fIVERSION\fR\fR, \fB\-\-uname=\fR\fB\fIVERSION\fR\fR
408 .RS 4
409 Specify the kernel version (as in
410 \fBuname \-r\fR, the
411 "\&.uname"
412 section)\&. If not specified, an attempt will be made to extract the version string from the kernel image\&. It is recommended to pass this explicitly if known, because the extraction is based on heuristics and not very reliable\&. If not specified and extraction fails, the section will not be present\&.
413 .sp
414 Added in version 253\&.
415 .RE
416 .PP
417 \fISBAT=\fR\fI\fITEXT\fR\fR\fI|\fR\fI\fI@PATH\fR\fR, \fB\-\-sbat=\fR\fB\fITEXT\fR\fR\fB|\fR\fB\fI@PATH\fR\fR
418 .RS 4
419 SBAT metadata associated with the UKI or addon\&. SBAT policies are useful to revoke whole groups of UKIs or addons with a single, static policy update that does not take space in DBX/MOKX\&. If not specified manually, a default metadata entry consisting of
420 .sp
421 .if n \{\
422 .RS 4
423 .\}
424 .nf
425 uki,1,UKI,uki,1,https://uapi\-group\&.org/specifications/specs/unified_kernel_image/
426 .fi
427 .if n \{\
428 .RE
429 .\}
430 .sp
431 for UKIs and
432 .sp
433 .if n \{\
434 .RS 4
435 .\}
436 .nf
437 uki\-addon,1,UKI Addon,addon,1,https://www\&.freedesktop\&.org/software/systemd/man/latest/systemd\-stub\&.html
438 .fi
439 .if n \{\
440 .RE
441 .\}
442 .sp
443 for addons will be used, to ensure it is always possible to revoke them\&. For more information on SBAT see
444 \m[blue]\fBShim documentation\fR\m[]\&\s-2\u[2]\d\s+2\&.
445 .sp
446 Added in version 254\&.
447 .RE
448 .PP
449 \fIPCRPKey=\fR\fI\fIPATH\fR\fR, \fB\-\-pcrpkey=\fR\fB\fIPATH\fR\fR
450 .RS 4
451 A path to a public key to embed in the
452 "\&.pcrpkey"
453 section\&. If not specified, and there\*(Aqs exactly one
454 \fIPCRPublicKey=\fR/\fB\-\-pcr\-public\-key=\fR
455 argument, that key will be used\&. Otherwise, the section will not be present\&.
456 .sp
457 Added in version 253\&.
458 .RE
459 .PP
460 \fIProfile=\fR\fI\fIPATH\fR\fR, \fB\-\-profile=\fR\fB\fIPATH\fR\fR
461 .RS 4
462 A path to a UKI profile to place in an
463 "\&.profile"
464 section\&. This option is useful for creating multi\-profile UKIs, and is typically used in combination with
465 \fB\-\-join\-profile=\fR, to extend the specified UKI with an additional profile\&.
466 .sp
467 Added in version 257\&.
468 .RE
469 .PP
470 \fIPCRBanks=\fR\fI\fIPATH\fR\fR, \fB\-\-pcr\-banks=\fR\fB\fIPATH\fR\fR
471 .RS 4
472 A comma or space\-separated list of PCR banks to sign a policy for\&. If not present, all known banks will be used ("sha1",
473 "sha256",
474 "sha384",
475 "sha512"), which will fail if not supported by the system\&.
476 .sp
477 Added in version 253\&.
478 .RE
479 .PP
480 \fISecureBootSigningTool=\fR\fI\fISIGNER\fR\fR, \fB\-\-signtool=\fR\fB\fISIGNER\fR\fR
481 .RS 4
482 Whether to use
483 "sbsign",
484 "pesign", or
485 "systemd\-sbsign"\&. Depending on this choice, different parameters are required in order to sign an image\&. Defaults to
486 "sbsign"\&.
487 .sp
488 Added in version 254\&.
489 .RE
490 .PP
491 \fISecureBootPrivateKey=\fR\fI\fISB_KEY\fR\fR, \fB\-\-secureboot\-private\-key=\fR\fB\fISB_KEY\fR\fR
492 .RS 4
493 A path to a private key to use for signing of the resulting binary\&. If the
494 \fISigningEngine=\fR/\fB\-\-signing\-engine=\fR
495 or
496 \fISigningProvider=\fR/\fB\-\-signing\-provider=\fR
497 option is used, this may also be an engine or provider specific designation\&. This option is required by
498 \fISecureBootSigningTool=sbsign\fR/\fB\-\-signtool=sbsign\fR
499 and
500 \fISecureBootSigningTool=systemd\-sbsign\fR/\fB\-\-signtool=systemd\-sbsign\fR\&.
501 .sp
502 Added in version 253\&.
503 .RE
504 .PP
505 \fISecureBootCertificate=\fR\fI\fISB_CERT\fR\fR, \fB\-\-secureboot\-certificate=\fR\fB\fISB_CERT\fR\fR
506 .RS 4
507 A path to a certificate to use for signing of the resulting binary\&. If the
508 \fISigningEngine=\fR/\fB\-\-signing\-engine=\fR
509 or
510 \fISigningProvider=\fR/\fB\-\-signing\-provider=\fR
511 option is used, this may also be an engine or provider specific designation\&. This option is required by
512 \fISecureBootSigningTool=sbsign\fR/\fB\-\-signtool=sbsign\fR
513 and
514 \fISecureBootSigningTool=systemd\-sbsign\fR/\fB\-\-signtool=systemd\-sbsign\fR\&.
515 .sp
516 Added in version 253\&.
517 .RE
518 .PP
519 \fISecureBootCertificateDir=\fR\fI\fISB_PATH\fR\fR, \fB\-\-secureboot\-certificate\-dir=\fR\fB\fISB_PATH\fR\fR
520 .RS 4
521 A path to a nss certificate database directory to use for signing of the resulting binary\&. Takes effect when
522 \fISecureBootSigningTool=pesign\fR/\fB\-\-signtool=pesign\fR
523 is used\&. Defaults to
524 /etc/pki/pesign\&.
525 .sp
526 Added in version 254\&.
527 .RE
528 .PP
529 \fISecureBootCertificateName=\fR\fI\fISB_CERTNAME\fR\fR, \fB\-\-secureboot\-certificate\-name=\fR\fB\fISB_CERTNAME\fR\fR
530 .RS 4
531 The name of the nss certificate database entry to use for signing of the resulting binary\&. This option is required by
532 \fISecureBootSigningTool=pesign\fR/\fB\-\-signtool=pesign\fR\&.
533 .sp
534 Added in version 254\&.
535 .RE
536 .PP
537 \fISecureBootCertificateValidity=\fR\fI\fIDAYS\fR\fR, \fB\-\-secureboot\-certificate\-validity=\fR\fB\fIDAYS\fR\fR
538 .RS 4
539 Period of validity (in days) for a certificate created by
540 \fBgenkey\fR\&. Defaults to 3650, i\&.e\&. 10 years\&.
541 .sp
542 Added in version 254\&.
543 .RE
544 .PP
545 \fISigningEngine=\fR\fI\fIENGINE\fR\fR, \fB\-\-signing\-engine=\fR\fB\fIENGINE\fR\fR
546 .RS 4
547 An OpenSSL engine to be used for signing the resulting binary and PCR measurements, see
548 \fBopenssl-engine\fR(1)\&.
549 .sp
550 Added in version 253\&.
551 .RE
552 .PP
553 \fISigningProvider=\fR\fI\fIPROVIDER\fR\fR, \fB\-\-signing\-provider=\fR\fB\fIPROVIDER\fR\fR
554 .RS 4
555 An OpenSSL provider to be used for signing the resulting binary and PCR measurements, see
556 \fBprovider\fR(7)\&. This option can only be used when
557 \fBsystemd\-sbsign\fR
558 is used as the signing tool\&.
559 .sp
560 Added in version 257\&.
561 .RE
562 .PP
563 \fICertificateProvider=\fR\fI\fIPROVIDER\fR\fR, \fB\-\-certificate\-provider=\fR\fB\fIPROVIDER\fR\fR
564 .RS 4
565 An OpenSSL provider to be used for loading the certificate used to sign the resulting binary and PCR measurements, see
566 \fBprovider\fR(7)\&. This option can only be used when
567 \fBsystemd\-sbsign\fR
568 is used as the signing tool\&.
569 .sp
570 Added in version 257\&.
571 .RE
572 .PP
573 \fISignKernel=\fR\fI\fIBOOL\fR\fR, \fB\-\-sign\-kernel\fR, \fB\-\-no\-sign\-kernel\fR
574 .RS 4
575 Override the detection of whether to sign the Linux binary itself before it is embedded in the combined image\&. If not specified, it will be signed if a SecureBoot signing key is provided via the
576 \fISecureBootPrivateKey=\fR/\fB\-\-secureboot\-private\-key=\fR
577 option and the binary has not already been signed\&. If
578 \fISignKernel=\fR/\fB\-\-sign\-kernel\fR
579 is true, and the binary has already been signed, the signature will be appended anyway\&.
580 .sp
581 Added in version 253\&.
582 .RE
583 .SS "[PCRSignature:\fINAME\fR] section"
584 .PP
585 In the config file, those options are grouped by section\&. On the command line, they must be specified in the same order\&. The sections specified in both sources are combined\&.
586 .PP
587 \fIPCRPrivateKey=\fR\fI\fIPATH\fR\fR, \fB\-\-pcr\-private\-key=\fR\fB\fIPATH\fR\fR
588 .RS 4
589 A private key to use for signing PCR policies\&. On the command line, this option may be specified more than once, in which case multiple signatures will be made\&.
590 .sp
591 Added in version 253\&.
592 .RE
593 .PP
594 \fIPCRPublicKey=\fR\fI\fIPATH\fR\fR, \fB\-\-pcr\-public\-key=\fR\fB\fIPATH\fR\fR
595 .RS 4
596 A public key to use for signing PCR policies\&.
597 .sp
598 On the command line, this option may be specified more than once, similarly to the
599 \fB\-\-pcr\-private\-key=\fR
600 option\&. If not present, the public keys will be extracted from the private keys\&. On the command line, if present, this option must be specified the same number of times as the
601 \fB\-\-pcr\-private\-key=\fR
602 option\&.
603 .sp
604 Added in version 253\&.
605 .RE
606 .PP
607 \fIPhases=\fR\fI\fILIST\fR\fR, \fB\-\-phases=\fR\fB\fILIST\fR\fR
608 .RS 4
609 A comma or space\-separated list of colon\-separated phase paths to sign a policy for\&. Each set of boot phase paths will be signed with the corresponding private key\&. If not present, the default of
610 \fBsystemd-measure\fR(1)
611 will be used\&.
612 .sp
613 On the command line, when this argument is present, it must appear the same number of times as the
614 \fB\-\-pcr\-private\-key=\fR
615 option\&.
616 .sp
617 Added in version 253\&.
618 .RE
619 .SH "EXAMPLES"
620 .PP
621 \fBExample\ \&1.\ \&Minimal invocation\fR
622 .sp
623 .if n \{\
624 .RS 4
625 .\}
626 .nf
627 $ ukify build \e
628 \-\-linux=/lib/modules/6\&.0\&.9\-300\&.fc37\&.x86_64/vmlinuz \e
629 \-\-initrd=/some/path/initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img \e
630 \-\-cmdline=\*(Aqquiet rw\*(Aq
631 .fi
632 .if n \{\
633 .RE
634 .\}
635 .PP
636 This creates an unsigned UKI
637 \&./vmlinuz\&.unsigned\&.efi\&.
638 .PP
639 \fBExample\ \&2.\ \&All the bells and whistles\fR
640 .sp
641 .if n \{\
642 .RS 4
643 .\}
644 .nf
645 $ ukify build \e
646 \-\-linux=/lib/modules/6\&.0\&.9\-300\&.fc37\&.x86_64/vmlinuz \e
647 \-\-initrd=early_cpio \e
648 \-\-initrd=/some/path/initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img \e
649 \-\-sbat=\*(Aqsbat,1,SBAT Version,sbat,1,https://github\&.com/rhboot/shim/blob/main/SBAT\&.md
650 uki\&.author\&.myimage,1,UKI for System,uki\&.author\&.myimage,1,https://uapi\-group\&.org/specifications/specs/unified_kernel_image/\*(Aq \e
651 \-\-pcr\-private\-key=tpm2\-pcr\-private\-key\-initrd\&.pem \e
652 \-\-pcr\-public\-key=tpm2\-pcr\-public\-key\-initrd\&.pem \e
653 \-\-phases=\*(Aqenter\-initrd\*(Aq \e
654 \-\-pcr\-private\-key=tpm2\-pcr\-private\-key\-system\&.pem \e
655 \-\-pcr\-public\-key=tpm2\-pcr\-public\-key\-system\&.pem \e
656 \-\-phases=\*(Aqenter\-initrd:leave\-initrd enter\-initrd:leave\-initrd:sysinit \e
657 enter\-initrd:leave\-initrd:sysinit:ready\*(Aq \e
658 \-\-pcr\-banks=sha384,sha512 \e
659 \-\-secureboot\-private\-key=sb\&.key \e
660 \-\-secureboot\-certificate=sb\&.cert \e
661 \-\-sign\-kernel \e
662 \-\-cmdline=\*(Aqquiet rw rhgb\*(Aq
663 .fi
664 .if n \{\
665 .RE
666 .\}
667 .PP
668 This creates a signed UKI
669 \&./vmlinuz\&.signed\&.efi\&. The initrd section contains two concatenated parts,
670 early_cpio
671 and
672 initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img\&. The policy embedded in the
673 "\&.pcrsig"
674 section will be signed for the initrd (the
675 \fBenter\-initrd\fR
676 phase) with the key
677 tpm2\-pcr\-private\-key\-initrd\&.pem, and for the main system (phases
678 \fBleave\-initrd\fR,
679 \fBsysinit\fR,
680 \fBready\fR) with the key
681 tpm2\-pcr\-private\-key\-system\&.pem\&. The Linux binary and the resulting combined image will be signed with the SecureBoot key
682 sb\&.key\&.
683 .PP
684 \fBExample\ \&3.\ \&All the bells and whistles, via a config file\fR
685 .PP
686 This is the same as the previous example, but this time the configuration is stored in a file:
687 .sp
688 .if n \{\
689 .RS 4
690 .\}
691 .nf
692 $ cat ukify\&.conf
693 [UKI]
694 Initrd=early_cpio
695 Cmdline=quiet rw rhgb
696
697 SecureBootPrivateKey=secure\-boot\-key\&.pem
698 SecureBootCertificate=secure\-boot\-certificate\&.pem
699 SignKernel=yes
700 PCRBanks=sha384,sha512
701
702 [PCRSignature:initrd]
703 PCRPrivateKey=tpm2\-pcr\-private\-key\-initrd\&.pem
704 PCRPublicKey=tpm2\-pcr\-public\-key\-initrd\&.pem
705 Phases=enter\-initrd
706
707 [PCRSignature:system]
708 PCRPrivateKey=tpm2\-pcr\-private\-key\-system\&.pem
709 PCRPublicKey=tpm2\-pcr\-public\-key\-system\&.pem
710 Phases=enter\-initrd:leave\-initrd
711 enter\-initrd:leave\-initrd:sysinit
712 enter\-initrd:leave\-initrd:sysinit:ready
713
714 $ ukify \-c ukify\&.conf build \e
715 \-\-linux=/lib/modules/6\&.0\&.9\-300\&.fc37\&.x86_64/vmlinuz \e
716 \-\-initrd=/some/path/initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img
717 .fi
718 .if n \{\
719 .RE
720 .\}
721 .PP
722 One "initrd" (early_cpio) is specified in the config file, and the other initrd (initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img) is specified on the command line\&. This may be useful for example when the first initrd contains microcode for the CPU and does not need to be updated when the kernel version changes, unlike the actual initrd\&.
723 .PP
724 \fBExample\ \&4.\ \&Kernel command line PE addon\fR
725 .sp
726 .if n \{\
727 .RS 4
728 .\}
729 .nf
730 ukify build \e
731 \-\-secureboot\-private\-key=secure\-boot\-key\&.pem \e
732 \-\-secureboot\-certificate=secure\-boot\-certificate\&.pem \e
733 \-\-cmdline=\*(Aqdebug\*(Aq \e
734 \-\-sbat=\*(Aqsbat,1,SBAT Version,sbat,1,https://github\&.com/rhboot/shim/blob/main/SBAT\&.md
735 uki\-addon\&.author,1,UKI Addon for System,uki\-addon\&.author,1,https://www\&.freedesktop\&.org/software/systemd/man/systemd\-stub\&.html\*(Aq
736 \-\-output=debug\&.addon\&.efi
737 .fi
738 .if n \{\
739 .RE
740 .\}
741 .PP
742 This creates a signed PE binary that contains the additional kernel command line parameter
743 "debug"
744 with SBAT metadata referring to the owner of the addon\&.
745 .PP
746 \fBExample\ \&5.\ \&Decide signing policy, and create certificate and keys\fR
747 .PP
748 First, let\*(Aqs create a configuration file that specifies what signatures shall be made:
749 .sp
750 .if n \{\
751 .RS 4
752 .\}
753 .nf
754 # cat >/etc/kernel/uki\&.conf <<EOF
755 [UKI]
756 SecureBootPrivateKey=/etc/kernel/secure\-boot\-key\&.pem
757 SecureBootCertificate=/etc/kernel/secure\-boot\-certificate\&.pem
758
759 [PCRSignature:initrd]
760 Phases=enter\-initrd
761 PCRPrivateKey=/etc/systemd/tpm2\-pcr\-private\-key\-initrd\&.pem
762 PCRPublicKey=/etc/systemd/tpm2\-pcr\-public\-key\-initrd\&.pem
763
764 [PCRSignature:system]
765 Phases=enter\-initrd:leave\-initrd enter\-initrd:leave\-initrd:sysinit
766 enter\-initrd:leave\-initrd:sysinit:ready
767 PCRPrivateKey=/etc/systemd/tpm2\-pcr\-private\-key\-system\&.pem
768 PCRPublicKey=/etc/systemd/tpm2\-pcr\-public\-key\-system\&.pem
769 EOF
770 .fi
771 .if n \{\
772 .RE
773 .\}
774 .PP
775 Next, we can generate the certificate and keys:
776 .sp
777 .if n \{\
778 .RS 4
779 .\}
780 .nf
781 # ukify genkey \-\-config=/etc/kernel/uki\&.conf
782 Writing SecureBoot private key to /etc/kernel/secure\-boot\-key\&.pem
783 Writing SecureBoot certificate to /etc/kernel/secure\-boot\-certificate\&.pem
784 Writing private key for PCR signing to /etc/systemd/tpm2\-pcr\-private\-key\-initrd\&.pem
785 Writing public key for PCR signing to /etc/systemd/tpm2\-pcr\-public\-key\-initrd\&.pem
786 Writing private key for PCR signing to /etc/systemd/tpm2\-pcr\-private\-key\-system\&.pem
787 Writing public key for PCR signing to /etc/systemd/tpm2\-pcr\-public\-key\-system\&.pem
788 .fi
789 .if n \{\
790 .RE
791 .\}
792 .PP
793 (Both operations need to be done as root to allow write access to
794 /etc/kernel/\&.)
795 .PP
796 Subsequent invocations using the config file (\fBukify build \-\-config=/etc/kernel/uki\&.conf\fR) will use this certificate and key files\&. Note that the
797 \fBkernel-install\fR(8)
798 plugin
799 60\-ukify\&.install
800 uses
801 /etc/kernel/uki\&.conf
802 by default, so after this file has been created, installations of kernels that create a UKI on the local machine using
803 \fBkernel\-install\fR
804 will perform signing using this config\&.
805 .PP
806 \fBExample\ \&6.\ \&Multi\-Profile UKI\fR
807 .PP
808 First, create a few profiles:
809 .sp
810 .if n \{\
811 .RS 4
812 .\}
813 .nf
814 $ ukify build \e
815 \-\-profile=\*(AqTITLE=Base\*(Aq \e
816 \-\-output=profile0\&.efi
817 .fi
818 .if n \{\
819 .RE
820 .\}
821 .PP
822 Add a second profile (@1):
823 .sp
824 .if n \{\
825 .RS 4
826 .\}
827 .nf
828 $ ukify build \e
829 \-\-profile=\*(AqTITLE=Boot into Storage Target Mode
830 ID=storagetm\*(Aq \e
831 \-\-cmdline=\*(Aqquiet rw rd\&.systemd\&.unit=storage\-target\-mode\&.target\*(Aq \e
832 \-\-output=profile1\&.efi
833 .fi
834 .if n \{\
835 .RE
836 .\}
837 .PP
838 Add a third profile (@2):
839 .sp
840 .if n \{\
841 .RS 4
842 .\}
843 .nf
844 $ ukify build \e
845 \-\-profile=\*(AqTITLE=Factory Reset
846 ID=factory\-reset\*(Aq \e
847 \-\-cmdline=\*(Aqquiet rw systemd\&.unit=factory\-reset\&.target\*(Aq \e
848 \-\-output=profile2\&.efi
849 .fi
850 .if n \{\
851 .RE
852 .\}
853 .PP
854 Then, create a UKI and include all the generated profiles:
855 .sp
856 .if n \{\
857 .RS 4
858 .\}
859 .nf
860 $ ukify build \e
861 \-\-linux=/lib/modules/6\&.0\&.9\-300\&.fc37\&.x86_64/vmlinuz \e
862 \-\-initrd=/some/path/initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img \e
863 \-\-cmdline=\*(Aqquiet rw\*(Aq \e
864 \-\-join\-profile=profile0\&.efi \e
865 \-\-join\-profile=profile1\&.efi \e
866 \-\-join\-profile=profile2\&.efi \e
867 \-\-output=base\&.efi
868 .fi
869 .if n \{\
870 .RE
871 .\}
872 .PP
873 The resulting UKI
874 base\-with\-profile\-0\-1\-2\&.efi
875 will now contain three profiles\&.
876 .SH "SEE ALSO"
877 .PP
878 \fBsystemd\fR(1), \fBsystemd-stub\fR(7), \fBsystemd-boot\fR(7), \fBsystemd-measure\fR(1), \fBsystemd-pcrphase.service\fR(8)
879 .SH "NOTES"
880 .IP " 1." 4
881 Unified Kernel Image (UKI)
882 .RS 4
883 \%https://uapi-group.org/specifications/specs/unified_kernel_image/
884 .RE
885 .IP " 2." 4
886 Shim documentation
887 .RS 4
888 \%https://github.com/rhboot/shim/blob/main/SBAT.md
889 .RE