diff options
Diffstat (limited to 'man/systemd-stub.xml')
| -rw-r--r-- | man/systemd-stub.xml | 123 |
1 files changed, 114 insertions, 9 deletions
diff --git a/man/systemd-stub.xml b/man/systemd-stub.xml index 1e9bb5d631..f8c3eee393 100644 --- a/man/systemd-stub.xml +++ b/man/systemd-stub.xml @@ -45,9 +45,9 @@ system into the Linux world.</para> <para>The UEFI boot stub looks for various resources for the kernel invocation inside the UEFI PE binary - itself. This allows combining various resources inside a single PE binary image, which may then be signed - via UEFI SecureBoot as a whole, covering all individual resources at once. Specifically it may - include:</para> + itself. This allows combining various resources inside a single PE binary image (usually called "Unified + Kernel Image", or "UKI" for short), which may then be signed via UEFI SecureBoot as a whole, covering all + individual resources at once. Specifically it may include:</para> <itemizedlist> <listitem><para>The ELF Linux kernel images will be looked for in the <literal>.linux</literal> PE @@ -68,6 +68,14 @@ <listitem><para>A boot splash (in Windows <filename>.BMP</filename> format) to show on screen before invoking the kernel will be looked for in the <literal>.splash</literal> PE section.</para></listitem> + + <listitem><para>A set of cryptographic signatures for expected TPM2 PCR values when this kernel is + booted, in JSON format, in the <literal>.pcrsig</literal> section. This is useful for implementing TPM2 + policies that bind disk encryption and similar to kernels that are signed by a specific + key.</para></listitem> + + <listitem><para>A public key in PEM format matching this TPM2 PCR signature data in the + <literal>.pcrpkey</literal> section.</para></listitem> </itemizedlist> <para>If UEFI SecureBoot is enabled and the <literal>.cmdline</literal> section is present in the executed @@ -81,8 +89,25 @@ DeviceTree in the corresponding EFI configuration table. systemd-stub will ask the firmware via the <literal>EFI_DT_FIXUP_PROTOCOL</literal> for hardware specific fixups to the DeviceTree.</para> - <para>The contents of these six PE sections are measured into TPM PCR 11, that is otherwise not - used. Thus, it can be pre-calculated without too much effort.</para> + <para>The contents of seven of these eight PE sections are measured into TPM PCR 11, that is otherwise + not used. Thus, it can be pre-calculated without too much effort. The <literal>.pcrsig</literal> section + is not included in this PCR measurement, since it's supposed to contain signatures for the expected + results for these measurements, i.e. of the outputs of the measurement operation, and thus cannot also be + input to it.</para> + + <para>When <literal>.pcrsig</literal> and/or <literal>.pcrpkey</literal> are present in a unified kernel + image their contents are passed to the booted kernel in an synthetic initrd cpio archive that places them in the + <filename>/.extra/tpm2-pcr-signature.json</filename> and + <filename>/.extra/tpm2-pcr-public-key.pem</filename> files. Typically, a + <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> line then + ensures they are copied into <filename>/run/systemd/tpm2-pcr-signature.json</filename> and + <filename>/run/systemd/tpm2-pcr-public-key.pem</filename> where they remain accessible even after the + system transitions out of the initrd environment into the host file system. Tools such + <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and <citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry> + will automatically use files present under these paths to unlock protected resources (encrypted storage + or credentials) or bind encryption to booted kernels.</para> </refsect1> <refsect1> @@ -133,7 +158,7 @@ </refsect1> <refsect1> - <title>TPM2 PCR Notes</title> + <title>TPM PCR Notes</title> <para>Note that when a unified kernel using <command>systemd-stub</command> is invoked the firmware will measure it as a whole to TPM PCR 4, covering all embedded resources, such as the stub code itself, the @@ -166,12 +191,12 @@ </row> <row> - <entry>Boot splash (embedded in the unified PE binary)</entry> + <entry>Core kernel code (embedded in unified PE binary)</entry> <entry>4 + 11</entry> </row> <row> - <entry>Core kernel code (embedded in unified PE binary)</entry> + <entry>OS release information (embedded in the unified PE binary)</entry> <entry>4 + 11</entry> </row> @@ -191,6 +216,21 @@ </row> <row> + <entry>Boot splash (embedded in the unified PE binary)</entry> + <entry>4 + 11</entry> + </row> + + <row> + <entry>TPM2 PCR signature JSON (embedded in unified PE binary, synthesized into initrd)</entry> + <entry>4 + 9</entry> + </row> + + <row> + <entry>TPM2 PCR PEM public key (embedded in unified PE binary, synthesized into initrd)</entry> + <entry>4 + 9 + 11</entry> + </row> + + <row> <entry>Credentials (synthesized initrd from companion files)</entry> <entry>9 + 12</entry> </row> @@ -280,6 +320,66 @@ </refsect1> <refsect1> + <title>initrd Resources</title> + + <para>The following resources are passed as initrd cpio archives to the booted kernel, and thus make up + the initial file system hierarchy in the initrd execution environment:</para> + + <variablelist> + <varlistentry> + <term><filename>/</filename></term> + + <listitem><para>The main initrd from the <literal>.initrd</literal> PE section of the unified kernel image.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/.extra/credentials/*.cred</filename></term> + <listitem><para>Credential files (suffix <literal>.cred</literal>) that are placed next to the + unified kernel image (as described above) are copied into the + <filename>/.extra/credentials/</filename> directory in the initrd execution + environment.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/.extra/global_credentials/*.cred</filename></term> + <listitem><para>Similar, credential files in the <filename>/loader/credentials/</filename> directory + in the file system the unified kernel image is placed in are copied into the + <filename>/.extra/global_credentials/</filename> directory in the initrd execution + environment.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/.extra/sysext/*.raw</filename></term> + <listitem><para>System extension image files (suffix <literal>.raw</literal>) that are placed next to + the unified kernel image (as described above) are copied into the + <filename>/.extra/sysext/</filename> directory in the initrd execution environment.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/.extra/tpm2-pcr-signature.json</filename></term> + <listitem><para>The TPM2 PCR signature JSON object included in the <literal>.pcrsig</literal> PE + section of the unified kernel image is copied into the + <filename>/.extra/tpm2-pcr-signature.json</filename> file in the initrd execution + environment.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/.extra/tpm2-pcr-pkey.pem</filename></term> + <listitem><para>The PEM public key included in the <literal>.pcrpkey</literal> PE section of the + unified kernel image is copied into the <filename>/.extra/tpm2-pcr-public-key.pem</filename> file in + the initrd execution environment.</para></listitem> + </varlistentry> + </variablelist> + + <para>Note that all these files are located in the <literal>tmpfs</literal> file system the kernel sets + up for the initrd file hierarchy and are thus lost when the system transitions from the initrd execution + environment into the host file system. If these resources shall be kept around over this transition they + need to be copied to a place that survives the transition first, for example via a suitable + <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> line. By + default, this is done for the TPM2 PCR signature and public key files.</para> + </refsect1> + + <refsect1> <title>Assembling Kernel Images</title> <para>In order to assemble an UEFI PE kernel image from various components as described above, use an @@ -313,6 +413,10 @@ <para>This expects a pair of X.509 private key and certificate as parameters and then signs the UEFI PE executable we generated above for UEFI SecureBoot and generates a signed UEFI PE executable as result.</para> + + <para>See + <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> for + an example involving the <literal>.pcrsig</literal> and <literal>.pcrpkey</literal> sections.</para> </refsect1> <refsect1> @@ -325,7 +429,8 @@ <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>, <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>, <citerefentry project='man-pages'><refentrytitle>objcopy</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='archlinux'><refentrytitle>sbsign</refentrytitle><manvolnum>1</manvolnum></citerefentry> + <citerefentry project='archlinux'><refentrytitle>sbsign</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> </refsect1> </refentry> |