1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
|
<?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="systemd-pcrphase.service" conditional='ENABLE_BOOTLOADER HAVE_OPENSSL HAVE_TPM2'
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-pcrextend</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-pcrextend</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 the
<citerefentry><refentrytitle>systemd-pcrphase-initrd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
service 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 the
<filename>systemd-pcrphase-initrd.service</filename> service 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 the
<citerefentry><refentrytitle>systemd-pcrphase-sysinit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
service 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 the <filename>systemd-pcrphase.service</filename> service 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 the <filename>systemd-pcrphase.service</filename> service 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 the
<citerefentry><refentrytitle>systemd-pcrphase-sysinit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
service 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-pcrextend</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>
<xi:include href="version-info.xml" xpointer="v252"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--pcr=</option></term>
<listitem><para>Takes the index of the PCR to extend. If <option>--machine-id</option> or
<option>--file-system=</option> are specified defaults to 15, otherwise defaults to 11.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--tpm2-device=<replaceable>PATH</replaceable></option></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>
<xi:include href="version-info.xml" xpointer="v252"/></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>
<xi:include href="version-info.xml" xpointer="v253"/></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>
<xi:include href="version-info.xml" xpointer="v253"/></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>
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
</varlistentry>
<xi:include href="standard-options.xml" xpointer="help" />
<xi:include href="standard-options.xml" xpointer="version" />
</variablelist>
</refsect1>
<refsect1>
<title>Files</title>
<variablelist>
<varlistentry>
<term><filename>/run/log/systemd/tpm2-measure.log</filename></term>
<listitem><para>Measurements are logged into an event log file maintained in
<filename>/run/log/systemd/tpm2-measure.log</filename>, which contains a <ulink
url="https://www.rfc-editor.org/rfc/rfc7464.html">JSON-SEQ</ulink> series of objects that follow the
general structure of the <ulink
url="https://trustedcomputinggroup.org/resource/canonical-event-log-format/">TCG Canonical Event Log
Format (CEL-JSON)</ulink> event objects (but lack the <literal>recnum</literal>
field).</para>
<para>A <constant>LOCK_EX</constant> BSD file lock (<citerefentry
project='man-pages'><refentrytitle>flock</refentrytitle><manvolnum>2</manvolnum></citerefentry>) on
the log file is acquired while the measurement is made and the file is updated. Thus, applications
that intend to acquire a consistent quote from the TPM with the associated snapshot of the event log
should acquire a <constant>LOCK_SH</constant> lock while doing so.</para>
<xi:include href="version-info.xml" xpointer="v252"/></listitem>
</varlistentry>
</variablelist>
</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-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><ulink url="https://systemd.io/TPM2_PCR_MEASUREMENTS">TPM2 PCR Measurements Made by systemd</ulink></member>
</simplelist></para>
</refsect1>
</refentry>
|
