| <?xml version='1.0'?> <!--*-nxml-*--> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
| <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
| |
| <refentry id="systemd-pcrphase.service" conditional='HAVE_GNU_EFI' |
| xmlns:xi="http://www.w3.org/2001/XInclude"> |
| |
| <refentryinfo> |
| <title>systemd-pcrphase.service</title> |
| <productname>systemd</productname> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>systemd-pcrphase.service</refentrytitle> |
| <manvolnum>8</manvolnum> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>systemd-pcrphase.service</refname> |
| <refname>systemd-pcrphase-sysinit.service</refname> |
| <refname>systemd-pcrphase-initrd.service</refname> |
| <refname>systemd-pcrmachine.service</refname> |
| <refname>systemd-pcrfs-root.service</refname> |
| <refname>systemd-pcrfs@.service</refname> |
| <refname>systemd-pcrphase</refname> |
| <refpurpose>Measure boot phase into TPM2 PCR 11, machine ID and file system identity into PCR 15</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <para><filename>systemd-pcrphase.service</filename></para> |
| <para><filename>systemd-pcrphase-sysinit.service</filename></para> |
| <para><filename>systemd-pcrphase-initrd.service</filename></para> |
| <para><filename>systemd-pcrmachine.service</filename></para> |
| <para><filename>systemd-pcrfs-root.service</filename></para> |
| <para><filename>systemd-pcrfs@.service</filename></para> |
| <para><filename>/usr/lib/systemd/systemd-pcrphase</filename> <optional><replaceable>STRING</replaceable></optional></para> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para><filename>systemd-pcrphase.service</filename>, |
| <filename>systemd-pcrphase-sysinit.service</filename>, and |
| <filename>systemd-pcrphase-initrd.service</filename> are system services that measure specific strings |
| into TPM2 PCR 11 during boot at various milestones of the boot process.</para> |
| |
| <para><filename>systemd-pcrmachine.service</filename> is a system service that measures the machine ID |
| (see <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>) into |
| PCR 15.</para> |
| |
| <para><filename>systemd-pcrfs-root.service</filename> and <filename>systemd-pcrfs@.service</filename> are |
| services that measure file system identity information (i.e. mount point, file system type, label and |
| UUID, partition label and UUID) into PCR 15. <filename>systemd-pcrfs-root.service</filename> does so for |
| the root file system, <filename>systemd-pcrfs@.service</filename> is a template unit that measures the |
| file system indicated by its instance identifier instead.</para> |
| |
| <para>These services require |
| <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> to be |
| used in a unified kernel image (UKI). They execute no operation when the stub has not been used to invoke |
| the kernel. The stub will measure the invoked kernel and associated vendor resources into PCR 11 before |
| handing control to it; once userspace is invoked these services then will extend TPM2 PCR 11 with certain |
| literal strings indicating phases of the boot process. During a regular boot process PCR 11 is extended |
| with the following strings:</para> |
| |
| <orderedlist> |
| <listitem><para><literal>enter-initrd</literal> — early when the initrd initializes, before activating |
| system extension images for the initrd. It acts as a barrier between the time where the kernel |
| initializes and where the initrd starts operating and enables system extension images, i.e. code |
| shipped outside of the UKI. (This extension happens when |
| <filename>systemd-pcrphase-initrd.service</filename> is started.)</para></listitem> |
| |
| <listitem><para><literal>leave-initrd</literal> — when the initrd is about to transition into the host |
| file system. It acts as barrier between initrd code and host OS code. (This extension happens when |
| <filename>systemd-pcrphase-initrd.service</filename> is stopped.)</para></listitem> |
| |
| <listitem><para><literal>sysinit</literal> — when basic system initialization is complete (which |
| includes local file systems having been mounted), and the system begins starting regular system |
| services. (This extension happens when <filename>systemd-pcrphase-sysinit.service</filename> is |
| started.)</para></listitem> |
| |
| <listitem><para><literal>ready</literal> — during later boot-up, after remote file systems have been |
| activated (i.e. after <filename>remote-fs.target</filename>), but before users are permitted to log in |
| (i.e. before <filename>systemd-user-sessions.service</filename>). It acts as barrier between the time |
| where unprivileged regular users are still prohibited to log in and where they are allowed to log in. |
| (This extension happens when <filename>systemd-pcrphase.service</filename> is started.) |
| </para></listitem> |
| |
| <listitem><para><literal>shutdown</literal> — when the system shutdown begins. It acts as barrier |
| between the time the system is fully up and running and where it is about to shut down. (This extension |
| happens when <filename>systemd-pcrphase.service</filename> is stopped.)</para></listitem> |
| |
| <listitem><para><literal>final</literal> — at the end of system shutdown. It acts as barrier between |
| the time the service manager still runs and when it transitions into the final shutdown phase where |
| service management is not available anymore. (This extension happens when |
| <filename>systemd-pcrphase-sysinit.service</filename> is stopped.)</para></listitem> |
| </orderedlist> |
| |
| <para>During a regular system lifecycle, PCR 11 is extended with the strings |
| <literal>enter-initrd</literal>, <literal>leave-initrd</literal>, <literal>sysinit</literal>, |
| <literal>ready</literal>, <literal>shutdown</literal>, and <literal>final</literal>.</para> |
| |
| <para>Specific phases of the boot process may be referenced via the series of strings measured, separated |
| by colons (the "phase path"). For example, the phase path for the regular system runtime is |
| <literal>enter-initrd:leave-initrd:sysinit:ready</literal>, while the one for the initrd is just |
| <literal>enter-initrd</literal>. The phase path for the boot phase before the initrd is an empty string; |
| because that's hard to pass around a single colon (<literal>:</literal>) may be used instead. Note that |
| the aforementioned six strings are just the default strings and individual systems might measure other |
| strings at other times, and thus implement different and more fine-grained boot phases to bind policy |
| to.</para> |
| |
| <para>By binding policy of TPM2 objects to a specific phase path it is possible to restrict access to |
| them to specific phases of the boot process, for example making it impossible to access the root file |
| system's encryption key after the system transitioned from the initrd into the host root file system. |
| </para> |
| |
| <para>Use |
| <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> to |
| pre-calculate expected PCR 11 values for specific boot phases (via the <option>--phase=</option> switch). |
| </para> |
| |
| <para><filename>systemd-pcrfs-root.service</filename> and <filename>systemd-pcrfs@.service</filename> are |
| automatically pulled into the initial transaction by |
| <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
| for the root and <filename>/var/</filename> file |
| systems. <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
| will do this for all mounts with the <option>x-systemd.pcrfs</option> mount option in |
| <filename>/etc/fstab</filename>.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Options</title> |
| |
| <para>The <filename>/usr/lib/systemd/system-pcrphase</filename> executable may also be invoked from the |
| command line, where it expects the word to extend into PCR 11, as well as the following switches:</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><option>--bank=</option></term> |
| |
| <listitem><para>Takes the PCR banks to extend the specified word into. If not specified the tool |
| automatically determines all enabled PCR banks and measures the word into all of |
| them.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--tpm2-device=</option><replaceable>PATH</replaceable></term> |
| |
| <listitem><para>Controls which TPM2 device to use. Expects a device node path referring to the TPM2 |
| chip (e.g. <filename>/dev/tpmrm0</filename>). Alternatively the special value <literal>auto</literal> |
| may be specified, in order to automatically determine the device node of a suitable TPM2 device (of |
| which there must be exactly one). The special value <literal>list</literal> may be used to enumerate |
| all suitable TPM2 devices currently discovered.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--graceful</option></term> |
| |
| <listitem><para>If no TPM2 firmware, kernel subsystem, kernel driver or device support is found, exit |
| with exit status 0 (i.e. indicate success). If this is not specified any attempt to measure without a |
| TPM2 device will cause the invocation to fail.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--machine-id</option></term> |
| |
| <listitem><para>Instead of measuring a word specified on the command line into PCR 11, measure the |
| host's machine ID into PCR 15.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--file-system=</option></term> |
| |
| <listitem><para>Instead of measuring a word specified on the command line into PCR 11, measure |
| identity information of the specified file system into PCR 15. The parameter must be the path to the |
| established mount point of the file system to measure.</para></listitem> |
| </varlistentry> |
| |
| <xi:include href="standard-options.xml" xpointer="help" /> |
| <xi:include href="standard-options.xml" xpointer="version" /> |
| |
| </variablelist> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| <para> |
| <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
| </para> |
| </refsect1> |
| |
| </refentry> |