Debian Codegraph @

upstream/mageia-cauldron/man1/ukify.1

raw
1 '\" t
2 .TH "UKIFY" "1" "" "systemd 258.7" "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 or
76 \fIPCRCertificate=\fR/\fB\-\-pcr\-certificate=\fR
77 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\&.
78 \fBsystemd-measure\fR(1)
79 is used to perform this calculation and signing\&.
80 .PP
81 The calculation of PCR values is done for specific boot phase paths\&. Those can be specified with the
82 \fIPhases=\fR/\fB\-\-phases=\fR
83 option\&. If not specified, the default provided by
84 \fBsystemd\-measure\fR
85 is used\&. It is also possible to specify the
86 \fIPCRPrivateKey=\fR/\fB\-\-pcr\-private\-key=\fR,
87 \fIPCRPublicKey=\fR/\fB\-\-pcr\-public\-key=\fR
88 or
89 \fIPCRCertificate=\fR/\fB\-\-pcr\-certificate=\fR, and
90 \fIPhases=\fR/\fB\-\-phases=\fR
91 arguments more than once\&. Signatures will then be performed with each of the specified keys\&. On the command line, when both
92 \fB\-\-phases=\fR
93 and
94 \fB\-\-pcr\-private\-key=\fR
95 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,
96 \fIPCRPrivateKey=\fR,
97 \fIPCRPublicKey=\fR, and
98 \fIPhases=\fR
99 are grouped into separate sections, describing separate boot phases\&. If one of
100 \fISigningEngine=\fR/\fB\-\-signing\-engine=\fR
101 or
102 \fISigningProvider=\fR/\fB\-\-signing\-provider=\fR
103 is specified, then the private key arguments will be passed verbatim to
104 \fBopenssl\fR(1)
105 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\&.
106 .PP
107 If a SecureBoot signing key is provided via the
108 \fISecureBootPrivateKey=\fR/\fB\-\-secureboot\-private\-key=\fR
109 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
110 \fBsystemd-boot\fR(7)\&.
111 .PP
112 If the stub and/or the kernel contain
113 "\&.sbat"
114 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
115 \m[blue]\fBShim documentation\fR\m[]\&\s-2\u[2]\d\s+2\&.
116 .SS "genkey"
117 .PP
118 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
119 \fBbuild\fR
120 is used, here determine which keys will be created\&. See the discussion of
121 \fIPCRPrivateKey=\fR/\fB\-\-pcr\-private\-key=\fR,
122 \fIPCRPublicKey=\fR/\fB\-\-pcr\-public\-key=\fR, and
123 \fISecureBootPrivateKey=\fR/\fB\-\-secureboot\-private\-key=\fR
124 below\&.
125 .PP
126 The output files must not exist\&.
127 .SS "inspect"
128 .PP
129 Display information about the sections in a given binary or binaries\&. If
130 \fB\-\-all\fR
131 is given, all sections are shown\&. Otherwise, if
132 \fB\-\-section=\fR
133 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\&.
134 .PP
135 Also see the description of
136 \fB\-j\fR/\fB\-\-json=\fR
137 and
138 \fB\-\-section=\fR\&.
139 .PP
140 Other tools that may be useful for inspect UKIs:
141 \fBllvm-objdump\fR(1)
142 \fB\-p\fR
143 and
144 \fBpe\-inspect\fR\&.
145 .SH "CONFIGURATION SETTINGS"
146 .PP
147 Settings can appear in configuration files (the syntax with
148 \fISomeSetting=\fR\fI\fIvalue\fR\fR) and on the command line (the syntax with
149 \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\&.
150 .PP
151 If no config file is provided via the option
152 \fB\-\-config=\fR\fB\fIPATH\fR\fR,
153 \fBukify\fR
154 will try to look for a default configuration file in the following paths in this order:
155 /etc/systemd/ukify\&.conf,
156 /run/systemd/ukify\&.conf,
157 /usr/local/lib/systemd/ukify\&.conf, and
158 /usr/lib/systemd/ukify\&.conf, and then load the first one found\&.
159 \fBukify\fR
160 will proceed normally if no configuration file is specified and no default one is found\&.
161 .PP
162 The
163 \fILINUX\fR
164 and
165 \fIINITRD\fR
166 positional arguments, or the equivalent
167 \fILinux=\fR
168 and
169 \fIInitrd=\fR
170 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\&.
171 .PP
172 The following options and settings are understood:
173 .SS "Command line\-only options"
174 .PP
175 \fB\-\-config=\fR\fB\fIPATH\fR\fR
176 .RS 4
177 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\&.
178 .sp
179 Added in version 254\&.
180 .RE
181 .PP
182 \fB\-\-measure\fR, \fB\-\-no\-measure\fR
183 .RS 4
184 Enable or disable a call to
185 \fBsystemd-measure\fR(1)
186 to print pre\-calculated PCR values\&. Defaults to false\&.
187 .sp
188 Added in version 253\&.
189 .RE
190 .PP
191 \fB\-\-policy\-digest\fR, \fB\-\-no\-policy\-digest\fR
192 .RS 4
193 Enable or disable a call to
194 \fBsystemd-measure\fR(1)
195 to print pre\-calculated TPM2 policy digests\&. Useful for offline signing of PCR policies\&. Defaults to false\&.
196 .sp
197 Added in version 258\&.
198 .RE
199 .PP
200 \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
201 .RS 4
202 For all verbs except
203 \fBinspect\fR, the first syntax is used\&. Specify an arbitrary additional section
204 "\fINAME\fR"\&. The argument may be a literal string, or
205 "@"
206 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
207 "\&.linux"
208 section which is always last\&.
209 .sp
210 For the
211 \fBinspect\fR
212 verb, the second syntax is used\&. The section
213 \fINAME\fR
214 will be inspected (if found)\&. If the second argument is
215 "text", the contents will be printed\&. If the third argument is given, the contents will be saved to the file named
216 \fIPATH\fR\&.
217 .sp
218 Note that the name is used as\-is, and if the section name should start with a dot, it must be included in
219 \fINAME\fR\&.
220 .sp
221 Added in version 253\&.
222 .RE
223 .PP
224 \fB\-\-join\-profile=\fR\fB\fIPATH\fR\fR
225 .RS 4
226 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
227 \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
228 "\&.text"
229 or similar\&.
230 .sp
231 Added in version 257\&.
232 .RE
233 .PP
234 \fB\-\-sign\-profile=\fR\fB\fIID\fR\fR
235 .RS 4
236 Takes a profile ID for which signed PCR measurements should be generated by ukify\&. This option can be used together with
237 \fB\-\-join\-profile=\fR
238 when building the final unified kernel image\&. If not specified, signed PCR measurements will be added for all profiles\&.
239 .sp
240 Added in version 258\&.
241 .RE
242 .PP
243 \fB\-\-join\-pcrsig=\fR\fB\fIPATH\fR\fR, \fB\-\-pcrsig=\fR\fB\fITEXT\fR\fR\fB|\fR\fB\fI@PATH\fR\fR
244 .RS 4
245 \fB\-\-join\-pcrsig=\fR
246 takes a path to an existing PE file containing a previously built UKI\&.
247 \fB\-\-pcrsig=\fR
248 takes a path to an existing pcrsig JSON blob, or a verbatim inline blob\&. They must be used together, and without specifying any other UKI section parameters\&.
249 \fBukify\fR
250 will attach the pcrsig JSON blob to the UKI\&. This is useful in combination with
251 \fB\-\-policy\-digest\fR
252 to create a UKI and then sign the TPM2 policy digests offline\&.
253 .sp
254 Added in version 258\&.
255 .RE
256 .PP
257 \fB\-\-tools=\fR\fB\fIDIRS\fR\fR
258 .RS 4
259 Specify one or more directories with helper tools\&.
260 \fBukify\fR
261 will look for helper tools in those directories first, and if not found, try to load them from
262 \fI$PATH\fR
263 in the usual fashion\&.
264 .sp
265 Added in version 253\&.
266 .RE
267 .PP
268 \fB\-\-output=\fR\fB\fIFILENAME\fR\fR
269 .RS 4
270 The output filename\&. If not specified, the name of the
271 \fILINUX\fR
272 argument, with the suffix
273 "\&.unsigned\&.efi"
274 or
275 "\&.signed\&.efi"
276 will be used, depending on whether signing for SecureBoot was performed\&.
277 .sp
278 Added in version 253\&.
279 .RE
280 .PP
281 \fB\-\-summary\fR
282 .RS 4
283 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\&.
284 .sp
285 Added in version 254\&.
286 .RE
287 .PP
288 \fB\-\-all\fR
289 .RS 4
290 Print all sections (with
291 \fBinspect\fR
292 verb)\&.
293 .sp
294 Added in version 255\&.
295 .RE
296 .PP
297 \fB\-\-json\fR
298 .RS 4
299 Generate JSON output (with
300 \fBinspect\fR
301 verb)\&.
302 .sp
303 Added in version 255\&.
304 .RE
305 .PP
306 \fB\-h\fR, \fB\-\-help\fR
307 .RS 4
308 Print a short help text and exit\&.
309 .RE
310 .PP
311 \fB\-\-version\fR
312 .RS 4
313 Print a short version string and exit\&.
314 .RE
315 .SS "[UKI] section"
316 .PP
317 \fILinux=\fR\fI\fILINUX\fR\fR, \fB\-\-linux=\fR\fB\fILINUX\fR\fR
318 .RS 4
319 A path to the kernel binary\&.
320 .sp
321 Added in version 254\&.
322 .RE
323 .PP
324 \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
325 .RS 4
326 The os\-release description (the
327 "\&.osrel"
328 section)\&. The argument may be a literal string, or
329 "@"
330 followed by a path name\&. If not specified, the
331 \fBos-release\fR(5)
332 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
333 \fBkernel\-install\fR
334 and
335 \fBbootctl\fR)\&.
336 .sp
337 Added in version 253\&.
338 .RE
339 .PP
340 \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
341 .RS 4
342 The kernel command line (the
343 "\&.cmdline"
344 section)\&. The argument may be a literal string, or
345 "@"
346 followed by a path name\&. If not specified, no command line will be embedded\&.
347 .sp
348 Added in version 253\&.
349 .RE
350 .PP
351 \fIInitrd=\fR\fI\fIINITRD\fR\fR\fI\&.\&.\&.\fR, \fB\-\-initrd=\fR\fB\fILINUX\fR\fR
352 .RS 4
353 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\&.
354 .sp
355 Added in version 254\&.
356 .RE
357 .PP
358 \fIMicrocode=\fR\fI\fIUCODE\fR\fR, \fB\-\-microcode=\fR\fB\fIUCODE\fR\fR
359 .RS 4
360 Path to initrd containing microcode updates\&. If not specified, the section will not be present\&.
361 .sp
362 Added in version 256\&.
363 .RE
364 .PP
365 \fISplash=\fR\fI\fIPATH\fR\fR, \fB\-\-splash=\fR\fB\fIPATH\fR\fR
366 .RS 4
367 A picture to display during boot (the
368 "\&.splash"
369 section)\&. The argument is a path to a BMP file\&. If not specified, the section will not be present\&.
370 .sp
371 Added in version 253\&.
372 .RE
373 .PP
374 \fIDeviceTree=\fR\fI\fIPATH\fR\fR, \fB\-\-devicetree=\fR\fB\fIPATH\fR\fR
375 .RS 4
376 The devicetree description (the
377 "\&.dtb"
378 section)\&. The argument is a path to a compiled binary DeviceTree file\&. If not specified, the section will not be present\&.
379 .sp
380 Added in version 253\&.
381 .RE
382 .PP
383 \fIDeviceTreeAuto=\fR\fI\fIPATH\fR\fR\fI\&.\&.\&.\fR, \fB\-\-devicetree\-auto=\fR\fB\fIPATH\fR\fR
384 .RS 4
385 Zero or more automatically selectable DeviceTree files\&. In the configuration file, items are separated by whitespace\&. Each DeviceTree will be in a separate
386 "\&.dtbauto"
387 section\&.
388 .sp
389 Added in version 257\&.
390 .RE
391 .PP
392 \fIHWIDs=\fR\fI\fIPATH\fR\fR, \fB\-\-hwids=\fR\fB\fIPATH\fR\fR
393 .RS 4
394 The hardware ID device table (the
395 "\&.hwids"
396 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
397 "name",
398 "compatible"
399 and
400 "hwids"
401 keys\&. The
402 "name"
403 and
404 "compatible"
405 keys must have string values and the
406 "hwids"
407 key must have a list of strings as value, where the strings must be valid UUIDs that represent CHIDs/HWIDs\&. Example:
408 .sp
409 .if n \{\
410 .RS 4
411 .\}
412 .nf
413 {
414 "type": "devicetree",
415 "name": "Example Laptop 16 Gen 7",
416 "compatible": "example,laptop\-16\-g7",
417 "hwids": [
418 "5dc05bf4\-01f6\-4089\-b464\-a08c47ea9295",
419 "3e3f8f3c\-2003\-46f2\-811c\-85554f7d5952"
420 ]
421 }
422 .fi
423 .if n \{\
424 .RE
425 .\}
426 .sp
427 Here
428 "Example Laptop 16 Gen 7"
429 is the device
430 "name"
431 (as defined by the manufacturer),
432 "example,laptop\-16\-g7"
433 is the
434 "compatible"
435 (as defined by the kernel) and
436 "hwids"
437 is an array of CHIDs/HWIDs (extracted i\&.e\&. from
438 \fBfwupdtool hwids\fR
439 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\&.
440 .sp
441 Added in version 257\&.
442 .RE
443 .PP
444 \fIUname=\fR\fI\fIVERSION\fR\fR, \fB\-\-uname=\fR\fB\fIVERSION\fR\fR
445 .RS 4
446 Specify the kernel version (as in
447 \fBuname \-r\fR, the
448 "\&.uname"
449 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\&.
450 .sp
451 Added in version 253\&.
452 .RE
453 .PP
454 \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
455 .RS 4
456 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
457 .sp
458 .if n \{\
459 .RS 4
460 .\}
461 .nf
462 uki,1,UKI,uki,1,https://uapi\-group\&.org/specifications/specs/unified_kernel_image/
463 .fi
464 .if n \{\
465 .RE
466 .\}
467 .sp
468 for UKIs and
469 .sp
470 .if n \{\
471 .RS 4
472 .\}
473 .nf
474 uki\-addon,1,UKI Addon,addon,1,https://www\&.freedesktop\&.org/software/systemd/man/latest/systemd\-stub\&.html
475 .fi
476 .if n \{\
477 .RE
478 .\}
479 .sp
480 for addons will be used, to ensure it is always possible to revoke them\&. For more information on SBAT see
481 \m[blue]\fBShim documentation\fR\m[]\&\s-2\u[2]\d\s+2\&.
482 .sp
483 Added in version 254\&.
484 .RE
485 .PP
486 \fIPCRPKey=\fR\fI\fIPATH\fR\fR, \fB\-\-pcrpkey=\fR\fB\fIPATH\fR\fR
487 .RS 4
488 A path to a public key to embed in the
489 "\&.pcrpkey"
490 section\&. If not specified, and there\*(Aqs exactly one
491 \fIPCRPublicKey=\fR/\fB\-\-pcr\-public\-key=\fR
492 or
493 \fIPCRCertificate=\fR/\fB\-\-pcr\-certificate=\fR
494 argument, that key will be used\&. Otherwise, the section will not be present\&.
495 .sp
496 Added in version 253\&.
497 .RE
498 .PP
499 \fIProfile=\fR\fI\fIPATH\fR\fR, \fB\-\-profile=\fR\fB\fIPATH\fR\fR
500 .RS 4
501 A path to a UKI profile to place in an
502 "\&.profile"
503 section\&. This option is useful for creating multi\-profile UKIs, and is typically used in combination with
504 \fB\-\-join\-profile=\fR, to extend the specified UKI with an additional profile\&.
505 .sp
506 Added in version 257\&.
507 .RE
508 .PP
509 \fIPCRBanks=\fR\fI\fIPATH\fR\fR, \fB\-\-pcr\-banks=\fR\fB\fIPATH\fR\fR
510 .RS 4
511 A comma or space\-separated list of PCR banks to sign a policy for\&. If not present, all known banks will be used ("sha1",
512 "sha256",
513 "sha384",
514 "sha512"), which will fail if not supported by the system\&.
515 .sp
516 Added in version 253\&.
517 .RE
518 .PP
519 \fISecureBootSigningTool=\fR\fI\fISIGNER\fR\fR, \fB\-\-signtool=\fR\fB\fISIGNER\fR\fR
520 .RS 4
521 Whether to use
522 "sbsign",
523 "pesign", or
524 "systemd\-sbsign"\&. Depending on this choice, different parameters are required in order to sign an image\&. Defaults to
525 "sbsign"\&.
526 .sp
527 Added in version 254\&.
528 .RE
529 .PP
530 \fISecureBootPrivateKey=\fR\fI\fISB_KEY\fR\fR, \fB\-\-secureboot\-private\-key=\fR\fB\fISB_KEY\fR\fR
531 .RS 4
532 A path to a private key to use for signing of the resulting binary\&. If the
533 \fISigningEngine=\fR/\fB\-\-signing\-engine=\fR
534 or
535 \fISigningProvider=\fR/\fB\-\-signing\-provider=\fR
536 option is used, this may also be an engine or provider specific designation\&. This option is required by
537 \fISecureBootSigningTool=sbsign\fR/\fB\-\-signtool=sbsign\fR
538 and
539 \fISecureBootSigningTool=systemd\-sbsign\fR/\fB\-\-signtool=systemd\-sbsign\fR\&.
540 .sp
541 Added in version 253\&.
542 .RE
543 .PP
544 \fISecureBootCertificate=\fR\fI\fISB_CERT\fR\fR, \fB\-\-secureboot\-certificate=\fR\fB\fISB_CERT\fR\fR
545 .RS 4
546 A path to a certificate to use for signing of the resulting binary\&. If the
547 \fISigningEngine=\fR/\fB\-\-signing\-engine=\fR
548 or
549 \fISigningProvider=\fR/\fB\-\-signing\-provider=\fR
550 option is used, this may also be an engine or provider specific designation\&. This option is required by
551 \fISecureBootSigningTool=sbsign\fR/\fB\-\-signtool=sbsign\fR
552 and
553 \fISecureBootSigningTool=systemd\-sbsign\fR/\fB\-\-signtool=systemd\-sbsign\fR\&.
554 .sp
555 Added in version 253\&.
556 .RE
557 .PP
558 \fISecureBootCertificateDir=\fR\fI\fISB_PATH\fR\fR, \fB\-\-secureboot\-certificate\-dir=\fR\fB\fISB_PATH\fR\fR
559 .RS 4
560 A path to a nss certificate database directory to use for signing of the resulting binary\&. Takes effect when
561 \fISecureBootSigningTool=pesign\fR/\fB\-\-signtool=pesign\fR
562 is used\&. Defaults to
563 /etc/pki/pesign\&.
564 .sp
565 Added in version 254\&.
566 .RE
567 .PP
568 \fISecureBootCertificateName=\fR\fI\fISB_CERTNAME\fR\fR, \fB\-\-secureboot\-certificate\-name=\fR\fB\fISB_CERTNAME\fR\fR
569 .RS 4
570 The name of the nss certificate database entry to use for signing of the resulting binary\&. This option is required by
571 \fISecureBootSigningTool=pesign\fR/\fB\-\-signtool=pesign\fR\&.
572 .sp
573 Added in version 254\&.
574 .RE
575 .PP
576 \fISecureBootCertificateValidity=\fR\fI\fIDAYS\fR\fR, \fB\-\-secureboot\-certificate\-validity=\fR\fB\fIDAYS\fR\fR
577 .RS 4
578 Period of validity (in days) for a certificate created by
579 \fBgenkey\fR\&. Defaults to 3650, i\&.e\&. 10 years\&.
580 .sp
581 Added in version 254\&.
582 .RE
583 .PP
584 \fISigningEngine=\fR\fI\fIENGINE\fR\fR, \fB\-\-signing\-engine=\fR\fB\fIENGINE\fR\fR
585 .RS 4
586 An OpenSSL engine to be used for signing the resulting binary and PCR measurements, see
587 \fBopenssl-engine\fR(1)\&.
588 .sp
589 Added in version 253\&.
590 .RE
591 .PP
592 \fISigningProvider=\fR\fI\fIPROVIDER\fR\fR, \fB\-\-signing\-provider=\fR\fB\fIPROVIDER\fR\fR
593 .RS 4
594 An OpenSSL provider to be used for signing the resulting binary and PCR measurements, see
595 \fBprovider\fR(7)\&. This option can only be used when
596 \fBsystemd\-sbsign\fR
597 is used as the signing tool\&.
598 .sp
599 Added in version 257\&.
600 .RE
601 .PP
602 \fICertificateProvider=\fR\fI\fIPROVIDER\fR\fR, \fB\-\-certificate\-provider=\fR\fB\fIPROVIDER\fR\fR
603 .RS 4
604 An OpenSSL provider to be used for loading the certificate used to sign the resulting binary and PCR measurements, see
605 \fBprovider\fR(7)\&. This option can only be used when
606 \fBsystemd\-sbsign\fR
607 is used as the signing tool\&.
608 .sp
609 Added in version 257\&.
610 .RE
611 .PP
612 \fISignKernel=\fR\fI\fIBOOL\fR\fR, \fB\-\-sign\-kernel\fR, \fB\-\-no\-sign\-kernel\fR
613 .RS 4
614 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
615 \fISecureBootPrivateKey=\fR/\fB\-\-secureboot\-private\-key=\fR
616 option and the binary has not already been signed\&. If
617 \fISignKernel=\fR/\fB\-\-sign\-kernel\fR
618 is true, and the binary has already been signed, the signature will be appended anyway\&.
619 .sp
620 Added in version 253\&.
621 .RE
622 .SS "[PCRSignature:\fINAME\fR] section"
623 .PP
624 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\&.
625 .PP
626 \fIPCRPrivateKey=\fR\fI\fIPATH\fR\fR, \fB\-\-pcr\-private\-key=\fR\fB\fIPATH\fR\fR
627 .RS 4
628 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\&.
629 .sp
630 Added in version 253\&.
631 .RE
632 .PP
633 \fIPCRPublicKey=\fR\fI\fIPATH\fR\fR, \fB\-\-pcr\-public\-key=\fR\fB\fIPATH\fR\fR
634 .RS 4
635 A public key to use for signing PCR policies\&.
636 .sp
637 On the command line, this option may be specified more than once, similarly to the
638 \fB\-\-pcr\-private\-key=\fR
639 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
640 \fB\-\-pcr\-private\-key=\fR
641 option\&. Cannot be specified if
642 \fB\-\-pcr\-certificate=\fR
643 is used\&.
644 .sp
645 Added in version 253\&.
646 .RE
647 .PP
648 \fIPCRCertificate=\fR\fI\fIPATH\fR\fR, \fB\-\-pcr\-certificate=\fR\fB\fIPATH\fR\fR
649 .RS 4
650 An X\&.509 certificate to use for signing PCR policies\&.
651 .sp
652 On the command line, this option may be specified more than once, similarly to the
653 \fB\-\-pcr\-private\-key=\fR
654 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
655 \fB\-\-pcr\-private\-key=\fR
656 option\&. Cannot be specified if
657 \fB\-\-pcr\-public\-key=\fR
658 is used\&.
659 .sp
660 Added in version 258\&.
661 .RE
662 .PP
663 \fIPhases=\fR\fI\fILIST\fR\fR, \fB\-\-phases=\fR\fB\fILIST\fR\fR
664 .RS 4
665 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
666 \fBsystemd-measure\fR(1)
667 will be used\&.
668 .sp
669 On the command line, when this argument is present, it must appear the same number of times as the
670 \fB\-\-pcr\-private\-key=\fR
671 option\&.
672 .sp
673 Added in version 253\&.
674 .RE
675 .SH "EXAMPLES"
676 .PP
677 \fBExample\ \&1.\ \&Minimal invocation\fR
678 .sp
679 .if n \{\
680 .RS 4
681 .\}
682 .nf
683 $ ukify build \e
684 \-\-linux=/lib/modules/6\&.0\&.9\-300\&.fc37\&.x86_64/vmlinuz \e
685 \-\-initrd=/some/path/initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img \e
686 \-\-cmdline=\*(Aqquiet rw\*(Aq
687 .fi
688 .if n \{\
689 .RE
690 .\}
691 .PP
692 This creates an unsigned UKI
693 \&./vmlinuz\&.unsigned\&.efi\&.
694 .PP
695 \fBExample\ \&2.\ \&All the bells and whistles\fR
696 .sp
697 .if n \{\
698 .RS 4
699 .\}
700 .nf
701 $ ukify build \e
702 \-\-linux=/lib/modules/6\&.0\&.9\-300\&.fc37\&.x86_64/vmlinuz \e
703 \-\-initrd=early_cpio \e
704 \-\-initrd=/some/path/initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img \e
705 \-\-sbat=\*(Aqsbat,1,SBAT Version,sbat,1,https://github\&.com/rhboot/shim/blob/main/SBAT\&.md
706 uki\&.author\&.myimage,1,UKI for System,uki\&.author\&.myimage,1,https://uapi\-group\&.org/specifications/specs/unified_kernel_image/\*(Aq \e
707 \-\-pcr\-private\-key=tpm2\-pcr\-initrd\-private\-key\&.pem \e
708 \-\-pcr\-public\-key=tpm2\-pcr\-initrd\-public\-key\&.pem \e
709 \-\-phases=\*(Aqenter\-initrd\*(Aq \e
710 \-\-pcr\-private\-key=tpm2\-pcr\-private\-key\-system\&.pem \e
711 \-\-pcr\-public\-key=tpm2\-pcr\-public\-key\-system\&.pem \e
712 \-\-phases=\*(Aqenter\-initrd:leave\-initrd enter\-initrd:leave\-initrd:sysinit \e
713 enter\-initrd:leave\-initrd:sysinit:ready\*(Aq \e
714 \-\-pcr\-banks=sha384,sha512 \e
715 \-\-secureboot\-private\-key=secureboot\-private\-key\&.pem \e
716 \-\-secureboot\-certificate=secureboot\-certificate\&.pem \e
717 \-\-sign\-kernel \e
718 \-\-cmdline=\*(Aqquiet rw rhgb\*(Aq
719 .fi
720 .if n \{\
721 .RE
722 .\}
723 .PP
724 This creates a signed UKI
725 \&./vmlinuz\&.signed\&.efi\&. The initrd section contains two concatenated parts,
726 early_cpio
727 and
728 initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img\&. The policy embedded in the
729 "\&.pcrsig"
730 section will be signed for the initrd (the
731 \fBenter\-initrd\fR
732 phase) with the key
733 tpm2\-pcr\-initrd\-private\-key\&.pem, and for the main system (phases
734 \fBleave\-initrd\fR,
735 \fBsysinit\fR,
736 \fBready\fR) with the key
737 tpm2\-pcr\-private\-key\-system\&.pem\&. The Linux binary and the resulting combined image will be signed with the SecureBoot key
738 secureboot\-private\-key\&.pem\&.
739 .PP
740 \fBExample\ \&3.\ \&All the bells and whistles, via a config file\fR
741 .PP
742 This is the same as the previous example, but this time the configuration is stored in a file:
743 .sp
744 .if n \{\
745 .RS 4
746 .\}
747 .nf
748 $ cat ukify\&.conf
749 [UKI]
750 Initrd=early_cpio
751 Cmdline=quiet rw rhgb
752
753 SecureBootPrivateKey=secureboot\-private\-key\&.pem
754 SecureBootCertificate=secureboot\-certificate\&.pem
755 SignKernel=yes
756 PCRBanks=sha384,sha512
757
758 [PCRSignature:initrd]
759 PCRPrivateKey=tpm2\-pcr\-initrd\-private\-key\&.pem
760 PCRPublicKey=tpm2\-pcr\-initrd\-public\-key\&.pem
761 Phases=enter\-initrd
762
763 [PCRSignature:system]
764 PCRPrivateKey=tpm2\-pcr\-private\-key\-system\&.pem
765 PCRPublicKey=tpm2\-pcr\-public\-key\-system\&.pem
766 Phases=enter\-initrd:leave\-initrd
767 enter\-initrd:leave\-initrd:sysinit
768 enter\-initrd:leave\-initrd:sysinit:ready
769
770 $ ukify \-c ukify\&.conf build \e
771 \-\-linux=/lib/modules/6\&.0\&.9\-300\&.fc37\&.x86_64/vmlinuz \e
772 \-\-initrd=/some/path/initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img
773 .fi
774 .if n \{\
775 .RE
776 .\}
777 .PP
778 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\&.
779 .PP
780 \fBExample\ \&4.\ \&Kernel command line PE addon\fR
781 .sp
782 .if n \{\
783 .RS 4
784 .\}
785 .nf
786 ukify build \e
787 \-\-secureboot\-private\-key=secureboot\-private\-key\&.pem \e
788 \-\-secureboot\-certificate=secureboot\-certificate\&.pem \e
789 \-\-cmdline=\*(Aqdebug\*(Aq \e
790 \-\-sbat=\*(Aqsbat,1,SBAT Version,sbat,1,https://github\&.com/rhboot/shim/blob/main/SBAT\&.md
791 uki\-addon\&.author,1,UKI Addon for System,uki\-addon\&.author,1,https://www\&.freedesktop\&.org/software/systemd/man/systemd\-stub\&.html\*(Aq
792 \-\-output=debug\&.addon\&.efi
793 .fi
794 .if n \{\
795 .RE
796 .\}
797 .PP
798 This creates a signed PE binary that contains the additional kernel command line parameter
799 "debug"
800 with SBAT metadata referring to the owner of the addon\&.
801 .PP
802 \fBExample\ \&5.\ \&Decide signing policy, and create certificate and keys\fR
803 .PP
804 First, let\*(Aqs create a configuration file that specifies what signatures shall be made:
805 .sp
806 .if n \{\
807 .RS 4
808 .\}
809 .nf
810 # cat >/etc/kernel/uki\&.conf <<EOF
811 [UKI]
812 SecureBootPrivateKey=/etc/kernel/secureboot\-private\-key\&.pem
813 SecureBootCertificate=/etc/kernel/secureboot\-certificate\&.pem
814
815 [PCRSignature:initrd]
816 Phases=enter\-initrd
817 PCRPrivateKey=/etc/systemd/tpm2\-pcr\-initrd\-private\-key\&.pem
818 PCRPublicKey=/etc/systemd/tpm2\-pcr\-initrd\-public\-key\&.pem
819
820 [PCRSignature:system]
821 Phases=enter\-initrd:leave\-initrd enter\-initrd:leave\-initrd:sysinit
822 enter\-initrd:leave\-initrd:sysinit:ready
823 PCRPrivateKey=/etc/systemd/tpm2\-pcr\-private\-key\-system\&.pem
824 PCRPublicKey=/etc/systemd/tpm2\-pcr\-public\-key\-system\&.pem
825 EOF
826 .fi
827 .if n \{\
828 .RE
829 .\}
830 .PP
831 Next, we can generate the certificate and keys:
832 .sp
833 .if n \{\
834 .RS 4
835 .\}
836 .nf
837 # ukify genkey \-\-config=/etc/kernel/uki\&.conf
838 Writing SecureBoot private key to /etc/kernel/secureboot\-private\-key\&.pem
839 Writing SecureBoot certificate to /etc/kernel/secureboot\-certificate\&.pem
840 Writing private key for PCR signing to /etc/systemd/tpm2\-pcr\-initrd\-private\-key\&.pem
841 Writing public key for PCR signing to /etc/systemd/tpm2\-pcr\-initrd\-public\-key\&.pem
842 Writing private key for PCR signing to /etc/systemd/tpm2\-pcr\-private\-key\-system\&.pem
843 Writing public key for PCR signing to /etc/systemd/tpm2\-pcr\-public\-key\-system\&.pem
844 .fi
845 .if n \{\
846 .RE
847 .\}
848 .PP
849 (Both operations need to be done as root to allow write access to
850 /etc/kernel/\&.)
851 .PP
852 Subsequent invocations using the config file (\fBukify build \-\-config=/etc/kernel/uki\&.conf\fR) will use this certificate and key files\&. Note that the
853 \fBkernel-install\fR(8)
854 plugin
855 60\-ukify\&.install
856 uses
857 /etc/kernel/uki\&.conf
858 by default, so after this file has been created, installations of kernels that create a UKI on the local machine using
859 \fBkernel\-install\fR
860 will perform signing using this config\&.
861 .PP
862 \fBExample\ \&6.\ \&Multi\-Profile UKI\fR
863 .PP
864 First, create a few profiles:
865 .sp
866 .if n \{\
867 .RS 4
868 .\}
869 .nf
870 $ ukify build \e
871 \-\-profile=\*(AqTITLE=Base\*(Aq \e
872 \-\-output=profile0\&.efi
873 .fi
874 .if n \{\
875 .RE
876 .\}
877 .PP
878 Add a second profile (@1):
879 .sp
880 .if n \{\
881 .RS 4
882 .\}
883 .nf
884 $ ukify build \e
885 \-\-profile=\*(AqTITLE=Boot into Storage Target Mode
886 ID=storagetm\*(Aq \e
887 \-\-cmdline=\*(Aqquiet rw rd\&.systemd\&.unit=storage\-target\-mode\&.target\*(Aq \e
888 \-\-output=profile1\&.efi
889 .fi
890 .if n \{\
891 .RE
892 .\}
893 .PP
894 Add a third profile (@2):
895 .sp
896 .if n \{\
897 .RS 4
898 .\}
899 .nf
900 $ ukify build \e
901 \-\-profile=\*(AqTITLE=Factory Reset
902 ID=factory\-reset\*(Aq \e
903 \-\-cmdline=\*(Aqquiet rw systemd\&.unit=factory\-reset\&.target\*(Aq \e
904 \-\-output=profile2\&.efi
905 .fi
906 .if n \{\
907 .RE
908 .\}
909 .PP
910 Then, create a UKI and include all the generated profiles:
911 .sp
912 .if n \{\
913 .RS 4
914 .\}
915 .nf
916 $ ukify build \e
917 \-\-linux=/lib/modules/6\&.0\&.9\-300\&.fc37\&.x86_64/vmlinuz \e
918 \-\-initrd=/some/path/initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img \e
919 \-\-cmdline=\*(Aqquiet rw\*(Aq \e
920 \-\-join\-profile=profile0\&.efi \e
921 \-\-join\-profile=profile1\&.efi \e
922 \-\-join\-profile=profile2\&.efi \e
923 \-\-output=base\&.efi
924 .fi
925 .if n \{\
926 .RE
927 .\}
928 .PP
929 The resulting UKI
930 base\-with\-profile\-0\-1\-2\&.efi
931 will now contain three profiles\&.
932 .PP
933 \fBExample\ \&7.\ \&Offline signing of pcrsig section\fR
934 .PP
935 First, create a UKI and save the PCR JSON blob:
936 .sp
937 .if n \{\
938 .RS 4
939 .\}
940 .nf
941 $ ukify build \e
942 \-\-linux=/lib/modules/6\&.0\&.9\-300\&.fc37\&.x86_64/vmlinuz \e
943 \-\-initrd=/some/path/initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img \e
944 \-\-cmdline=\*(Aqquiet rw\*(Aq \e
945 \-\-pcr\-public\-key=tpm2\-pcr\-initrd\-public\-key\&.pem \e
946 \-\-policy\-digest \e
947 \-\-json=short \e
948 \-\-output=base\&.efi >base\&.pcrs
949 .fi
950 .if n \{\
951 .RE
952 .\}
953 .PP
954 Then, sign the PCR digests offline and insert them in the JSON blob:
955 .sp
956 .if n \{\
957 .RS 4
958 .\}
959 .nf
960 #!/usr/bin/python3
961 import base64, json, subprocess
962
963 priv_key = \*(Aq/home/zbyszek/src/systemd/tpm2\-pcr\-private\&.pem\*(Aq
964 base_file = \*(Aqbase\&.pcrs\*(Aq
965
966 base = json\&.load(open(base_file))
967
968 for bank,policies in base\&.items():
969 for policy in policies:
970 pol = base64\&.b16decode(policy[\*(Aqpol\*(Aq]\&.upper())
971 call = subprocess\&.run([\*(Aqopenssl\*(Aq, \*(Aqdgst\*(Aq, f\*(Aq\-{bank}\*(Aq, \*(Aq\-sign\*(Aq, priv_key],
972 input=pol,
973 check=True,
974 capture_output=True)
975 sig = base64\&.b64encode(call\&.stdout)\&.decode()
976 policy[\*(Aqsig\*(Aq] = sig
977
978 print(json\&.dumps(base))
979 .fi
980 .if n \{\
981 .RE
982 .\}
983 .PP
984 Finally, attach the updated JSON blob to the UKI:
985 .sp
986 .if n \{\
987 .RS 4
988 .\}
989 .nf
990 $ ukify build \e
991 \-\-join\-pcrsig=base\&.efi \e
992 \-\-pcrsig=@base\&.pcrs \e
993 \-\-json=short \e
994 \-\-output=base\-signed\&.efi
995 .fi
996 .if n \{\
997 .RE
998 .\}
999 .PP
1000 The resulting UKI
1001 base\-signed\&.efi
1002 will now contain the signed PCR digests\&.
1003 .SH "SEE ALSO"
1004 .PP
1005 \fBsystemd\fR(1), \fBsystemd-stub\fR(7), \fBsystemd-boot\fR(7), \fBsystemd-measure\fR(1), \fBsystemd-pcrphase.service\fR(8)
1006 .SH "NOTES"
1007 .IP " 1." 4
1008 Unified Kernel Image (UKI)
1009 .RS 4
1010 \%https://uapi-group.org/specifications/specs/unified_kernel_image/
1011 .RE
1012 .IP " 2." 4
1013 Shim documentation
1014 .RS 4
1015 \%https://github.com/rhboot/shim/blob/main/SBAT.md
1016 .RE