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