man/systemd-pcrphase.service.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd-pcrphase.service" conditional='ENABLE_BOOTLOADER'
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>systemd-pcrphase.service</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>systemd-pcrphase.service</refentrytitle>
  16     <manvolnum>8</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>systemd-pcrphase.service</refname>
  21     <refname>systemd-pcrphase-sysinit.service</refname>
  22     <refname>systemd-pcrphase-initrd.service</refname>
  23     <refname>systemd-pcrmachine.service</refname>
  24     <refname>systemd-pcrfs-root.service</refname>
  25     <refname>systemd-pcrfs@.service</refname>
  26     <refname>systemd-pcrextend</refname>
  27     <refpurpose>Measure boot phase into TPM2 PCR 11, machine ID and file system identity into PCR 15</refpurpose>
  28   </refnamediv>
  29
  30   <refsynopsisdiv>
  31     <para><filename>systemd-pcrphase.service</filename></para>
  32     <para><filename>systemd-pcrphase-sysinit.service</filename></para>
  33     <para><filename>systemd-pcrphase-initrd.service</filename></para>
  34     <para><filename>systemd-pcrmachine.service</filename></para>
  35     <para><filename>systemd-pcrfs-root.service</filename></para>
  36     <para><filename>systemd-pcrfs@.service</filename></para>
  37     <para><filename>/usr/lib/systemd/systemd-pcrextend</filename> <optional><replaceable>STRING</replaceable></optional></para>
  38   </refsynopsisdiv>
  39
  40   <refsect1>
  41     <title>Description</title>
  42
  43     <para><filename>systemd-pcrphase.service</filename>,
  44     <filename>systemd-pcrphase-sysinit.service</filename>, and
  45     <filename>systemd-pcrphase-initrd.service</filename> are system services that measure specific strings
  46     into TPM2 PCR 11 during boot at various milestones of the boot process.</para>
  47
  48     <para><filename>systemd-pcrmachine.service</filename> is a system service that measures the machine ID
  49     (see <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>) into
  50     PCR 15.</para>
  51
  52     <para><filename>systemd-pcrfs-root.service</filename> and <filename>systemd-pcrfs@.service</filename> are
  53     services that measure file system identity information (i.e. mount point, file system type, label and
  54     UUID, partition label and UUID) into PCR 15. <filename>systemd-pcrfs-root.service</filename> does so for
  55     the root file system, <filename>systemd-pcrfs@.service</filename> is a template unit that measures the
  56     file system indicated by its instance identifier instead.</para>
  57
  58     <para>These services require
  59     <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> to be
  60     used in a unified kernel image (UKI). They execute no operation when the stub has not been used to invoke
  61     the kernel. The stub will measure the invoked kernel and associated vendor resources into PCR 11 before
  62     handing control to it; once userspace is invoked these services then will extend TPM2 PCR 11 with certain
  63     literal strings indicating phases of the boot process. During a regular boot process PCR 11 is extended
  64     with the following strings:</para>
  65
  66     <orderedlist>
  67       <listitem><para><literal>enter-initrd</literal> — early when the initrd initializes, before activating
  68       system extension images for the initrd. It acts as a barrier between the time where the kernel
  69       initializes and where the initrd starts operating and enables system extension images, i.e. code
  70       shipped outside of the UKI. (This extension happens when the
  71       <citerefentry><refentrytitle>systemd-pcrphase-initrd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  72       service is started.)</para></listitem>
  73
  74       <listitem><para><literal>leave-initrd</literal> — when the initrd is about to transition into the host
  75       file system. It acts as barrier between initrd code and host OS code. (This extension happens when the
  76       <filename>systemd-pcrphase-initrd.service</filename> service is stopped.)</para></listitem>
  77
  78       <listitem><para><literal>sysinit</literal> — when basic system initialization is complete (which
  79       includes local file systems having been mounted), and the system begins starting regular system
  80       services. (This extension happens when the
  81       <citerefentry><refentrytitle>systemd-pcrphase-sysinit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  82       service is started.)</para></listitem>
  83
  84       <listitem><para><literal>ready</literal> — during later boot-up, after remote file systems have been
  85       activated (i.e. after <filename>remote-fs.target</filename>), but before users are permitted to log in
  86       (i.e. before <filename>systemd-user-sessions.service</filename>). It acts as barrier between the time
  87       where unprivileged regular users are still prohibited to log in and where they are allowed to log in.
  88       (This extension happens when the <filename>systemd-pcrphase.service</filename> service is started.)
  89       </para></listitem>
  90
  91       <listitem><para><literal>shutdown</literal> — when the system shutdown begins. It acts as barrier
  92       between the time the system is fully up and running and where it is about to shut down. (This extension
  93       happens when the <filename>systemd-pcrphase.service</filename> service is stopped.)</para></listitem>
  94
  95       <listitem><para><literal>final</literal> — at the end of system shutdown. It acts as barrier between
  96       the time the service manager still runs and when it transitions into the final shutdown phase where
  97       service management is not available anymore. (This extension happens when the
  98       <citerefentry><refentrytitle>systemd-pcrphase-sysinit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  99       service is stopped.)</para></listitem>
 100     </orderedlist>
 101
 102     <para>During a regular system lifecycle, PCR 11 is extended with the strings
 103     <literal>enter-initrd</literal>, <literal>leave-initrd</literal>, <literal>sysinit</literal>,
 104     <literal>ready</literal>, <literal>shutdown</literal>, and <literal>final</literal>.</para>
 105
 106     <para>Specific phases of the boot process may be referenced via the series of strings measured, separated
 107     by colons (the "phase path"). For example, the phase path for the regular system runtime is
 108     <literal>enter-initrd:leave-initrd:sysinit:ready</literal>, while the one for the initrd is just
 109     <literal>enter-initrd</literal>. The phase path for the boot phase before the initrd is an empty string;
 110     because that's hard to pass around a single colon (<literal>:</literal>) may be used instead. Note that
 111     the aforementioned six strings are just the default strings and individual systems might measure other
 112     strings at other times, and thus implement different and more fine-grained boot phases to bind policy
 113     to.</para>
 114
 115     <para>By binding policy of TPM2 objects to a specific phase path it is possible to restrict access to
 116     them to specific phases of the boot process, for example making it impossible to access the root file
 117     system's encryption key after the system transitioned from the initrd into the host root file system.
 118     </para>
 119
 120     <para>Use
 121     <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> to
 122     pre-calculate expected PCR 11 values for specific boot phases (via the <option>--phase=</option> switch).
 123     </para>
 124
 125     <para><filename>systemd-pcrfs-root.service</filename> and <filename>systemd-pcrfs@.service</filename> are
 126     automatically pulled into the initial transaction by
 127     <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 128     for the root and <filename>/var/</filename> file
 129     systems. <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 130     will do this for all mounts with the <option>x-systemd.pcrfs</option> mount option in
 131     <filename>/etc/fstab</filename>.</para>
 132   </refsect1>
 133
 134   <refsect1>
 135     <title>Options</title>
 136
 137     <para>The <filename>/usr/lib/systemd/system-pcrextend</filename> executable may also be invoked from the
 138     command line, where it expects the word to extend into PCR 11, as well as the following switches:</para>
 139
 140     <variablelist>
 141       <varlistentry>
 142         <term><option>--bank=</option></term>
 143
 144         <listitem><para>Takes the PCR banks to extend the specified word into. If not specified the tool
 145         automatically determines all enabled PCR banks and measures the word into all of
 146         them.</para>
 147
 148         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 149       </varlistentry>
 150
 151       <varlistentry>
 152         <term><option>--pcr=</option></term>
 153
 154         <listitem><para>Takes the index of the PCR to extend. If <option>--machine-id</option> or
 155         <option>--file-system=</option> are specified defaults to 15, otherwise defaults to 11.</para>
 156
 157         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 158       </varlistentry>
 159
 160       <varlistentry>
 161         <term><option>--tpm2-device=</option><replaceable>PATH</replaceable></term>
 162
 163         <listitem><para>Controls which TPM2 device to use. Expects a device node path referring to the TPM2
 164         chip (e.g. <filename>/dev/tpmrm0</filename>). Alternatively the special value <literal>auto</literal>
 165         may be specified, in order to automatically determine the device node of a suitable TPM2 device (of
 166         which there must be exactly one). The special value <literal>list</literal> may be used to enumerate
 167         all suitable TPM2 devices currently discovered.</para>
 168
 169         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 170       </varlistentry>
 171
 172       <varlistentry>
 173         <term><option>--graceful</option></term>
 174
 175         <listitem><para>If no TPM2 firmware, kernel subsystem, kernel driver or device support is found, exit
 176         with exit status 0 (i.e. indicate success). If this is not specified any attempt to measure without a
 177         TPM2 device will cause the invocation to fail.</para>
 178
 179         <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 180       </varlistentry>
 181
 182       <varlistentry>
 183         <term><option>--machine-id</option></term>
 184
 185         <listitem><para>Instead of measuring a word specified on the command line into PCR 11, measure the
 186         host's machine ID into PCR 15.</para>
 187
 188         <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 189       </varlistentry>
 190
 191       <varlistentry>
 192         <term><option>--file-system=</option></term>
 193
 194         <listitem><para>Instead of measuring a word specified on the command line into PCR 11, measure
 195         identity information of the specified file system into PCR 15. The parameter must be the path to the
 196         established mount point of the file system to measure.</para>
 197
 198         <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 199       </varlistentry>
 200
 201       <xi:include href="standard-options.xml" xpointer="help" />
 202       <xi:include href="standard-options.xml" xpointer="version" />
 203
 204     </variablelist>
 205   </refsect1>
 206
 207   <refsect1>
 208     <title>Files</title>
 209
 210     <variablelist>
 211       <varlistentry>
 212         <term><filename>/run/log/systemd/tpm2-measure.log</filename></term>
 213
 214         <listitem><para>Measurements are logged into an event log file maintained in
 215         <filename>/run/log/systemd/tpm2-measure.log</filename>, which contains a <ulink
 216         url="https://www.rfc-editor.org/rfc/rfc7464.html">JSON-SEQ</ulink> series of objects that follow the
 217         general structure of the <ulink
 218         url="https://trustedcomputinggroup.org/resource/canonical-event-log-format/">TCG Canonical Event Log
 219         Format (CEL-JSON)</ulink> event objects (but lack the <literal>recnum</literal>
 220         field).</para>
 221
 222         <para>A <constant>LOCK_EX</constant> BSD file lock (<citerefentry
 223         project='man-pages'><refentrytitle>flock</refentrytitle><manvolnum>2</manvolnum></citerefentry>) on
 224         the log file is acquired while the measurement is made and the file is updated. Thus, applications
 225         that intend to acquire a consistent quote from the TPM with the associated snapshot of the event log
 226         should acquire a <constant>LOCK_SH</constant> lock while doing so.</para>
 227
 228         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 229       </varlistentry>
 230     </variablelist>
 231   </refsect1>
 232
 233   <refsect1>
 234     <title>See Also</title>
 235     <para>
 236       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 237       <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 238       <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 239       <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 240       <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 241       <ulink url="https://systemd.io/TPM2_PCR_MEASUREMENTS">TPM2 PCR Measurements Made by systemd</ulink>
 242     </para>
 243   </refsect1>
 244
 245 </refentry>