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