]>
Commit | Line | Data |
---|---|---|
0fdf4e18 ZJS |
1 | <?xml version="1.0"?> |
2 | <!--*-nxml-*--> | |
3 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
4 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | |
5 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> | |
9c45bfb2 | 6 | <refentry id="ukify" xmlns:xi="http://www.w3.org/2001/XInclude" conditional='ENABLE_UKIFY'> |
0fdf4e18 ZJS |
7 | |
8 | <refentryinfo> | |
9 | <title>ukify</title> | |
10 | <productname>systemd</productname> | |
11 | </refentryinfo> | |
12 | ||
13 | <refmeta> | |
14 | <refentrytitle>ukify</refentrytitle> | |
15 | <manvolnum>1</manvolnum> | |
16 | </refmeta> | |
17 | ||
18 | <refnamediv> | |
19 | <refname>ukify</refname> | |
00e5933f | 20 | <refpurpose>Combine components into a signed Unified Kernel Image for UEFI systems</refpurpose> |
0fdf4e18 ZJS |
21 | </refnamediv> |
22 | ||
23 | <refsynopsisdiv> | |
24 | <cmdsynopsis> | |
f65aa477 | 25 | <command>ukify</command> |
0fdf4e18 | 26 | <arg choice="opt" rep="repeat">OPTIONS</arg> |
a3b227d2 | 27 | <arg choice="plain">build</arg> |
d3f8b754 ZJS |
28 | </cmdsynopsis> |
29 | ||
30 | <cmdsynopsis> | |
31 | <command>ukify</command> | |
32 | <arg choice="opt" rep="repeat">OPTIONS</arg> | |
a1c80efd | 33 | <arg choice="plain">genkey</arg> |
0fdf4e18 | 34 | </cmdsynopsis> |
d3f8b754 ZJS |
35 | |
36 | <cmdsynopsis> | |
37 | <command>ukify</command> | |
38 | <arg choice="opt" rep="repeat">OPTIONS</arg> | |
39 | <arg choice="plain">inspect</arg> | |
40 | <arg choice="plain" rep="repeat">FILE</arg> | |
41 | </cmdsynopsis> | |
0fdf4e18 ZJS |
42 | </refsynopsisdiv> |
43 | ||
44 | <refsect1> | |
45 | <title>Description</title> | |
46 | ||
a3f758b3 ZJS |
47 | <para><command>ukify</command> is a tool whose primary purpose is to combine components (usually a |
48 | kernel, an initrd, and a UEFI boot stub) to create a | |
0fdf4e18 ZJS |
49 | <ulink url="https://uapi-group.org/specifications/specs/unified_kernel_image/">Unified Kernel Image (UKI)</ulink> |
50 | — a PE binary that can be executed by the firmware to start the embedded linux kernel. | |
51 | See <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> | |
52 | for details about the stub.</para> | |
a3f758b3 | 53 | </refsect1> |
0fdf4e18 | 54 | |
a3f758b3 ZJS |
55 | <refsect1> |
56 | <title>Commands</title> | |
57 | ||
58 | <para>The following commands are understood:</para> | |
59 | ||
60 | <refsect2> | |
61 | <title><command>build</command></title> | |
62 | ||
63 | <para>This command creates a Unified Kernel Image. The two primary options that should be specified for | |
64 | the <command>build</command> verb are <varname>Linux=</varname>/<option>--linux=</option>, and | |
65 | <varname>Initrd=</varname>/<option>--initrd=</option>. <varname>Initrd=</varname> accepts multiple | |
66 | whitespace-separated paths and <option>--initrd=</option> can be specified multiple times.</para> | |
67 | ||
68 | <para>Additional sections will be inserted into the UKI, either automatically or only if a specific | |
69 | option is provided. See the discussions of | |
70 | <varname>Cmdline=</varname>/<option>--cmdline=</option>, | |
71 | <varname>OSRelease=</varname>/<option>--os-release=</option>, | |
72 | <varname>DeviceTree=</varname>/<option>--devicetree=</option>, | |
73 | <varname>Splash=</varname>/<option>--splash=</option>, | |
74 | <varname>PCRPKey=</varname>/<option>--pcrpkey=</option>, | |
75 | <varname>Uname=</varname>/<option>--uname=</option>, | |
76 | <varname>SBAT=</varname>/<option>--sbat=</option>, | |
77 | and <option>--section=</option> | |
78 | below.</para> | |
79 | ||
80 | <para><command>ukify</command> can also be used to assemble a PE binary that is not executable but | |
81 | contains auxiliary data, for example additional kernel command line entries.</para> | |
82 | ||
83 | <para>If PCR signing keys are provided via the | |
84 | <varname>PCRPrivateKey=</varname>/<option>--pcr-private-key=</option> and | |
85 | <varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option> options, PCR values that will be seen | |
86 | after booting with the given kernel, initrd, and other sections, will be calculated, signed, and embedded | |
87 | in the UKI. | |
88 | <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> is | |
89 | used to perform this calculation and signing.</para> | |
90 | ||
91 | <para>The calculation of PCR values is done for specific boot phase paths. Those can be specified with | |
92 | the <varname>Phases=</varname>/<option>--phases=</option> option. If not specified, the default provided | |
93 | by <command>systemd-measure</command> is used. It is also possible to specify the | |
94 | <varname>PCRPrivateKey=</varname>/<option>--pcr-private-key=</option>, | |
95 | <varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option>, and | |
96 | <varname>Phases=</varname>/<option>--phases=</option> arguments more than once. Signatures will then be | |
97 | performed with each of the specified keys. On the command line, when both <option>--phases=</option> and | |
98 | <option>--pcr-private-key=</option> are used, they must be specified the same number of times, and then | |
99 | the n-th boot phase path set will be signed by the n-th key. This can be used to build different trust | |
100 | policies for different phases of the boot. In the config file, <varname>PCRPrivateKey=</varname>, | |
101 | <varname>PCRPublicKey=</varname>, and <varname>Phases=</varname> are grouped into separate sections, | |
102 | describing separate boot phases.</para> | |
103 | ||
104 | <para>If a SecureBoot signing key is provided via the | |
105 | <varname>SecureBootPrivateKey=</varname>/<option>--secureboot-private-key=</option> option, the resulting | |
106 | PE binary will be signed as a whole, allowing the resulting UKI to be trusted by SecureBoot. Also see the | |
107 | discussion of automatic enrollment in | |
108 | <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>. | |
109 | </para> | |
c3f7501c LB |
110 | |
111 | <para>If the stub and/or the kernel contain <literal>.sbat</literal> sections they will be merged in | |
112 | the UKI so that revocation updates affecting either are considered when the UKI is loaded by Shim. For | |
113 | more information on SBAT see | |
bf63dadb | 114 | <ulink url="https://github.com/rhboot/shim/blob/main/SBAT.md">Shim documentation</ulink>. |
c3f7501c | 115 | </para> |
a3f758b3 ZJS |
116 | </refsect2> |
117 | ||
118 | <refsect2> | |
119 | <title><command>genkey</command></title> | |
120 | ||
121 | <para>This command creates the keys for PCR signing and the key and certificate used for SecureBoot | |
122 | signing. The same configuration options that determine what keys and in which paths will be needed for | |
123 | signing when <command>build</command> is used, here determine which keys will be created. See the | |
124 | discussion of <varname>PCRPrivateKey=</varname>/<option>--pcr-private-key=</option>, | |
125 | <varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option>, and | |
126 | <varname>SecureBootPrivateKey=</varname>/<option>--secureboot-private-key=</option> below.</para> | |
127 | ||
128 | <para>The output files must not exist.</para> | |
129 | </refsect2> | |
7d481546 EGE |
130 | |
131 | <refsect2> | |
132 | <title><command>inspect</command></title> | |
133 | ||
134 | <para>Display information about the sections in a given binary or binaries. | |
135 | If <option>--all</option> is given, all sections are shown. | |
136 | Otherwise, if <option>--section=</option> option is specified at least once, only those sections are shown. | |
137 | Otherwise, well-known sections that are typically included in an UKI are shown. | |
138 | For each section, its name, size, and sha256-digest is printed. | |
139 | For text sections, the contents are printed.</para> | |
140 | ||
141 | <para>Also see the description of <option>-j</option>/<option>--json=</option> and | |
142 | <option>--section=</option>.</para> | |
ef126bbe ZJS |
143 | |
144 | <para>Other tools that may be useful for inspect UKIs: | |
145 | <citerefentry project='man-pages'><refentrytitle>llvm-objdump</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
146 | <option>-p</option> and <command>pe-inspect</command>. | |
147 | <!-- TODO: add link to pe-inspect man page when it gets one --> | |
148 | </para> | |
7d481546 | 149 | </refsect2> |
0fdf4e18 ZJS |
150 | </refsect1> |
151 | ||
152 | <refsect1> | |
248be6ef ZJS |
153 | <title>Configuration settings</title> |
154 | ||
155 | <para>Settings can appear in configuration files (the syntax with <varname | |
156 | index='false'>SomeSetting=<replaceable>value</replaceable></varname>) and on the command line (the syntax | |
157 | with <option index='false'>--some-setting=<replaceable>value</replaceable></option>). For some command | |
158 | line parameters, a single-letter shortcut is also allowed. In the configuration files, the setting must | |
159 | be in the appropriate section, so the descriptions are grouped by section below. When the same setting | |
160 | appears in the configuration file and on the command line, generally the command line setting has higher | |
161 | priority and overwrites the config file setting completely. If some setting behaves differently, this is | |
162 | described below.</para> | |
163 | ||
a05fa30f AA |
164 | <para>If no config file is provided via the option <option>--config=<replaceable>PATH</replaceable></option>, |
165 | <command>ukify</command> will try to look for a default configuration file in the following paths in this | |
166 | order: <filename>/run/systemd/ukify.conf</filename>, <filename>/etc/systemd/ukify.conf</filename>, | |
167 | <filename>/usr/local/lib/systemd/ukify.conf</filename>, and <filename>/usr/lib/systemd/ukify.conf</filename>, | |
168 | and then load the first one found. <command>ukify</command> will proceed normally if no configuration file | |
169 | is specified and no default one is found.</para> | |
170 | ||
248be6ef ZJS |
171 | <para>The <replaceable>LINUX</replaceable> and <replaceable>INITRD</replaceable> positional arguments, or |
172 | the equivalent <varname>Linux=</varname> and <varname>Initrd=</varname> settings, are optional. If more | |
173 | than one initrd is specified, they will all be combined into a single PE section. This is useful to, for | |
174 | example, prepend microcode before the actual initrd.</para> | |
175 | ||
176 | <para>The following options and settings are understood:</para> | |
177 | ||
178 | <refsect2> | |
7c52d523 | 179 | <title>Command line-only options</title> |
248be6ef ZJS |
180 | |
181 | <variablelist> | |
182 | <varlistentry> | |
183 | <term><option>--config=<replaceable>PATH</replaceable></option></term> | |
184 | ||
185 | <listitem><para>Load configuration from the given config file. In general, settings specified in | |
186 | the config file have lower precedence than the settings specified via options. In cases where the | |
7c52d523 | 187 | command line option does not fully override the config file setting are explicitly mentioned in the |
ec07c3c8 AK |
188 | descriptions of individual options.</para> |
189 | ||
190 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
248be6ef ZJS |
191 | </varlistentry> |
192 | ||
193 | <varlistentry> | |
194 | <term><option>--measure</option></term> | |
195 | <term><option>--no-measure</option></term> | |
196 | ||
8fb35004 ZJS |
197 | <listitem><para>Enable or disable a call to |
198 | <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
aefdc112 AK |
199 | to print pre-calculated PCR values. Defaults to false.</para> |
200 | ||
201 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
202 | </varlistentry> |
203 | ||
204 | <varlistentry> | |
205 | <term><option>--section=<replaceable>NAME</replaceable>:<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term> | |
7d481546 EGE |
206 | <term><option>--section=<replaceable>NAME</replaceable>:<arg choice="plain">text|binary</arg><optional>@<replaceable>PATH</replaceable></optional></option></term> |
207 | ||
208 | <listitem><para>For all verbs except <command>inspect</command>, the first syntax is used. | |
209 | Specify an arbitrary additional section <literal><replaceable>NAME</replaceable></literal>. | |
210 | The argument may be a literal string, or <literal>@</literal> followed by a path name. | |
211 | This option may be specified more than once. Any sections specified in this fashion will be | |
212 | inserted (in order) before the <literal>.linux</literal> section which is always last.</para> | |
213 | ||
214 | <para>For the <command>inspect</command> verb, the second syntax is used. | |
215 | The section <replaceable>NAME</replaceable> will be inspected (if found). | |
216 | If the second argument is <literal>text</literal>, the contents will be printed. | |
217 | If the third argument is given, the contents will be saved to file <replaceable>PATH</replaceable>. | |
218 | </para> | |
219 | ||
220 | <para>Note that the name is used as-is, and if the section name should start with a dot, it must be | |
221 | included in <replaceable>NAME</replaceable>.</para> | |
ec07c3c8 | 222 | |
aefdc112 | 223 | <xi:include href="version-info.xml" xpointer="v253"/> |
7d481546 | 224 | </listitem> |
248be6ef ZJS |
225 | </varlistentry> |
226 | ||
227 | <varlistentry> | |
228 | <term><option>--tools=<replaceable>DIRS</replaceable></option></term> | |
229 | ||
230 | <listitem><para>Specify one or more directories with helper tools. <command>ukify</command> will | |
231 | look for helper tools in those directories first, and if not found, try to load them from | |
aefdc112 AK |
232 | <varname>$PATH</varname> in the usual fashion.</para> |
233 | ||
234 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
235 | </varlistentry> |
236 | ||
237 | <varlistentry> | |
238 | <term><option>--output=<replaceable>FILENAME</replaceable></option></term> | |
239 | ||
240 | <listitem><para>The output filename. If not specified, the name of the | |
241 | <replaceable>LINUX</replaceable> argument, with the suffix <literal>.unsigned.efi</literal> or | |
242 | <literal>.signed.efi</literal> will be used, depending on whether signing for SecureBoot was | |
aefdc112 AK |
243 | performed.</para> |
244 | ||
245 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
246 | </varlistentry> |
247 | ||
248 | <varlistentry> | |
249 | <term><option>--summary</option></term> | |
250 | ||
251 | <listitem><para>Print a summary of loaded config and exit. This is useful to check how the options | |
bf63dadb | 252 | from the configuration file and the command line are combined.</para> |
ec07c3c8 AK |
253 | |
254 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
248be6ef ZJS |
255 | </varlistentry> |
256 | ||
7d481546 EGE |
257 | <varlistentry> |
258 | <term><option>--all</option></term> | |
259 | ||
ec07c3c8 AK |
260 | <listitem><para>Print all sections (with <command>inspect</command> verb).</para> |
261 | ||
262 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
7d481546 EGE |
263 | </varlistentry> |
264 | ||
265 | <varlistentry> | |
266 | <term><option>--json</option></term> | |
267 | ||
ec07c3c8 AK |
268 | <listitem><para>Generate JSON output (with <command>inspect</command> verb).</para> |
269 | ||
270 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
7d481546 EGE |
271 | </varlistentry> |
272 | ||
248be6ef ZJS |
273 | <xi:include href="standard-options.xml" xpointer="help" /> |
274 | <xi:include href="standard-options.xml" xpointer="version" /> | |
275 | </variablelist> | |
276 | </refsect2> | |
277 | ||
278 | <refsect2> | |
279 | <title>[UKI] section</title> | |
280 | ||
281 | <variablelist> | |
282 | <varlistentry> | |
283 | <term><varname>Linux=<replaceable>LINUX</replaceable></varname></term> | |
a3b227d2 | 284 | <term><option>--linux=<replaceable>LINUX</replaceable></option></term> |
248be6ef | 285 | |
ec07c3c8 AK |
286 | <listitem><para>A path to the kernel binary.</para> |
287 | ||
288 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
248be6ef ZJS |
289 | </varlistentry> |
290 | ||
291 | <varlistentry> | |
292 | <term><varname>Initrd=<replaceable>INITRD</replaceable>...</varname></term> | |
a3b227d2 | 293 | <term><option>--initrd=<replaceable>LINUX</replaceable></option></term> |
248be6ef ZJS |
294 | |
295 | <listitem><para>Zero or more initrd paths. In the configuration file, items are separated by | |
296 | whitespace. The initrds are combined in the order of specification, with the initrds specified in | |
ec07c3c8 AK |
297 | the config file first.</para> |
298 | ||
299 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
248be6ef ZJS |
300 | </varlistentry> |
301 | ||
302 | <varlistentry> | |
303 | <term><varname>Cmdline=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term> | |
304 | <term><option>--cmdline=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term> | |
305 | ||
306 | <listitem><para>The kernel command line (the <literal>.cmdline</literal> section). The argument may | |
307 | be a literal string, or <literal>@</literal> followed by a path name. If not specified, no command | |
aefdc112 AK |
308 | line will be embedded.</para> |
309 | ||
310 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
311 | </varlistentry> |
312 | ||
313 | <varlistentry> | |
314 | <term><varname>OSRelease=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term> | |
315 | <term><option>--os-release=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term> | |
316 | ||
317 | <listitem><para>The os-release description (the <literal>.osrel</literal> section). The argument | |
318 | may be a literal string, or <literal>@</literal> followed by a path name. If not specified, the | |
319 | <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file | |
aefdc112 AK |
320 | will be picked up from the host system.</para> |
321 | ||
322 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
323 | </varlistentry> |
324 | ||
325 | <varlistentry> | |
326 | <term><varname>DeviceTree=<replaceable>PATH</replaceable></varname></term> | |
327 | <term><option>--devicetree=<replaceable>PATH</replaceable></option></term> | |
328 | ||
329 | <listitem><para>The devicetree description (the <literal>.dtb</literal> section). The argument is a | |
330 | path to a compiled binary DeviceTree file. If not specified, the section will not be present. | |
aefdc112 AK |
331 | </para> |
332 | ||
333 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
334 | </varlistentry> |
335 | ||
336 | <varlistentry> | |
337 | <term><varname>Splash=<replaceable>PATH</replaceable></varname></term> | |
338 | <term><option>--splash=<replaceable>PATH</replaceable></option></term> | |
339 | ||
340 | <listitem><para>A picture to display during boot (the <literal>.splash</literal> section). The | |
341 | argument is a path to a BMP file. If not specified, the section will not be present. | |
aefdc112 AK |
342 | </para> |
343 | ||
344 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
345 | </varlistentry> |
346 | ||
347 | <varlistentry> | |
348 | <term><varname>PCRPKey=<replaceable>PATH</replaceable></varname></term> | |
349 | <term><option>--pcrpkey=<replaceable>PATH</replaceable></option></term> | |
350 | ||
351 | <listitem><para>A path to a public key to embed in the <literal>.pcrpkey</literal> section. If not | |
352 | specified, and there's exactly one | |
353 | <varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option> argument, that key will be used. | |
aefdc112 AK |
354 | Otherwise, the section will not be present.</para> |
355 | ||
356 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
357 | </varlistentry> |
358 | ||
359 | <varlistentry> | |
360 | <term><varname>Uname=<replaceable>VERSION</replaceable></varname></term> | |
361 | <term><option>--uname=<replaceable>VERSION</replaceable></option></term> | |
362 | ||
363 | <listitem><para>Specify the kernel version (as in <command>uname -r</command>, the | |
364 | <literal>.uname</literal> section). If not specified, an attempt will be made to extract the | |
365 | version string from the kernel image. It is recommended to pass this explicitly if known, because | |
366 | the extraction is based on heuristics and not very reliable. If not specified and extraction fails, | |
aefdc112 AK |
367 | the section will not be present.</para> |
368 | ||
369 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
370 | </varlistentry> |
371 | ||
372 | <varlistentry> | |
373 | <term><varname>PCRBanks=<replaceable>PATH</replaceable></varname></term> | |
374 | <term><option>--pcr-banks=<replaceable>PATH</replaceable></option></term> | |
375 | ||
376 | <listitem><para>A comma or space-separated list of PCR banks to sign a policy for. If not present, | |
377 | all known banks will be used (<literal>sha1</literal>, <literal>sha256</literal>, | |
378 | <literal>sha384</literal>, <literal>sha512</literal>), which will fail if not supported by the | |
aefdc112 AK |
379 | system.</para> |
380 | ||
381 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
382 | </varlistentry> |
383 | ||
c1e8d172 EGE |
384 | <varlistentry> |
385 | <term><varname>SecureBootSigningTool=<replaceable>SIGNER</replaceable></varname></term> | |
386 | <term><option>--signtool=<replaceable>SIGNER</replaceable></option></term> | |
387 | ||
388 | <listitem><para>Whether to use <literal>sbsign</literal> or <literal>pesign</literal>. | |
389 | Depending on this choice, different parameters are required in order to sign an image. | |
ec07c3c8 AK |
390 | Defaults to <literal>sbsign</literal>.</para> |
391 | ||
392 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
c1e8d172 EGE |
393 | </varlistentry> |
394 | ||
248be6ef ZJS |
395 | <varlistentry> |
396 | <term><varname>SecureBootPrivateKey=<replaceable>SB_KEY</replaceable></varname></term> | |
397 | <term><option>--secureboot-private-key=<replaceable>SB_KEY</replaceable></option></term> | |
398 | ||
399 | <listitem><para>A path to a private key to use for signing of the resulting binary. If the | |
400 | <varname>SigningEngine=</varname>/<option>--signing-engine=</option> option is used, this may also be | |
c1e8d172 | 401 | an engine-specific designation. This option is required by |
aefdc112 AK |
402 | <varname>SecureBootSigningTool=sbsign</varname>/<option>--signtool=sbsign</option>. </para> |
403 | ||
404 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
405 | </varlistentry> |
406 | ||
407 | <varlistentry> | |
408 | <term><varname>SecureBootCertificate=<replaceable>SB_CERT</replaceable></varname></term> | |
409 | <term><option>--secureboot-certificate=<replaceable>SB_CERT</replaceable></option></term> | |
410 | ||
411 | <listitem><para>A path to a certificate to use for signing of the resulting binary. If the | |
412 | <varname>SigningEngine=</varname>/<option>--signing-engine=</option> option is used, this may also | |
c1e8d172 | 413 | be an engine-specific designation. This option is required by |
aefdc112 AK |
414 | <varname>SecureBootSigningTool=sbsign</varname>/<option>--signtool=sbsign</option>. </para> |
415 | ||
416 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
c1e8d172 EGE |
417 | </varlistentry> |
418 | ||
419 | <varlistentry> | |
420 | <term><varname>SecureBootCertificateDir=<replaceable>SB_PATH</replaceable></varname></term> | |
421 | <term><option>--secureboot-certificate-dir=<replaceable>SB_PATH</replaceable></option></term> | |
422 | ||
423 | <listitem><para>A path to a nss certificate database directory to use for signing of the resulting binary. | |
424 | Takes effect when <varname>SecureBootSigningTool=pesign</varname>/<option>--signtool=pesign</option> is used. | |
ec07c3c8 AK |
425 | Defaults to <filename>/etc/pki/pesign</filename>.</para> |
426 | ||
427 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
c1e8d172 EGE |
428 | </varlistentry> |
429 | ||
430 | <varlistentry> | |
431 | <term><varname>SecureBootCertificateName=<replaceable>SB_CERTNAME</replaceable></varname></term> | |
432 | <term><option>--secureboot-certificate-name=<replaceable>SB_CERTNAME</replaceable></option></term> | |
433 | ||
434 | <listitem><para>The name of the nss certificate database entry to use for signing of the resulting binary. | |
ec07c3c8 AK |
435 | This option is required by <varname>SecureBootSigningTool=pesign</varname>/<option>--signtool=pesign</option>.</para> |
436 | ||
437 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
248be6ef ZJS |
438 | </varlistentry> |
439 | ||
814e4d7a ZJS |
440 | <varlistentry> |
441 | <term><varname>SecureBootCertificateValidity=<replaceable>DAYS</replaceable></varname></term> | |
442 | <term><option>--secureboot-certificate-validity=<replaceable>DAYS</replaceable></option></term> | |
443 | ||
444 | <listitem><para>Period of validity (in days) for a certificate created by | |
ec07c3c8 AK |
445 | <command>genkey</command>. Defaults to 3650, i.e. 10 years.</para> |
446 | ||
447 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
814e4d7a ZJS |
448 | </varlistentry> |
449 | ||
248be6ef ZJS |
450 | <varlistentry> |
451 | <term><varname>SigningEngine=<replaceable>ENGINE</replaceable></varname></term> | |
452 | <term><option>--signing-engine=<replaceable>ENGINE</replaceable></option></term> | |
453 | ||
8fb35004 | 454 | <listitem><para>An "engine" for signing of the resulting binary. This option is currently passed |
248be6ef ZJS |
455 | verbatim to the <option>--engine=</option> option of |
456 | <citerefentry project='archlinux'><refentrytitle>sbsign</refentrytitle><manvolnum>1</manvolnum></citerefentry>. | |
aefdc112 AK |
457 | </para> |
458 | ||
459 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
460 | </varlistentry> |
461 | ||
462 | <varlistentry> | |
463 | <term><varname>SignKernel=<replaceable>BOOL</replaceable></varname></term> | |
464 | <term><option>--sign-kernel</option></term> | |
465 | <term><option>--no-sign-kernel</option></term> | |
466 | ||
467 | <listitem><para>Override the detection of whether to sign the Linux binary itself before it is | |
468 | embedded in the combined image. If not specified, it will be signed if a SecureBoot signing key is | |
469 | provided via the | |
470 | <varname>SecureBootPrivateKey=</varname>/<option>--secureboot-private-key=</option> option and the | |
471 | binary has not already been signed. If | |
472 | <varname>SignKernel=</varname>/<option>--sign-kernel</option> is true, and the binary has already | |
aefdc112 AK |
473 | been signed, the signature will be appended anyway.</para> |
474 | ||
475 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef | 476 | </varlistentry> |
a8b645de LB |
477 | |
478 | <varlistentry> | |
479 | <term><varname>SBAT=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term> | |
480 | <term><option>--sbat=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term> | |
481 | ||
482 | <listitem><para>SBAT metadata associated with the UKI or addon. SBAT policies are useful to revoke | |
483 | whole groups of UKIs or addons with a single, static policy update that does not take space in | |
484 | DBX/MOKX. If not specified manually, a default metadata entry consisting of | |
485 | <literal>uki,1,UKI,uki,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html</literal> | |
486 | will be used, to ensure it is always possible to revoke UKIs and addons. For more information on | |
bf63dadb | 487 | SBAT see <ulink url="https://github.com/rhboot/shim/blob/main/SBAT.md">Shim documentation</ulink>. |
ec07c3c8 AK |
488 | </para> |
489 | ||
490 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
a8b645de | 491 | </varlistentry> |
248be6ef ZJS |
492 | </variablelist> |
493 | </refsect2> | |
494 | ||
495 | <refsect2> | |
496 | <title>[PCRSignature:<replaceable>NAME</replaceable>] section</title> | |
497 | ||
7c52d523 | 498 | <para>In the config file, those options are grouped by section. On the command line, they |
248be6ef ZJS |
499 | must be specified in the same order. The sections specified in both sources are combined. |
500 | </para> | |
501 | ||
502 | <variablelist> | |
503 | <varlistentry> | |
504 | <term><varname>PCRPrivateKey=<replaceable>PATH</replaceable></varname></term> | |
505 | <term><option>--pcr-private-key=<replaceable>PATH</replaceable></option></term> | |
506 | ||
7c52d523 | 507 | <listitem><para>A private key to use for signing PCR policies. On the command line, this option may |
aefdc112 AK |
508 | be specified more than once, in which case multiple signatures will be made.</para> |
509 | ||
510 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
511 | </varlistentry> |
512 | ||
513 | <varlistentry> | |
514 | <term><varname>PCRPublicKey=<replaceable>PATH</replaceable></varname></term> | |
515 | <term><option>--pcr-public-key=<replaceable>PATH</replaceable></option></term> | |
516 | ||
517 | <listitem><para>A public key to use for signing PCR policies.</para> | |
518 | ||
7c52d523 | 519 | <para>On the command line, this option may be specified more than once, similarly to the |
248be6ef | 520 | <option>--pcr-private-key=</option> option. If not present, the public keys will be extracted from |
bf63dadb ZJS |
521 | the private keys. On the command line, if present, this option must be specified the same number of |
522 | times as the <option>--pcr-private-key=</option> option.</para> | |
aefdc112 AK |
523 | |
524 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
525 | </varlistentry> |
526 | ||
527 | <varlistentry> | |
528 | <term><varname>Phases=<replaceable>LIST</replaceable></varname></term> | |
529 | <term><option>--phases=<replaceable>LIST</replaceable></option></term> | |
530 | ||
531 | <listitem><para>A comma or space-separated list of colon-separated phase paths to sign a policy | |
532 | for. Each set of boot phase paths will be signed with the corresponding private key. If not | |
533 | present, the default of | |
534 | <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
535 | will be used.</para> | |
536 | ||
7c52d523 | 537 | <para>On the command line, when this argument is present, it must appear the same number of times as |
aefdc112 AK |
538 | the <option>--pcr-private-key=</option> option. </para> |
539 | ||
540 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
541 | </varlistentry> |
542 | </variablelist> | |
543 | </refsect2> | |
0fdf4e18 ZJS |
544 | </refsect1> |
545 | ||
546 | <refsect1> | |
547 | <title>Examples</title> | |
548 | ||
549 | <example> | |
550 | <title>Minimal invocation</title> | |
551 | ||
a3b227d2 ZJS |
552 | <programlisting>$ ukify build \ |
553 | --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ | |
554 | --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \ | |
0fdf4e18 ZJS |
555 | --cmdline='quiet rw' |
556 | </programlisting> | |
557 | ||
558 | <para>This creates an unsigned UKI <filename>./vmlinuz.unsigned.efi</filename>.</para> | |
559 | </example> | |
560 | ||
561 | <example> | |
562 | <title>All the bells and whistles</title> | |
563 | ||
f65aa477 | 564 | <programlisting>$ ukify build \ |
a3b227d2 ZJS |
565 | --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ |
566 | --initrd=early_cpio \ | |
567 | --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \ | |
a8b645de LB |
568 | --sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md |
569 | uki.author.myimage,1,UKI for System,uki.author.myimage,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html' \ | |
0fdf4e18 ZJS |
570 | --pcr-private-key=pcr-private-initrd-key.pem \ |
571 | --pcr-public-key=pcr-public-initrd-key.pem \ | |
572 | --phases='enter-initrd' \ | |
573 | --pcr-private-key=pcr-private-system-key.pem \ | |
574 | --pcr-public-key=pcr-public-system-key.pem \ | |
575 | --phases='enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit \ | |
576 | enter-initrd:leave-initrd:sysinit:ready' \ | |
577 | --pcr-banks=sha384,sha512 \ | |
578 | --secureboot-private-key=sb.key \ | |
579 | --secureboot-certificate=sb.cert \ | |
580 | --sign-kernel \ | |
581 | --cmdline='quiet rw rhgb' | |
582 | </programlisting> | |
583 | ||
584 | <para>This creates a signed UKI <filename index='false'>./vmlinuz.signed.efi</filename>. | |
54c84c8a ZJS |
585 | The initrd section contains two concatenated parts, <filename index='false'>early_cpio</filename> |
586 | and <filename index='false'>initramfs-6.0.9-300.fc37.x86_64.img</filename>. | |
0fdf4e18 ZJS |
587 | The policy embedded in the <literal>.pcrsig</literal> section will be signed for the initrd (the |
588 | <constant>enter-initrd</constant> phase) with the key | |
589 | <filename index='false'>pcr-private-initrd-key.pem</filename>, and for the main system (phases | |
590 | <constant>leave-initrd</constant>, <constant>sysinit</constant>, <constant>ready</constant>) with the | |
591 | key <filename index='false'>pcr-private-system-key.pem</filename>. The Linux binary and the resulting | |
592 | combined image will be signed with the SecureBoot key <filename index='false'>sb.key</filename>.</para> | |
593 | </example> | |
00e5933f | 594 | |
248be6ef ZJS |
595 | <example> |
596 | <title>All the bells and whistles, via a config file</title> | |
597 | ||
598 | <para>This is the same as the previous example, but this time the configuration is stored in a | |
599 | file:</para> | |
600 | ||
601 | <programlisting>$ cat ukify.conf | |
602 | [UKI] | |
603 | Initrd=early_cpio | |
604 | Cmdline=quiet rw rhgb | |
605 | ||
606 | SecureBootPrivateKey=sb.key | |
c766e05f | 607 | SecureBootCertificate=sb.cert |
248be6ef ZJS |
608 | SignKernel=yes |
609 | PCRBanks=sha384,sha512 | |
610 | ||
611 | [PCRSignature:initrd] | |
612 | PCRPrivateKey=pcr-private-initrd-key.pem | |
613 | PCRPublicKey=pcr-public-initrd-key.pem | |
614 | Phases=enter-initrd | |
615 | ||
616 | [PCRSignature:system] | |
617 | PCRPrivateKey=pcr-private-system-key.pem | |
618 | PCRPublicKey=pcr-public-system-key.pem | |
619 | Phases=enter-initrd:leave-initrd | |
620 | enter-initrd:leave-initrd:sysinit | |
621 | enter-initrd:leave-initrd:sysinit:ready | |
622 | ||
f65aa477 | 623 | $ ukify -c ukify.conf build \ |
a3b227d2 ZJS |
624 | --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ |
625 | --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img | |
248be6ef ZJS |
626 | </programlisting> |
627 | ||
628 | <para>One "initrd" (<filename index='false'>early_cpio</filename>) is specified in the config file, and | |
629 | the other initrd (<filename index='false'>initramfs-6.0.9-300.fc37.x86_64.img</filename>) is specified | |
7c52d523 | 630 | on the command line. This may be useful for example when the first initrd contains microcode for the CPU |
248be6ef ZJS |
631 | and does not need to be updated when the kernel version changes, unlike the actual initrd.</para> |
632 | </example> | |
633 | ||
00e5933f LB |
634 | <example> |
635 | <title>Kernel command line auxiliary PE</title> | |
636 | ||
a3b227d2 | 637 | <programlisting>ukify build \ |
00e5933f LB |
638 | --secureboot-private-key=sb.key \ |
639 | --secureboot-certificate=sb.cert \ | |
640 | --cmdline='debug' \ | |
c67d5a02 LB |
641 | --sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md |
642 | uki.addon.author,1,UKI Addon for System,uki.addon.author,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html' | |
e673c5c2 | 643 | --output=debug.cmdline |
00e5933f LB |
644 | </programlisting> |
645 | ||
248be6ef | 646 | <para>This creates a signed PE binary that contains the additional kernel command line parameter |
c67d5a02 | 647 | <literal>debug</literal> with SBAT metadata referring to the owner of the addon.</para> |
00e5933f | 648 | </example> |
27140fc7 ZJS |
649 | |
650 | <example> | |
651 | <title>Decide signing policy and create certificate and keys</title> | |
652 | ||
653 | <para>First, let's create an config file that specifies what signatures shall be made:</para> | |
654 | ||
655 | <programlisting># cat >/etc/kernel/uki.conf <<EOF | |
656 | <xi:include href="uki.conf.example" parse="text" />EOF</programlisting> | |
657 | ||
658 | <para>Next, we can generate the certificate and keys:</para> | |
f65aa477 | 659 | <programlisting># ukify genkey --config=/etc/kernel/uki.conf |
27140fc7 | 660 | Writing SecureBoot private key to /etc/kernel/secure-boot.key.pem |
9a27ef09 | 661 | Writing SecureBoot certificate to /etc/kernel/secure-boot.cert.pem |
27140fc7 ZJS |
662 | Writing private key for PCR signing to /etc/kernel/pcr-initrd.key.pem |
663 | Writing public key for PCR signing to /etc/kernel/pcr-initrd.pub.pem | |
664 | Writing private key for PCR signing to /etc/kernel/pcr-system.key.pem | |
665 | Writing public key for PCR signing to /etc/kernel/pcr-system.pub.pem | |
666 | </programlisting> | |
667 | ||
668 | <para>(Both operations need to be done as root to allow write access | |
669 | to <filename>/etc/kernel/</filename>.)</para> | |
670 | ||
bf63dadb | 671 | <para>Subsequent invocations using the config file |
f65aa477 | 672 | (<command>ukify build --config=/etc/kernel/uki.conf</command>) |
27140fc7 ZJS |
673 | will use this certificate and key files. Note that the |
674 | <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
675 | plugin <filename>60-ukify.install</filename> uses <filename>/etc/kernel/uki.conf</filename> | |
676 | by default, so after this file has been created, installations of kernels that create a UKI on the | |
bf63dadb | 677 | local machine using <command>kernel-install</command> will perform signing using this config.</para> |
27140fc7 | 678 | </example> |
0fdf4e18 ZJS |
679 | </refsect1> |
680 | ||
681 | <refsect1> | |
682 | <title>See Also</title> | |
683 | <para> | |
684 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
685 | <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>, | |
686 | <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, | |
248be6ef | 687 | <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
9e60dc0d | 688 | <citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
0fdf4e18 ZJS |
689 | </para> |
690 | </refsect1> | |
691 | ||
692 | </refentry> |