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