man/ukify.xml

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