mirror of
https://github.com/systemd/systemd
synced 2024-09-06 08:46:19 +00:00
693 lines
34 KiB
XML
693 lines
34 KiB
XML
<?xml version="1.0"?>
|
|
<!--*-nxml-*-->
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
|
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
|
<refentry id="ukify" xmlns:xi="http://www.w3.org/2001/XInclude" conditional='ENABLE_UKIFY'>
|
|
|
|
<refentryinfo>
|
|
<title>ukify</title>
|
|
<productname>systemd</productname>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>ukify</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>ukify</refname>
|
|
<refpurpose>Combine components into a signed Unified Kernel Image for UEFI systems</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>ukify</command>
|
|
<arg choice="opt" rep="repeat">OPTIONS</arg>
|
|
<arg choice="plain">build</arg>
|
|
</cmdsynopsis>
|
|
|
|
<cmdsynopsis>
|
|
<command>ukify</command>
|
|
<arg choice="opt" rep="repeat">OPTIONS</arg>
|
|
<arg choice="plain">genkey</arg>
|
|
</cmdsynopsis>
|
|
|
|
<cmdsynopsis>
|
|
<command>ukify</command>
|
|
<arg choice="opt" rep="repeat">OPTIONS</arg>
|
|
<arg choice="plain">inspect</arg>
|
|
<arg choice="plain" rep="repeat">FILE</arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para><command>ukify</command> is a tool whose primary purpose is to combine components (usually a
|
|
kernel, an initrd, and a UEFI boot stub) to create a
|
|
<ulink url="https://uapi-group.org/specifications/specs/unified_kernel_image/">Unified Kernel Image (UKI)</ulink>
|
|
— a PE binary that can be executed by the firmware to start the embedded linux kernel.
|
|
See <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
|
for details about the stub.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Commands</title>
|
|
|
|
<para>The following commands are understood:</para>
|
|
|
|
<refsect2>
|
|
<title><command>build</command></title>
|
|
|
|
<para>This command creates a Unified Kernel Image. The two primary options that should be specified for
|
|
the <command>build</command> verb are <varname>Linux=</varname>/<option>--linux=</option>, and
|
|
<varname>Initrd=</varname>/<option>--initrd=</option>. <varname>Initrd=</varname> accepts multiple
|
|
whitespace-separated paths and <option>--initrd=</option> can be specified multiple times.</para>
|
|
|
|
<para>Additional sections will be inserted into the UKI, either automatically or only if a specific
|
|
option is provided. See the discussions of
|
|
<varname>Cmdline=</varname>/<option>--cmdline=</option>,
|
|
<varname>OSRelease=</varname>/<option>--os-release=</option>,
|
|
<varname>DeviceTree=</varname>/<option>--devicetree=</option>,
|
|
<varname>Splash=</varname>/<option>--splash=</option>,
|
|
<varname>PCRPKey=</varname>/<option>--pcrpkey=</option>,
|
|
<varname>Uname=</varname>/<option>--uname=</option>,
|
|
<varname>SBAT=</varname>/<option>--sbat=</option>,
|
|
and <option>--section=</option>
|
|
below.</para>
|
|
|
|
<para><command>ukify</command> can also be used to assemble a PE binary that is not executable but
|
|
contains auxiliary data, for example additional kernel command line entries.</para>
|
|
|
|
<para>If PCR signing keys are provided via the
|
|
<varname>PCRPrivateKey=</varname>/<option>--pcr-private-key=</option> and
|
|
<varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option> options, PCR values that will be seen
|
|
after booting with the given kernel, initrd, and other sections, will be calculated, signed, and embedded
|
|
in the UKI.
|
|
<citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> is
|
|
used to perform this calculation and signing.</para>
|
|
|
|
<para>The calculation of PCR values is done for specific boot phase paths. Those can be specified with
|
|
the <varname>Phases=</varname>/<option>--phases=</option> option. If not specified, the default provided
|
|
by <command>systemd-measure</command> is used. It is also possible to specify the
|
|
<varname>PCRPrivateKey=</varname>/<option>--pcr-private-key=</option>,
|
|
<varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option>, and
|
|
<varname>Phases=</varname>/<option>--phases=</option> arguments more than once. Signatures will then be
|
|
performed with each of the specified keys. On the command line, when both <option>--phases=</option> and
|
|
<option>--pcr-private-key=</option> are used, they must be specified the same number of times, and then
|
|
the n-th boot phase path set will be signed by the n-th key. This can be used to build different trust
|
|
policies for different phases of the boot. In the config file, <varname>PCRPrivateKey=</varname>,
|
|
<varname>PCRPublicKey=</varname>, and <varname>Phases=</varname> are grouped into separate sections,
|
|
describing separate boot phases.</para>
|
|
|
|
<para>If a SecureBoot signing key is provided via the
|
|
<varname>SecureBootPrivateKey=</varname>/<option>--secureboot-private-key=</option> option, the resulting
|
|
PE binary will be signed as a whole, allowing the resulting UKI to be trusted by SecureBoot. Also see the
|
|
discussion of automatic enrollment in
|
|
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
|
|
</para>
|
|
|
|
<para>If the stub and/or the kernel contain <literal>.sbat</literal> sections they will be merged in
|
|
the UKI so that revocation updates affecting either are considered when the UKI is loaded by Shim. For
|
|
more information on SBAT see
|
|
<ulink url="https://github.com/rhboot/shim/blob/main/SBAT.md">Shim documentation</ulink>.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title><command>genkey</command></title>
|
|
|
|
<para>This command creates the keys for PCR signing and the key and certificate used for SecureBoot
|
|
signing. The same configuration options that determine what keys and in which paths will be needed for
|
|
signing when <command>build</command> is used, here determine which keys will be created. See the
|
|
discussion of <varname>PCRPrivateKey=</varname>/<option>--pcr-private-key=</option>,
|
|
<varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option>, and
|
|
<varname>SecureBootPrivateKey=</varname>/<option>--secureboot-private-key=</option> below.</para>
|
|
|
|
<para>The output files must not exist.</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title><command>inspect</command></title>
|
|
|
|
<para>Display information about the sections in a given binary or binaries.
|
|
If <option>--all</option> is given, all sections are shown.
|
|
Otherwise, if <option>--section=</option> option is specified at least once, only those sections are shown.
|
|
Otherwise, well-known sections that are typically included in an UKI are shown.
|
|
For each section, its name, size, and sha256-digest is printed.
|
|
For text sections, the contents are printed.</para>
|
|
|
|
<para>Also see the description of <option>-j</option>/<option>--json=</option> and
|
|
<option>--section=</option>.</para>
|
|
|
|
<para>Other tools that may be useful for inspect UKIs:
|
|
<citerefentry project='man-pages'><refentrytitle>llvm-objdump</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
<option>-p</option> and <command>pe-inspect</command>.
|
|
<!-- TODO: add link to pe-inspect man page when it gets one -->
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Configuration settings</title>
|
|
|
|
<para>Settings can appear in configuration files (the syntax with <varname
|
|
index='false'>SomeSetting=<replaceable>value</replaceable></varname>) and on the command line (the syntax
|
|
with <option index='false'>--some-setting=<replaceable>value</replaceable></option>). For some command
|
|
line parameters, a single-letter shortcut is also allowed. In the configuration files, the setting must
|
|
be in the appropriate section, so the descriptions are grouped by section below. When the same setting
|
|
appears in the configuration file and on the command line, generally the command line setting has higher
|
|
priority and overwrites the config file setting completely. If some setting behaves differently, this is
|
|
described below.</para>
|
|
|
|
<para>If no config file is provided via the option <option>--config=<replaceable>PATH</replaceable></option>,
|
|
<command>ukify</command> will try to look for a default configuration file in the following paths in this
|
|
order: <filename>/run/systemd/ukify.conf</filename>, <filename>/etc/systemd/ukify.conf</filename>,
|
|
<filename>/usr/local/lib/systemd/ukify.conf</filename>, and <filename>/usr/lib/systemd/ukify.conf</filename>,
|
|
and then load the first one found. <command>ukify</command> will proceed normally if no configuration file
|
|
is specified and no default one is found.</para>
|
|
|
|
<para>The <replaceable>LINUX</replaceable> and <replaceable>INITRD</replaceable> positional arguments, or
|
|
the equivalent <varname>Linux=</varname> and <varname>Initrd=</varname> settings, are optional. If more
|
|
than one initrd is specified, they will all be combined into a single PE section. This is useful to, for
|
|
example, prepend microcode before the actual initrd.</para>
|
|
|
|
<para>The following options and settings are understood:</para>
|
|
|
|
<refsect2>
|
|
<title>Command line-only options</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>--config=<replaceable>PATH</replaceable></option></term>
|
|
|
|
<listitem><para>Load configuration from the given config file. In general, settings specified in
|
|
the config file have lower precedence than the settings specified via options. In cases where the
|
|
command line option does not fully override the config file setting are explicitly mentioned in the
|
|
descriptions of individual options.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--measure</option></term>
|
|
<term><option>--no-measure</option></term>
|
|
|
|
<listitem><para>Enable or disable a call to
|
|
<citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
to print pre-calculated PCR values. Defaults to false.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--section=<replaceable>NAME</replaceable>:<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term>
|
|
<term><option>--section=<replaceable>NAME</replaceable>:text|binary<optional>@<replaceable>PATH</replaceable></optional></option></term>
|
|
|
|
<listitem><para>For all verbs except <command>inspect</command>, the first syntax is used.
|
|
Specify an arbitrary additional section <literal><replaceable>NAME</replaceable></literal>.
|
|
The argument may be a literal string, or <literal>@</literal> followed by a path name.
|
|
This option may be specified more than once. Any sections specified in this fashion will be
|
|
inserted (in order) before the <literal>.linux</literal> section which is always last.</para>
|
|
|
|
<para>For the <command>inspect</command> verb, the second syntax is used.
|
|
The section <replaceable>NAME</replaceable> will be inspected (if found).
|
|
If the second argument is <literal>text</literal>, the contents will be printed.
|
|
If the third argument is given, the contents will be saved to file <replaceable>PATH</replaceable>.
|
|
</para>
|
|
|
|
<para>Note that the name is used as-is, and if the section name should start with a dot, it must be
|
|
included in <replaceable>NAME</replaceable>.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--tools=<replaceable>DIRS</replaceable></option></term>
|
|
|
|
<listitem><para>Specify one or more directories with helper tools. <command>ukify</command> will
|
|
look for helper tools in those directories first, and if not found, try to load them from
|
|
<varname>$PATH</varname> in the usual fashion.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--output=<replaceable>FILENAME</replaceable></option></term>
|
|
|
|
<listitem><para>The output filename. If not specified, the name of the
|
|
<replaceable>LINUX</replaceable> argument, with the suffix <literal>.unsigned.efi</literal> or
|
|
<literal>.signed.efi</literal> will be used, depending on whether signing for SecureBoot was
|
|
performed.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--summary</option></term>
|
|
|
|
<listitem><para>Print a summary of loaded config and exit. This is useful to check how the options
|
|
from the configuration file and the command line are combined.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--all</option></term>
|
|
|
|
<listitem><para>Print all sections (with <command>inspect</command> verb).</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--json</option></term>
|
|
|
|
<listitem><para>Generate JSON output (with <command>inspect</command> verb).</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
|
|
</varlistentry>
|
|
|
|
<xi:include href="standard-options.xml" xpointer="help" />
|
|
<xi:include href="standard-options.xml" xpointer="version" />
|
|
</variablelist>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>[UKI] section</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><varname>Linux=<replaceable>LINUX</replaceable></varname></term>
|
|
<term><option>--linux=<replaceable>LINUX</replaceable></option></term>
|
|
|
|
<listitem><para>A path to the kernel binary.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>Initrd=<replaceable>INITRD</replaceable>...</varname></term>
|
|
<term><option>--initrd=<replaceable>LINUX</replaceable></option></term>
|
|
|
|
<listitem><para>Zero or more initrd paths. In the configuration file, items are separated by
|
|
whitespace. The initrds are combined in the order of specification, with the initrds specified in
|
|
the config file first.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>Cmdline=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term>
|
|
<term><option>--cmdline=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term>
|
|
|
|
<listitem><para>The kernel command line (the <literal>.cmdline</literal> section). The argument may
|
|
be a literal string, or <literal>@</literal> followed by a path name. If not specified, no command
|
|
line will be embedded.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>OSRelease=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term>
|
|
<term><option>--os-release=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term>
|
|
|
|
<listitem><para>The os-release description (the <literal>.osrel</literal> section). The argument
|
|
may be a literal string, or <literal>@</literal> followed by a path name. If not specified, the
|
|
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file
|
|
will be picked up from the host system.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>DeviceTree=<replaceable>PATH</replaceable></varname></term>
|
|
<term><option>--devicetree=<replaceable>PATH</replaceable></option></term>
|
|
|
|
<listitem><para>The devicetree description (the <literal>.dtb</literal> section). The argument is a
|
|
path to a compiled binary DeviceTree file. If not specified, the section will not be present.
|
|
</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>Splash=<replaceable>PATH</replaceable></varname></term>
|
|
<term><option>--splash=<replaceable>PATH</replaceable></option></term>
|
|
|
|
<listitem><para>A picture to display during boot (the <literal>.splash</literal> section). The
|
|
argument is a path to a BMP file. If not specified, the section will not be present.
|
|
</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>PCRPKey=<replaceable>PATH</replaceable></varname></term>
|
|
<term><option>--pcrpkey=<replaceable>PATH</replaceable></option></term>
|
|
|
|
<listitem><para>A path to a public key to embed in the <literal>.pcrpkey</literal> section. If not
|
|
specified, and there's exactly one
|
|
<varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option> argument, that key will be used.
|
|
Otherwise, the section will not be present.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>Uname=<replaceable>VERSION</replaceable></varname></term>
|
|
<term><option>--uname=<replaceable>VERSION</replaceable></option></term>
|
|
|
|
<listitem><para>Specify the kernel version (as in <command>uname -r</command>, the
|
|
<literal>.uname</literal> section). If not specified, an attempt will be made to extract the
|
|
version string from the kernel image. It is recommended to pass this explicitly if known, because
|
|
the extraction is based on heuristics and not very reliable. If not specified and extraction fails,
|
|
the section will not be present.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>PCRBanks=<replaceable>PATH</replaceable></varname></term>
|
|
<term><option>--pcr-banks=<replaceable>PATH</replaceable></option></term>
|
|
|
|
<listitem><para>A comma or space-separated list of PCR banks to sign a policy for. If not present,
|
|
all known banks will be used (<literal>sha1</literal>, <literal>sha256</literal>,
|
|
<literal>sha384</literal>, <literal>sha512</literal>), which will fail if not supported by the
|
|
system.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>SecureBootSigningTool=<replaceable>SIGNER</replaceable></varname></term>
|
|
<term><option>--signtool=<replaceable>SIGNER</replaceable></option></term>
|
|
|
|
<listitem><para>Whether to use <literal>sbsign</literal> or <literal>pesign</literal>.
|
|
Depending on this choice, different parameters are required in order to sign an image.
|
|
Defaults to <literal>sbsign</literal>.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>SecureBootPrivateKey=<replaceable>SB_KEY</replaceable></varname></term>
|
|
<term><option>--secureboot-private-key=<replaceable>SB_KEY</replaceable></option></term>
|
|
|
|
<listitem><para>A path to a private key to use for signing of the resulting binary. If the
|
|
<varname>SigningEngine=</varname>/<option>--signing-engine=</option> option is used, this may also be
|
|
an engine-specific designation. This option is required by
|
|
<varname>SecureBootSigningTool=sbsign</varname>/<option>--signtool=sbsign</option>. </para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>SecureBootCertificate=<replaceable>SB_CERT</replaceable></varname></term>
|
|
<term><option>--secureboot-certificate=<replaceable>SB_CERT</replaceable></option></term>
|
|
|
|
<listitem><para>A path to a certificate to use for signing of the resulting binary. If the
|
|
<varname>SigningEngine=</varname>/<option>--signing-engine=</option> option is used, this may also
|
|
be an engine-specific designation. This option is required by
|
|
<varname>SecureBootSigningTool=sbsign</varname>/<option>--signtool=sbsign</option>. </para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>SecureBootCertificateDir=<replaceable>SB_PATH</replaceable></varname></term>
|
|
<term><option>--secureboot-certificate-dir=<replaceable>SB_PATH</replaceable></option></term>
|
|
|
|
<listitem><para>A path to a nss certificate database directory to use for signing of the resulting binary.
|
|
Takes effect when <varname>SecureBootSigningTool=pesign</varname>/<option>--signtool=pesign</option> is used.
|
|
Defaults to <filename>/etc/pki/pesign</filename>.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>SecureBootCertificateName=<replaceable>SB_CERTNAME</replaceable></varname></term>
|
|
<term><option>--secureboot-certificate-name=<replaceable>SB_CERTNAME</replaceable></option></term>
|
|
|
|
<listitem><para>The name of the nss certificate database entry to use for signing of the resulting binary.
|
|
This option is required by <varname>SecureBootSigningTool=pesign</varname>/<option>--signtool=pesign</option>.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>SecureBootCertificateValidity=<replaceable>DAYS</replaceable></varname></term>
|
|
<term><option>--secureboot-certificate-validity=<replaceable>DAYS</replaceable></option></term>
|
|
|
|
<listitem><para>Period of validity (in days) for a certificate created by
|
|
<command>genkey</command>. Defaults to 3650, i.e. 10 years.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>SigningEngine=<replaceable>ENGINE</replaceable></varname></term>
|
|
<term><option>--signing-engine=<replaceable>ENGINE</replaceable></option></term>
|
|
|
|
<listitem><para>An "engine" for signing of the resulting binary. This option is currently passed
|
|
verbatim to the <option>--engine=</option> option of
|
|
<citerefentry project='archlinux'><refentrytitle>sbsign</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
|
|
</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>SignKernel=<replaceable>BOOL</replaceable></varname></term>
|
|
<term><option>--sign-kernel</option></term>
|
|
<term><option>--no-sign-kernel</option></term>
|
|
|
|
<listitem><para>Override the detection of whether to sign the Linux binary itself before it is
|
|
embedded in the combined image. If not specified, it will be signed if a SecureBoot signing key is
|
|
provided via the
|
|
<varname>SecureBootPrivateKey=</varname>/<option>--secureboot-private-key=</option> option and the
|
|
binary has not already been signed. If
|
|
<varname>SignKernel=</varname>/<option>--sign-kernel</option> is true, and the binary has already
|
|
been signed, the signature will be appended anyway.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>SBAT=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term>
|
|
<term><option>--sbat=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term>
|
|
|
|
<listitem><para>SBAT metadata associated with the UKI or addon. SBAT policies are useful to revoke
|
|
whole groups of UKIs or addons with a single, static policy update that does not take space in
|
|
DBX/MOKX. If not specified manually, a default metadata entry consisting of
|
|
<literal>uki,1,UKI,uki,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html</literal>
|
|
will be used, to ensure it is always possible to revoke UKIs and addons. For more information on
|
|
SBAT see <ulink url="https://github.com/rhboot/shim/blob/main/SBAT.md">Shim documentation</ulink>.
|
|
</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>[PCRSignature:<replaceable>NAME</replaceable>] section</title>
|
|
|
|
<para>In the config file, those options are grouped by section. On the command line, they
|
|
must be specified in the same order. The sections specified in both sources are combined.
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><varname>PCRPrivateKey=<replaceable>PATH</replaceable></varname></term>
|
|
<term><option>--pcr-private-key=<replaceable>PATH</replaceable></option></term>
|
|
|
|
<listitem><para>A private key to use for signing PCR policies. On the command line, this option may
|
|
be specified more than once, in which case multiple signatures will be made.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>PCRPublicKey=<replaceable>PATH</replaceable></varname></term>
|
|
<term><option>--pcr-public-key=<replaceable>PATH</replaceable></option></term>
|
|
|
|
<listitem><para>A public key to use for signing PCR policies.</para>
|
|
|
|
<para>On the command line, this option may be specified more than once, similarly to the
|
|
<option>--pcr-private-key=</option> option. If not present, the public keys will be extracted from
|
|
the private keys. On the command line, if present, this option must be specified the same number of
|
|
times as the <option>--pcr-private-key=</option> option.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>Phases=<replaceable>LIST</replaceable></varname></term>
|
|
<term><option>--phases=<replaceable>LIST</replaceable></option></term>
|
|
|
|
<listitem><para>A comma or space-separated list of colon-separated phase paths to sign a policy
|
|
for. Each set of boot phase paths will be signed with the corresponding private key. If not
|
|
present, the default of
|
|
<citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
will be used.</para>
|
|
|
|
<para>On the command line, when this argument is present, it must appear the same number of times as
|
|
the <option>--pcr-private-key=</option> option. </para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<example>
|
|
<title>Minimal invocation</title>
|
|
|
|
<programlisting>$ ukify build \
|
|
--linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
|
|
--initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \
|
|
--cmdline='quiet rw'
|
|
</programlisting>
|
|
|
|
<para>This creates an unsigned UKI <filename>./vmlinuz.unsigned.efi</filename>.</para>
|
|
</example>
|
|
|
|
<example>
|
|
<title>All the bells and whistles</title>
|
|
|
|
<programlisting>$ ukify build \
|
|
--linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
|
|
--initrd=early_cpio \
|
|
--initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \
|
|
--sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
|
|
uki.author.myimage,1,UKI for System,uki.author.myimage,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html' \
|
|
--pcr-private-key=pcr-private-initrd-key.pem \
|
|
--pcr-public-key=pcr-public-initrd-key.pem \
|
|
--phases='enter-initrd' \
|
|
--pcr-private-key=pcr-private-system-key.pem \
|
|
--pcr-public-key=pcr-public-system-key.pem \
|
|
--phases='enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit \
|
|
enter-initrd:leave-initrd:sysinit:ready' \
|
|
--pcr-banks=sha384,sha512 \
|
|
--secureboot-private-key=sb.key \
|
|
--secureboot-certificate=sb.cert \
|
|
--sign-kernel \
|
|
--cmdline='quiet rw rhgb'
|
|
</programlisting>
|
|
|
|
<para>This creates a signed UKI <filename index='false'>./vmlinuz.signed.efi</filename>.
|
|
The initrd section contains two concatenated parts, <filename index='false'>early_cpio</filename>
|
|
and <filename index='false'>initramfs-6.0.9-300.fc37.x86_64.img</filename>.
|
|
The policy embedded in the <literal>.pcrsig</literal> section will be signed for the initrd (the
|
|
<constant>enter-initrd</constant> phase) with the key
|
|
<filename index='false'>pcr-private-initrd-key.pem</filename>, and for the main system (phases
|
|
<constant>leave-initrd</constant>, <constant>sysinit</constant>, <constant>ready</constant>) with the
|
|
key <filename index='false'>pcr-private-system-key.pem</filename>. The Linux binary and the resulting
|
|
combined image will be signed with the SecureBoot key <filename index='false'>sb.key</filename>.</para>
|
|
</example>
|
|
|
|
<example>
|
|
<title>All the bells and whistles, via a config file</title>
|
|
|
|
<para>This is the same as the previous example, but this time the configuration is stored in a
|
|
file:</para>
|
|
|
|
<programlisting>$ cat ukify.conf
|
|
[UKI]
|
|
Initrd=early_cpio
|
|
Cmdline=quiet rw rhgb
|
|
|
|
SecureBootPrivateKey=sb.key
|
|
SecureBootCertificate=sb.cert
|
|
SignKernel=yes
|
|
PCRBanks=sha384,sha512
|
|
|
|
[PCRSignature:initrd]
|
|
PCRPrivateKey=pcr-private-initrd-key.pem
|
|
PCRPublicKey=pcr-public-initrd-key.pem
|
|
Phases=enter-initrd
|
|
|
|
[PCRSignature:system]
|
|
PCRPrivateKey=pcr-private-system-key.pem
|
|
PCRPublicKey=pcr-public-system-key.pem
|
|
Phases=enter-initrd:leave-initrd
|
|
enter-initrd:leave-initrd:sysinit
|
|
enter-initrd:leave-initrd:sysinit:ready
|
|
|
|
$ ukify -c ukify.conf build \
|
|
--linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
|
|
--initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img
|
|
</programlisting>
|
|
|
|
<para>One "initrd" (<filename index='false'>early_cpio</filename>) is specified in the config file, and
|
|
the other initrd (<filename index='false'>initramfs-6.0.9-300.fc37.x86_64.img</filename>) is specified
|
|
on the command line. This may be useful for example when the first initrd contains microcode for the CPU
|
|
and does not need to be updated when the kernel version changes, unlike the actual initrd.</para>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Kernel command line auxiliary PE</title>
|
|
|
|
<programlisting>ukify build \
|
|
--secureboot-private-key=sb.key \
|
|
--secureboot-certificate=sb.cert \
|
|
--cmdline='debug' \
|
|
--sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
|
|
uki.addon.author,1,UKI Addon for System,uki.addon.author,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html'
|
|
--output=debug.cmdline
|
|
</programlisting>
|
|
|
|
<para>This creates a signed PE binary that contains the additional kernel command line parameter
|
|
<literal>debug</literal> with SBAT metadata referring to the owner of the addon.</para>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Decide signing policy and create certificate and keys</title>
|
|
|
|
<para>First, let's create an config file that specifies what signatures shall be made:</para>
|
|
|
|
<programlisting># cat >/etc/kernel/uki.conf <<EOF
|
|
<xi:include href="uki.conf.example" parse="text" />EOF</programlisting>
|
|
|
|
<para>Next, we can generate the certificate and keys:</para>
|
|
<programlisting># ukify genkey --config=/etc/kernel/uki.conf
|
|
Writing SecureBoot private key to /etc/kernel/secure-boot.key.pem
|
|
Writing SecureBoot certificate to /etc/kernel/secure-boot.cert.pem
|
|
Writing private key for PCR signing to /etc/kernel/pcr-initrd.key.pem
|
|
Writing public key for PCR signing to /etc/kernel/pcr-initrd.pub.pem
|
|
Writing private key for PCR signing to /etc/kernel/pcr-system.key.pem
|
|
Writing public key for PCR signing to /etc/kernel/pcr-system.pub.pem
|
|
</programlisting>
|
|
|
|
<para>(Both operations need to be done as root to allow write access
|
|
to <filename>/etc/kernel/</filename>.)</para>
|
|
|
|
<para>Subsequent invocations using the config file
|
|
(<command>ukify build --config=/etc/kernel/uki.conf</command>)
|
|
will use this certificate and key files. Note that the
|
|
<citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
|
plugin <filename>60-ukify.install</filename> uses <filename>/etc/kernel/uki.conf</filename>
|
|
by default, so after this file has been created, installations of kernels that create a UKI on the
|
|
local machine using <command>kernel-install</command> will perform signing using this config.</para>
|
|
</example>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
<para><simplelist type="inline">
|
|
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
|
|
</simplelist></para>
|
|
</refsect1>
|
|
|
|
</refentry>
|