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
|
<?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-pcrphase</refname>
<refpurpose>Measure boot phase into TPM2 PCR 11</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>/usr/lib/systemd/system-pcrphase</filename> <replaceable>STRING</replaceable></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>These services require
<citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> to be
used in a unified kernel image (UKI) setup. They execute no operation when invoked 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
certain literal strings indicating various phases of the boot process into TPM2 PCR 11. During a regular
boot process the following strings are extended into PCR 11.</para>
<orderedlist>
<listitem><para><literal>enter-initrd</literal> is extended into PCR 11 early when the initrd
initializes, before activating system extension images for the initrd. It is supposed to act as 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 string is extended at start of
<filename>systemd-pcrphase-initrd.service</filename>.)</para></listitem>
<listitem><para><literal>leave-initrd</literal> is extended into PCR 11 when the initrd is about to
transition into the host file system, i.e. when it achieved its purpose. It is supposed to act as
barrier between kernel/initrd code and host OS code. (This string is extended at stop of
<filename>systemd-pcrphase-initrd.service</filename>.)</para></listitem>
<listitem><para><literal>sysinit</literal> is extended into PCR 11 when basic system initialization is
complete (which includes local file systems have been mounted), and the system begins starting regular
system services. (This string is extended at start of
<filename>systemd-pcrphase-sysinit.service</filename>.)</para></listitem>
<listitem><para><literal>ready</literal> is extended into PCR 11 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 is
supposed to act as barrier between the time where unprivileged regular users are still prohibited to
log in and where they are allowed to log in. (This string is extended at start of
<filename>systemd-pcrphase.service</filename>.)</para></listitem>
<listitem><para><literal>shutdown</literal> is extended into PCR 11 when system shutdown begins. It is
supposed to act as barrier between the time the system is fully up and running and where it is about to
shut down. (This string is extended at stop of
<filename>systemd-pcrphase.service</filename>.)</para></listitem>
<listitem><para><literal>final</literal> is extended into PCR 11 at the end of system shutdown. It is
supposed to act as barrier between the time the service manager still runs and when it transitions into
the final boot phase where service management is not available anymore. (This string is extended at
stop of <filename>systemd-pcrphase-sysinit.service</filename>.)</para></listitem>
</orderedlist>
<para>During a regular system lifecycle, the strings <literal>enter-initrd</literal> →
<literal>leave-initrd</literal> → <literal>sysinit</literal> → <literal>ready</literal> →
<literal>shutdown</literal> → <literal>final</literal> are extended into PCR 11, one after the
other.</para>
<para>Specific phases of the boot process may be referenced via the series of strings measured, separated
by colons (the "boot path"). For example, the boot 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 boot path for the 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 boot 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>
</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>
<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>
</para>
</refsect1>
</refentry>
|
