]>
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 | ||
b6570095 LP |
231 | <varlistentry> |
232 | <term><option>--extend=<replaceable>PATH</replaceable></option></term> | |
233 | ||
234 | <listitem><para>Takes a path to an existing PE file to import into the newly generated PE file. If | |
235 | this option is used all UKI PE sections of the specified PE file are copied into the target PE file | |
236 | before any new PE sections are appended. This is useful for generating multi-profile UKIs. Note | |
237 | that this only copies PE sections that are defined by the UKI specification, and ignores any other, | |
238 | for example <literal>.text</literal> or similar.</para> | |
239 | ||
bc3e2c5a LP |
240 | <xi:include href="version-info.xml" xpointer="v257"/></listitem> |
241 | </varlistentry> | |
242 | ||
243 | <varlistentry> | |
244 | <term><option>--measure-base=<replaceable>PATH</replaceable></option></term> | |
245 | ||
246 | <listitem><para>Takes a path to an existing PE file to use as base profile, for measuring | |
247 | multi-profile UKIs. When calculating the PCR values, this has the effect that the sections | |
248 | specified on the command line are combined with any sections from the PE file specified here (up to | |
249 | the first <literal>.profile</literal> section, and only if not already specified on the command | |
250 | line). Typically, this is used together with <option>--extend=</option> to both import and use as | |
251 | measurement base an existing UKI.</para> | |
252 | ||
b6570095 LP |
253 | <xi:include href="version-info.xml" xpointer="v257"/></listitem> |
254 | </varlistentry> | |
255 | ||
248be6ef ZJS |
256 | <varlistentry> |
257 | <term><option>--tools=<replaceable>DIRS</replaceable></option></term> | |
258 | ||
259 | <listitem><para>Specify one or more directories with helper tools. <command>ukify</command> will | |
260 | look for helper tools in those directories first, and if not found, try to load them from | |
aefdc112 AK |
261 | <varname>$PATH</varname> in the usual fashion.</para> |
262 | ||
263 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
264 | </varlistentry> |
265 | ||
266 | <varlistentry> | |
267 | <term><option>--output=<replaceable>FILENAME</replaceable></option></term> | |
268 | ||
269 | <listitem><para>The output filename. If not specified, the name of the | |
270 | <replaceable>LINUX</replaceable> argument, with the suffix <literal>.unsigned.efi</literal> or | |
271 | <literal>.signed.efi</literal> will be used, depending on whether signing for SecureBoot was | |
aefdc112 AK |
272 | performed.</para> |
273 | ||
274 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
275 | </varlistentry> |
276 | ||
277 | <varlistentry> | |
278 | <term><option>--summary</option></term> | |
279 | ||
280 | <listitem><para>Print a summary of loaded config and exit. This is useful to check how the options | |
bf63dadb | 281 | from the configuration file and the command line are combined.</para> |
ec07c3c8 AK |
282 | |
283 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
248be6ef ZJS |
284 | </varlistentry> |
285 | ||
7d481546 EGE |
286 | <varlistentry> |
287 | <term><option>--all</option></term> | |
288 | ||
ec07c3c8 AK |
289 | <listitem><para>Print all sections (with <command>inspect</command> verb).</para> |
290 | ||
291 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
7d481546 EGE |
292 | </varlistentry> |
293 | ||
294 | <varlistentry> | |
295 | <term><option>--json</option></term> | |
296 | ||
ec07c3c8 AK |
297 | <listitem><para>Generate JSON output (with <command>inspect</command> verb).</para> |
298 | ||
299 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
7d481546 EGE |
300 | </varlistentry> |
301 | ||
248be6ef ZJS |
302 | <xi:include href="standard-options.xml" xpointer="help" /> |
303 | <xi:include href="standard-options.xml" xpointer="version" /> | |
304 | </variablelist> | |
305 | </refsect2> | |
306 | ||
307 | <refsect2> | |
308 | <title>[UKI] section</title> | |
309 | ||
310 | <variablelist> | |
311 | <varlistentry> | |
312 | <term><varname>Linux=<replaceable>LINUX</replaceable></varname></term> | |
a3b227d2 | 313 | <term><option>--linux=<replaceable>LINUX</replaceable></option></term> |
248be6ef | 314 | |
ec07c3c8 AK |
315 | <listitem><para>A path to the kernel binary.</para> |
316 | ||
317 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
248be6ef ZJS |
318 | </varlistentry> |
319 | ||
89ed3445 LP |
320 | <varlistentry> |
321 | <term><varname>OSRelease=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term> | |
322 | <term><option>--os-release=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term> | |
323 | ||
324 | <listitem><para>The os-release description (the <literal>.osrel</literal> section). The argument | |
325 | may be a literal string, or <literal>@</literal> followed by a path name. If not specified, the | |
326 | <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file | |
327 | will be picked up from the host system.</para> | |
328 | ||
329 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
330 | </varlistentry> | |
331 | ||
332 | <varlistentry> | |
333 | <term><varname>Cmdline=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term> | |
334 | <term><option>--cmdline=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term> | |
335 | ||
336 | <listitem><para>The kernel command line (the <literal>.cmdline</literal> section). The argument may | |
337 | be a literal string, or <literal>@</literal> followed by a path name. If not specified, no command | |
338 | line will be embedded.</para> | |
339 | ||
340 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
341 | </varlistentry> | |
342 | ||
248be6ef ZJS |
343 | <varlistentry> |
344 | <term><varname>Initrd=<replaceable>INITRD</replaceable>...</varname></term> | |
a3b227d2 | 345 | <term><option>--initrd=<replaceable>LINUX</replaceable></option></term> |
248be6ef ZJS |
346 | |
347 | <listitem><para>Zero or more initrd paths. In the configuration file, items are separated by | |
348 | whitespace. The initrds are combined in the order of specification, with the initrds specified in | |
ec07c3c8 AK |
349 | the config file first.</para> |
350 | ||
351 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
248be6ef ZJS |
352 | </varlistentry> |
353 | ||
d380337d TF |
354 | <varlistentry> |
355 | <term><varname>Microcode=<replaceable>UCODE</replaceable></varname></term> | |
356 | <term><option>--microcode=<replaceable>UCODE</replaceable></option></term> | |
357 | ||
358 | <listitem><para>Path to initrd containing microcode updates. If not specified, the section | |
359 | will not be present.</para> | |
360 | ||
361 | <xi:include href="version-info.xml" xpointer="v256"/></listitem> | |
362 | </varlistentry> | |
363 | ||
248be6ef | 364 | <varlistentry> |
89ed3445 LP |
365 | <term><varname>Splash=<replaceable>PATH</replaceable></varname></term> |
366 | <term><option>--splash=<replaceable>PATH</replaceable></option></term> | |
248be6ef | 367 | |
89ed3445 LP |
368 | <listitem><para>A picture to display during boot (the <literal>.splash</literal> section). The |
369 | argument is a path to a BMP file. If not specified, the section will not be present. | |
370 | </para> | |
aefdc112 AK |
371 | |
372 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
373 | </varlistentry> |
374 | ||
375 | <varlistentry> | |
89ed3445 LP |
376 | <term><varname>DeviceTree=<replaceable>PATH</replaceable></varname></term> |
377 | <term><option>--devicetree=<replaceable>PATH</replaceable></option></term> | |
248be6ef | 378 | |
89ed3445 LP |
379 | <listitem><para>The devicetree description (the <literal>.dtb</literal> section). The argument is a |
380 | path to a compiled binary DeviceTree file. If not specified, the section will not be present. | |
381 | </para> | |
aefdc112 AK |
382 | |
383 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
384 | </varlistentry> |
385 | ||
386 | <varlistentry> | |
89ed3445 LP |
387 | <term><varname>Uname=<replaceable>VERSION</replaceable></varname></term> |
388 | <term><option>--uname=<replaceable>VERSION</replaceable></option></term> | |
248be6ef | 389 | |
89ed3445 LP |
390 | <listitem><para>Specify the kernel version (as in <command>uname -r</command>, the |
391 | <literal>.uname</literal> section). If not specified, an attempt will be made to extract the | |
392 | version string from the kernel image. It is recommended to pass this explicitly if known, because | |
393 | the extraction is based on heuristics and not very reliable. If not specified and extraction fails, | |
394 | the section will not be present.</para> | |
aefdc112 AK |
395 | |
396 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
397 | </varlistentry> |
398 | ||
399 | <varlistentry> | |
89ed3445 LP |
400 | <term><varname>SBAT=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term> |
401 | <term><option>--sbat=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term> | |
248be6ef | 402 | |
89ed3445 LP |
403 | <listitem><para>SBAT metadata associated with the UKI or addon. SBAT policies are useful to revoke |
404 | whole groups of UKIs or addons with a single, static policy update that does not take space in | |
405 | DBX/MOKX. If not specified manually, a default metadata entry consisting of | |
406 | <literal>uki,1,UKI,uki,1,https://uapi-group.org/specifications/specs/unified_kernel_image/</literal> | |
407 | for UKIs and | |
408 | <literal>uki-addon,1,UKI Addon,addon,1,https://www.freedesktop.org/software/systemd/man/latest/systemd-stub.html</literal> | |
409 | for addons will be used, to ensure it is always possible to revoke them. For more information on | |
410 | SBAT see <ulink url="https://github.com/rhboot/shim/blob/main/SBAT.md">Shim documentation</ulink>. | |
aefdc112 AK |
411 | </para> |
412 | ||
89ed3445 | 413 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> |
248be6ef ZJS |
414 | </varlistentry> |
415 | ||
416 | <varlistentry> | |
417 | <term><varname>PCRPKey=<replaceable>PATH</replaceable></varname></term> | |
418 | <term><option>--pcrpkey=<replaceable>PATH</replaceable></option></term> | |
419 | ||
420 | <listitem><para>A path to a public key to embed in the <literal>.pcrpkey</literal> section. If not | |
421 | specified, and there's exactly one | |
422 | <varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option> argument, that key will be used. | |
aefdc112 AK |
423 | Otherwise, the section will not be present.</para> |
424 | ||
425 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
426 | </varlistentry> |
427 | ||
22b8236f LP |
428 | <varlistentry> |
429 | <term><varname>Profile=<replaceable>PATH</replaceable></varname></term> | |
430 | <term><option>--profile=<replaceable>PATH</replaceable></option></term> | |
431 | ||
432 | <listitem><para>A path to a UKI profile to place in an <literal>.profile</literal> section. This | |
433 | option is useful for creating multi-profile UKIs, and is typically used in combination with | |
434 | <option>--extend=</option>, to extend the specified UKI with an additional profile.</para> | |
435 | ||
436 | <xi:include href="version-info.xml" xpointer="v257"/></listitem> | |
437 | </varlistentry> | |
438 | ||
248be6ef ZJS |
439 | <varlistentry> |
440 | <term><varname>PCRBanks=<replaceable>PATH</replaceable></varname></term> | |
441 | <term><option>--pcr-banks=<replaceable>PATH</replaceable></option></term> | |
442 | ||
443 | <listitem><para>A comma or space-separated list of PCR banks to sign a policy for. If not present, | |
444 | all known banks will be used (<literal>sha1</literal>, <literal>sha256</literal>, | |
445 | <literal>sha384</literal>, <literal>sha512</literal>), which will fail if not supported by the | |
aefdc112 AK |
446 | system.</para> |
447 | ||
448 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
449 | </varlistentry> |
450 | ||
c1e8d172 EGE |
451 | <varlistentry> |
452 | <term><varname>SecureBootSigningTool=<replaceable>SIGNER</replaceable></varname></term> | |
453 | <term><option>--signtool=<replaceable>SIGNER</replaceable></option></term> | |
454 | ||
455 | <listitem><para>Whether to use <literal>sbsign</literal> or <literal>pesign</literal>. | |
456 | Depending on this choice, different parameters are required in order to sign an image. | |
ec07c3c8 AK |
457 | Defaults to <literal>sbsign</literal>.</para> |
458 | ||
459 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
c1e8d172 EGE |
460 | </varlistentry> |
461 | ||
248be6ef ZJS |
462 | <varlistentry> |
463 | <term><varname>SecureBootPrivateKey=<replaceable>SB_KEY</replaceable></varname></term> | |
464 | <term><option>--secureboot-private-key=<replaceable>SB_KEY</replaceable></option></term> | |
465 | ||
466 | <listitem><para>A path to a private key to use for signing of the resulting binary. If the | |
467 | <varname>SigningEngine=</varname>/<option>--signing-engine=</option> option is used, this may also be | |
c1e8d172 | 468 | an engine-specific designation. This option is required by |
aefdc112 AK |
469 | <varname>SecureBootSigningTool=sbsign</varname>/<option>--signtool=sbsign</option>. </para> |
470 | ||
471 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
472 | </varlistentry> |
473 | ||
474 | <varlistentry> | |
475 | <term><varname>SecureBootCertificate=<replaceable>SB_CERT</replaceable></varname></term> | |
476 | <term><option>--secureboot-certificate=<replaceable>SB_CERT</replaceable></option></term> | |
477 | ||
478 | <listitem><para>A path to a certificate to use for signing of the resulting binary. If the | |
479 | <varname>SigningEngine=</varname>/<option>--signing-engine=</option> option is used, this may also | |
c1e8d172 | 480 | be an engine-specific designation. This option is required by |
aefdc112 AK |
481 | <varname>SecureBootSigningTool=sbsign</varname>/<option>--signtool=sbsign</option>. </para> |
482 | ||
483 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
c1e8d172 EGE |
484 | </varlistentry> |
485 | ||
486 | <varlistentry> | |
487 | <term><varname>SecureBootCertificateDir=<replaceable>SB_PATH</replaceable></varname></term> | |
488 | <term><option>--secureboot-certificate-dir=<replaceable>SB_PATH</replaceable></option></term> | |
489 | ||
490 | <listitem><para>A path to a nss certificate database directory to use for signing of the resulting binary. | |
491 | Takes effect when <varname>SecureBootSigningTool=pesign</varname>/<option>--signtool=pesign</option> is used. | |
ec07c3c8 AK |
492 | Defaults to <filename>/etc/pki/pesign</filename>.</para> |
493 | ||
494 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
c1e8d172 EGE |
495 | </varlistentry> |
496 | ||
497 | <varlistentry> | |
498 | <term><varname>SecureBootCertificateName=<replaceable>SB_CERTNAME</replaceable></varname></term> | |
499 | <term><option>--secureboot-certificate-name=<replaceable>SB_CERTNAME</replaceable></option></term> | |
500 | ||
501 | <listitem><para>The name of the nss certificate database entry to use for signing of the resulting binary. | |
ec07c3c8 AK |
502 | This option is required by <varname>SecureBootSigningTool=pesign</varname>/<option>--signtool=pesign</option>.</para> |
503 | ||
504 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
248be6ef ZJS |
505 | </varlistentry> |
506 | ||
814e4d7a ZJS |
507 | <varlistentry> |
508 | <term><varname>SecureBootCertificateValidity=<replaceable>DAYS</replaceable></varname></term> | |
509 | <term><option>--secureboot-certificate-validity=<replaceable>DAYS</replaceable></option></term> | |
510 | ||
511 | <listitem><para>Period of validity (in days) for a certificate created by | |
ec07c3c8 AK |
512 | <command>genkey</command>. Defaults to 3650, i.e. 10 years.</para> |
513 | ||
514 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
814e4d7a ZJS |
515 | </varlistentry> |
516 | ||
248be6ef ZJS |
517 | <varlistentry> |
518 | <term><varname>SigningEngine=<replaceable>ENGINE</replaceable></varname></term> | |
519 | <term><option>--signing-engine=<replaceable>ENGINE</replaceable></option></term> | |
520 | ||
8fb35004 | 521 | <listitem><para>An "engine" for signing of the resulting binary. This option is currently passed |
248be6ef ZJS |
522 | verbatim to the <option>--engine=</option> option of |
523 | <citerefentry project='archlinux'><refentrytitle>sbsign</refentrytitle><manvolnum>1</manvolnum></citerefentry>. | |
aefdc112 AK |
524 | </para> |
525 | ||
526 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
527 | </varlistentry> |
528 | ||
529 | <varlistentry> | |
530 | <term><varname>SignKernel=<replaceable>BOOL</replaceable></varname></term> | |
531 | <term><option>--sign-kernel</option></term> | |
532 | <term><option>--no-sign-kernel</option></term> | |
533 | ||
534 | <listitem><para>Override the detection of whether to sign the Linux binary itself before it is | |
535 | embedded in the combined image. If not specified, it will be signed if a SecureBoot signing key is | |
536 | provided via the | |
537 | <varname>SecureBootPrivateKey=</varname>/<option>--secureboot-private-key=</option> option and the | |
538 | binary has not already been signed. If | |
539 | <varname>SignKernel=</varname>/<option>--sign-kernel</option> is true, and the binary has already | |
aefdc112 AK |
540 | been signed, the signature will be appended anyway.</para> |
541 | ||
542 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
543 | </varlistentry> |
544 | </variablelist> | |
545 | </refsect2> | |
546 | ||
547 | <refsect2> | |
548 | <title>[PCRSignature:<replaceable>NAME</replaceable>] section</title> | |
549 | ||
7c52d523 | 550 | <para>In the config file, those options are grouped by section. On the command line, they |
248be6ef ZJS |
551 | must be specified in the same order. The sections specified in both sources are combined. |
552 | </para> | |
553 | ||
554 | <variablelist> | |
555 | <varlistentry> | |
556 | <term><varname>PCRPrivateKey=<replaceable>PATH</replaceable></varname></term> | |
557 | <term><option>--pcr-private-key=<replaceable>PATH</replaceable></option></term> | |
558 | ||
7c52d523 | 559 | <listitem><para>A private key to use for signing PCR policies. On the command line, this option may |
aefdc112 AK |
560 | be specified more than once, in which case multiple signatures will be made.</para> |
561 | ||
562 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
563 | </varlistentry> |
564 | ||
565 | <varlistentry> | |
566 | <term><varname>PCRPublicKey=<replaceable>PATH</replaceable></varname></term> | |
567 | <term><option>--pcr-public-key=<replaceable>PATH</replaceable></option></term> | |
568 | ||
569 | <listitem><para>A public key to use for signing PCR policies.</para> | |
570 | ||
7c52d523 | 571 | <para>On the command line, this option may be specified more than once, similarly to the |
248be6ef | 572 | <option>--pcr-private-key=</option> option. If not present, the public keys will be extracted from |
bf63dadb ZJS |
573 | the private keys. On the command line, if present, this option must be specified the same number of |
574 | times as the <option>--pcr-private-key=</option> option.</para> | |
aefdc112 AK |
575 | |
576 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
577 | </varlistentry> |
578 | ||
579 | <varlistentry> | |
580 | <term><varname>Phases=<replaceable>LIST</replaceable></varname></term> | |
581 | <term><option>--phases=<replaceable>LIST</replaceable></option></term> | |
582 | ||
583 | <listitem><para>A comma or space-separated list of colon-separated phase paths to sign a policy | |
584 | for. Each set of boot phase paths will be signed with the corresponding private key. If not | |
585 | present, the default of | |
586 | <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
587 | will be used.</para> | |
588 | ||
7c52d523 | 589 | <para>On the command line, when this argument is present, it must appear the same number of times as |
aefdc112 AK |
590 | the <option>--pcr-private-key=</option> option. </para> |
591 | ||
592 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
248be6ef ZJS |
593 | </varlistentry> |
594 | </variablelist> | |
595 | </refsect2> | |
0fdf4e18 ZJS |
596 | </refsect1> |
597 | ||
598 | <refsect1> | |
599 | <title>Examples</title> | |
600 | ||
601 | <example> | |
602 | <title>Minimal invocation</title> | |
603 | ||
a3b227d2 ZJS |
604 | <programlisting>$ ukify build \ |
605 | --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ | |
606 | --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \ | |
0fdf4e18 ZJS |
607 | --cmdline='quiet rw' |
608 | </programlisting> | |
609 | ||
610 | <para>This creates an unsigned UKI <filename>./vmlinuz.unsigned.efi</filename>.</para> | |
611 | </example> | |
612 | ||
613 | <example> | |
614 | <title>All the bells and whistles</title> | |
615 | ||
f65aa477 | 616 | <programlisting>$ ukify build \ |
a3b227d2 ZJS |
617 | --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ |
618 | --initrd=early_cpio \ | |
619 | --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \ | |
a8b645de | 620 | --sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md |
121c4eba | 621 | uki.author.myimage,1,UKI for System,uki.author.myimage,1,https://uapi-group.org/specifications/specs/unified_kernel_image/' \ |
dbf5b09d | 622 | --pcr-private-key=tpm2-pcr-private-key-initrd.pem \ |
623 | --pcr-public-key=tpm2-pcr-public-key-initrd.pem \ | |
0fdf4e18 | 624 | --phases='enter-initrd' \ |
dbf5b09d | 625 | --pcr-private-key=tpm2-pcr-private-key-system.pem \ |
626 | --pcr-public-key=tpm2-pcr-public-key-system.pem \ | |
0fdf4e18 ZJS |
627 | --phases='enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit \ |
628 | enter-initrd:leave-initrd:sysinit:ready' \ | |
629 | --pcr-banks=sha384,sha512 \ | |
630 | --secureboot-private-key=sb.key \ | |
631 | --secureboot-certificate=sb.cert \ | |
632 | --sign-kernel \ | |
633 | --cmdline='quiet rw rhgb' | |
634 | </programlisting> | |
635 | ||
636 | <para>This creates a signed UKI <filename index='false'>./vmlinuz.signed.efi</filename>. | |
54c84c8a ZJS |
637 | The initrd section contains two concatenated parts, <filename index='false'>early_cpio</filename> |
638 | and <filename index='false'>initramfs-6.0.9-300.fc37.x86_64.img</filename>. | |
0fdf4e18 ZJS |
639 | The policy embedded in the <literal>.pcrsig</literal> section will be signed for the initrd (the |
640 | <constant>enter-initrd</constant> phase) with the key | |
dbf5b09d | 641 | <filename index='false'>tpm2-pcr-private-key-initrd.pem</filename>, and for the main system (phases |
0fdf4e18 | 642 | <constant>leave-initrd</constant>, <constant>sysinit</constant>, <constant>ready</constant>) with the |
dbf5b09d | 643 | key <filename index='false'>tpm2-pcr-private-key-system.pem</filename>. The Linux binary and the resulting |
0fdf4e18 ZJS |
644 | combined image will be signed with the SecureBoot key <filename index='false'>sb.key</filename>.</para> |
645 | </example> | |
00e5933f | 646 | |
248be6ef ZJS |
647 | <example> |
648 | <title>All the bells and whistles, via a config file</title> | |
649 | ||
650 | <para>This is the same as the previous example, but this time the configuration is stored in a | |
651 | file:</para> | |
652 | ||
653 | <programlisting>$ cat ukify.conf | |
654 | [UKI] | |
655 | Initrd=early_cpio | |
656 | Cmdline=quiet rw rhgb | |
657 | ||
dbf5b09d | 658 | SecureBootPrivateKey=secure-boot-key.pem |
659 | SecureBootCertificate=secure-boot-certificate.pem | |
248be6ef ZJS |
660 | SignKernel=yes |
661 | PCRBanks=sha384,sha512 | |
662 | ||
663 | [PCRSignature:initrd] | |
dbf5b09d | 664 | PCRPrivateKey=tpm2-pcr-private-key-initrd.pem |
665 | PCRPublicKey=tpm2-pcr-public-key-initrd.pem | |
248be6ef ZJS |
666 | Phases=enter-initrd |
667 | ||
668 | [PCRSignature:system] | |
dbf5b09d | 669 | PCRPrivateKey=tpm2-pcr-private-key-system.pem |
670 | PCRPublicKey=tpm2-pcr-public-key-system.pem | |
248be6ef ZJS |
671 | Phases=enter-initrd:leave-initrd |
672 | enter-initrd:leave-initrd:sysinit | |
673 | enter-initrd:leave-initrd:sysinit:ready | |
674 | ||
f65aa477 | 675 | $ ukify -c ukify.conf build \ |
a3b227d2 ZJS |
676 | --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ |
677 | --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img | |
248be6ef ZJS |
678 | </programlisting> |
679 | ||
680 | <para>One "initrd" (<filename index='false'>early_cpio</filename>) is specified in the config file, and | |
681 | the other initrd (<filename index='false'>initramfs-6.0.9-300.fc37.x86_64.img</filename>) is specified | |
7c52d523 | 682 | on the command line. This may be useful for example when the first initrd contains microcode for the CPU |
248be6ef ZJS |
683 | and does not need to be updated when the kernel version changes, unlike the actual initrd.</para> |
684 | </example> | |
685 | ||
00e5933f | 686 | <example> |
40d9c16d | 687 | <title>Kernel command line PE addon</title> |
00e5933f | 688 | |
a3b227d2 | 689 | <programlisting>ukify build \ |
dbf5b09d | 690 | --secureboot-private-key=secure-boot-key.pem \ |
691 | --secureboot-certificate=secure-boot-certificate.pem \ | |
00e5933f | 692 | --cmdline='debug' \ |
c67d5a02 | 693 | --sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md |
121c4eba | 694 | uki-addon.author,1,UKI Addon for System,uki-addon.author,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html' |
40d9c16d | 695 | --output=debug.addon.efi |
00e5933f LB |
696 | </programlisting> |
697 | ||
248be6ef | 698 | <para>This creates a signed PE binary that contains the additional kernel command line parameter |
c67d5a02 | 699 | <literal>debug</literal> with SBAT metadata referring to the owner of the addon.</para> |
00e5933f | 700 | </example> |
27140fc7 ZJS |
701 | |
702 | <example> | |
40d9c16d | 703 | <title>Decide signing policy, and create certificate and keys</title> |
27140fc7 | 704 | |
40d9c16d | 705 | <para>First, let's create a configuration file that specifies what signatures shall be made:</para> |
27140fc7 ZJS |
706 | |
707 | <programlisting># cat >/etc/kernel/uki.conf <<EOF | |
708 | <xi:include href="uki.conf.example" parse="text" />EOF</programlisting> | |
709 | ||
710 | <para>Next, we can generate the certificate and keys:</para> | |
f65aa477 | 711 | <programlisting># ukify genkey --config=/etc/kernel/uki.conf |
dbf5b09d | 712 | Writing SecureBoot private key to /etc/kernel/secure-boot-key.pem |
713 | Writing SecureBoot certificate to /etc/kernel/secure-boot-certificate.pem | |
714 | Writing private key for PCR signing to /etc/systemd/tpm2-pcr-private-key-initrd.pem | |
715 | Writing public key for PCR signing to /etc/systemd/tpm2-pcr-public-key-initrd.pem | |
716 | Writing private key for PCR signing to /etc/systemd/tpm2-pcr-private-key-system.pem | |
717 | Writing public key for PCR signing to /etc/systemd/tpm2-pcr-public-key-system.pem | |
27140fc7 ZJS |
718 | </programlisting> |
719 | ||
720 | <para>(Both operations need to be done as root to allow write access | |
721 | to <filename>/etc/kernel/</filename>.)</para> | |
722 | ||
bf63dadb | 723 | <para>Subsequent invocations using the config file |
f65aa477 | 724 | (<command>ukify build --config=/etc/kernel/uki.conf</command>) |
27140fc7 ZJS |
725 | will use this certificate and key files. Note that the |
726 | <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
727 | plugin <filename>60-ukify.install</filename> uses <filename>/etc/kernel/uki.conf</filename> | |
728 | by default, so after this file has been created, installations of kernels that create a UKI on the | |
bf63dadb | 729 | local machine using <command>kernel-install</command> will perform signing using this config.</para> |
27140fc7 | 730 | </example> |
b6570095 LP |
731 | |
732 | <example> | |
733 | <title>Multi-Profile PE</title> | |
734 | ||
735 | <para>First, create the base UKI:</para> | |
736 | <programlisting>$ ukify build \ | |
737 | --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ | |
738 | --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \ | |
739 | --cmdline='quiet rw' \ | |
740 | --output=base.efi | |
741 | </programlisting> | |
742 | ||
743 | <para>Then, extend the base UKI with information about profile @0:</para> | |
744 | ||
745 | <programlisting>$ ukify build \ | |
746 | --extend=base.efi \ | |
747 | --profile='TITLE=Base' \ | |
748 | --output=base-with-profile-0.efi | |
749 | </programlisting> | |
750 | ||
751 | <para>Add a second profile (@1):</para> | |
752 | ||
753 | <programlisting>$ ukify build \ | |
754 | --extend=base-with-profile-0.efi \ | |
755 | --profile='TITLE=Boot into Storage Target Mode | |
756 | ID=storagetm' \ | |
757 | --cmdline='quiet rw rd.systemd.unit=stroage-target-mode.target' \ | |
758 | --output=base-with-profile-0-1.efi | |
759 | </programlisting> | |
760 | ||
761 | <para>Add a third profile (@2):</para> | |
762 | ||
763 | <programlisting>$ ukify build \ | |
764 | --extend=base-with-profile-0-1.efi \ | |
765 | --profile='TITLE=Factory Reset | |
766 | ID=factory-reset' \ | |
767 | --cmdline='quiet rw systemd.unit=factory-reset.target' \ | |
768 | --output=base-with-profile-0-1-2.efi | |
769 | </programlisting> | |
770 | ||
771 | <para>The resulting UKI <filename>base-with-profile-0-1-2.efi</filename> will now contain three profiles.</para> | |
772 | </example> | |
0fdf4e18 ZJS |
773 | </refsect1> |
774 | ||
775 | <refsect1> | |
776 | <title>See Also</title> | |
13a69c12 DT |
777 | <para><simplelist type="inline"> |
778 | <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
779 | <member><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry></member> | |
780 | <member><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry></member> | |
781 | <member><citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
782 | <member><citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
783 | </simplelist></para> | |
0fdf4e18 ZJS |
784 | </refsect1> |
785 | ||
786 | </refentry> |