]>
Commit | Line | Data |
---|---|---|
708d7524 LP |
1 | <?xml version='1.0'?> <!--*-nxml-*--> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
708d7524 LP |
4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
5 | ||
ec3cf73f | 6 | <refentry id="systemd-pcrphase.service" conditional='ENABLE_BOOTLOADER HAVE_OPENSSL HAVE_TPM2' |
708d7524 LP |
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> | |
047273e6 | 21 | <refname>systemd-pcrphase-sysinit.service</refname> |
708d7524 | 22 | <refname>systemd-pcrphase-initrd.service</refname> |
2bd33c90 LP |
23 | <refname>systemd-pcrmachine.service</refname> |
24 | <refname>systemd-pcrfs-root.service</refname> | |
25 | <refname>systemd-pcrfs@.service</refname> | |
32295fa0 | 26 | <refname>systemd-pcrextend</refname> |
2bd33c90 | 27 | <refpurpose>Measure boot phase into TPM2 PCR 11, machine ID and file system identity into PCR 15</refpurpose> |
708d7524 LP |
28 | </refnamediv> |
29 | ||
30 | <refsynopsisdiv> | |
31 | <para><filename>systemd-pcrphase.service</filename></para> | |
15f9a152 | 32 | <para><filename>systemd-pcrphase-sysinit.service</filename></para> |
708d7524 | 33 | <para><filename>systemd-pcrphase-initrd.service</filename></para> |
2bd33c90 LP |
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> | |
32295fa0 | 37 | <para><filename>/usr/lib/systemd/systemd-pcrextend</filename> <optional><replaceable>STRING</replaceable></optional></para> |
708d7524 LP |
38 | </refsynopsisdiv> |
39 | ||
40 | <refsect1> | |
41 | <title>Description</title> | |
42 | ||
047273e6 | 43 | <para><filename>systemd-pcrphase.service</filename>, |
86a06615 | 44 | <filename>systemd-pcrphase-sysinit.service</filename>, and |
708d7524 | 45 | <filename>systemd-pcrphase-initrd.service</filename> are system services that measure specific strings |
047273e6 | 46 | into TPM2 PCR 11 during boot at various milestones of the boot process.</para> |
708d7524 | 47 | |
2bd33c90 LP |
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 | ||
708d7524 LP |
58 | <para>These services require |
59 | <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> to be | |
8b9f0921 ZJS |
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 | |
86a06615 | 62 | handing control to it; once userspace is invoked these services then will extend TPM2 PCR 11 with certain |
2bd33c90 LP |
63 | literal strings indicating phases of the boot process. During a regular boot process PCR 11 is extended |
64 | with the following strings:</para> | |
708d7524 LP |
65 | |
66 | <orderedlist> | |
86a06615 ZJS |
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 | |
8fb35004 ZJS |
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> | |
86a06615 ZJS |
73 | |
74 | <listitem><para><literal>leave-initrd</literal> — when the initrd is about to transition into the host | |
8fb35004 ZJS |
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> | |
86a06615 ZJS |
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 | |
8fb35004 ZJS |
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> | |
86a06615 ZJS |
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. | |
8fb35004 | 88 | (This extension happens when the <filename>systemd-pcrphase.service</filename> service is started.) |
86a06615 ZJS |
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 | |
8fb35004 | 93 | happens when the <filename>systemd-pcrphase.service</filename> service is stopped.)</para></listitem> |
86a06615 ZJS |
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 | |
8fb35004 ZJS |
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> | |
708d7524 LP |
100 | </orderedlist> |
101 | ||
86a06615 ZJS |
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> | |
708d7524 LP |
105 | |
106 | <para>Specific phases of the boot process may be referenced via the series of strings measured, separated | |
86a06615 | 107 | by colons (the "phase path"). For example, the phase path for the regular system runtime is |
047273e6 | 108 | <literal>enter-initrd:leave-initrd:sysinit:ready</literal>, while the one for the initrd is just |
86a06615 ZJS |
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> | |
708d7524 | 114 | |
86a06615 ZJS |
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> | |
708d7524 LP |
119 | |
120 | <para>Use | |
121 | <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> to | |
86a06615 ZJS |
122 | pre-calculate expected PCR 11 values for specific boot phases (via the <option>--phase=</option> switch). |
123 | </para> | |
2bd33c90 LP |
124 | |
125 | <para><filename>systemd-pcrfs-root.service</filename> and <filename>systemd-pcrfs@.service</filename> are | |
126 | automatically pulled into the initial transaction by | |
f37f0f35 | 127 | <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
2bd33c90 LP |
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> | |
708d7524 LP |
132 | </refsect1> |
133 | ||
134 | <refsect1> | |
135 | <title>Options</title> | |
136 | ||
32295fa0 | 137 | <para>The <filename>/usr/lib/systemd/system-pcrextend</filename> executable may also be invoked from the |
708d7524 LP |
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 | |
ec07c3c8 AK |
146 | them.</para> |
147 | ||
148 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
708d7524 LP |
149 | </varlistentry> |
150 | ||
b0d00ec6 LP |
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 | ||
708d7524 | 160 | <varlistentry> |
9bfabe14 | 161 | <term><option>--tpm2-device=<replaceable>PATH</replaceable></option></term> |
708d7524 LP |
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 | |
ec07c3c8 AK |
167 | all suitable TPM2 devices currently discovered.</para> |
168 | ||
169 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
708d7524 LP |
170 | </varlistentry> |
171 | ||
0318d545 LP |
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 | |
ec07c3c8 AK |
177 | TPM2 device will cause the invocation to fail.</para> |
178 | ||
179 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
0318d545 LP |
180 | </varlistentry> |
181 | ||
2bd33c90 LP |
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 | |
ec07c3c8 AK |
186 | host's machine ID into PCR 15.</para> |
187 | ||
188 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
2bd33c90 LP |
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 | |
ec07c3c8 AK |
196 | established mount point of the file system to measure.</para> |
197 | ||
198 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
2bd33c90 LP |
199 | </varlistentry> |
200 | ||
708d7524 LP |
201 | <xi:include href="standard-options.xml" xpointer="help" /> |
202 | <xi:include href="standard-options.xml" xpointer="version" /> | |
203 | ||
204 | </variablelist> | |
205 | </refsect1> | |
206 | ||
75174a5d LP |
207 | <refsect1> |
208 | <title>Files</title> | |
209 | ||
210 | <variablelist> | |
211 | <varlistentry> | |
9551aa70 | 212 | <term><filename>/run/log/systemd/tpm2-measure.log</filename></term> |
75174a5d LP |
213 | |
214 | <listitem><para>Measurements are logged into an event log file maintained in | |
9551aa70 | 215 | <filename>/run/log/systemd/tpm2-measure.log</filename>, which contains a <ulink |
75174a5d LP |
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 Common 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 | |
2de0bb2f AK |
226 | should acquire a <constant>LOCK_SH</constant> lock while doing so.</para> |
227 | ||
228 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
75174a5d LP |
229 | </varlistentry> |
230 | </variablelist> | |
231 | </refsect1> | |
232 | ||
708d7524 LP |
233 | <refsect1> |
234 | <title>See Also</title> | |
13a69c12 DT |
235 | <para><simplelist type="inline"> |
236 | <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
237 | <member><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry></member> | |
238 | <member><citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
239 | <member><citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
240 | <member><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
241 | <member><ulink url="https://systemd.io/TPM2_PCR_MEASUREMENTS">TPM2 PCR Measurements Made by systemd</ulink></member> | |
242 | </simplelist></para> | |
708d7524 LP |
243 | </refsect1> |
244 | ||
245 | </refentry> |