Debian Codegraph @

upstream/debian-trixie/man8/systemd-pcrphase.service.8

raw
1 '\" t
2 .TH "SYSTEMD\-PCRPHASE\&.SERVICE" "8" "" "systemd 257.13" "systemd-pcrphase.service"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-pcrphase.service, systemd-pcrphase-sysinit.service, systemd-pcrphase-initrd.service, systemd-pcrmachine.service, systemd-pcrfs-root.service, [email protected], systemd-pcrextend \- Measure boot phase into TPM2 PCR 11, machine ID and file system identity into PCR 15
24 .SH "SYNOPSIS"
25 .PP
26 systemd\-pcrphase\&.service
27 .PP
28 systemd\-pcrphase\-sysinit\&.service
29 .PP
30 systemd\-pcrphase\-initrd\&.service
31 .PP
32 systemd\-pcrmachine\&.service
33 .PP
34 systemd\-pcrfs\-root\&.service
35 .PP
36 systemd\-pcrfs@\&.service
37 .PP
38 /usr/lib/systemd/systemd\-pcrextend
39 [\fISTRING\fR]
40 .SH "DESCRIPTION"
41 .PP
42 systemd\-pcrphase\&.service,
43 systemd\-pcrphase\-sysinit\&.service, and
44 systemd\-pcrphase\-initrd\&.service
45 are system services that measure specific strings into TPM2 PCR 11 during boot at various milestones of the boot process\&.
46 .PP
47 systemd\-pcrmachine\&.service
48 is a system service that measures the machine ID (see
49 \fBmachine-id\fR(5)) into PCR 15\&.
50 .PP
51 systemd\-pcrfs\-root\&.service
52 and
53 systemd\-pcrfs@\&.service
54 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\&.
55 systemd\-pcrfs\-root\&.service
56 does so for the root file system,
57 systemd\-pcrfs@\&.service
58 is a template unit that measures the file system indicated by its instance identifier instead\&.
59 .PP
60 These services require
61 \fBsystemd-stub\fR(7)
62 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:
63 .sp
64 .RS 4
65 .ie n \{\
66 \h'-04' 1.\h'+01'\c
67 .\}
68 .el \{\
69 .sp -1
70 .IP " 1." 4.2
71 .\}
72 "enter\-initrd"
73 \(em 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
74 \fBsystemd-pcrphase-initrd.service\fR(8)
75 service is started\&.)
76 .RE
77 .sp
78 .RS 4
79 .ie n \{\
80 \h'-04' 2.\h'+01'\c
81 .\}
82 .el \{\
83 .sp -1
84 .IP " 2." 4.2
85 .\}
86 "leave\-initrd"
87 \(em 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
88 \fBsystemd-pcrphase-sysinit.service\fR(8)
89 service is stopped\&.)
90 .RE
91 .sp
92 .RS 4
93 .ie n \{\
94 \h'-04' 3.\h'+01'\c
95 .\}
96 .el \{\
97 .sp -1
98 .IP " 3." 4.2
99 .\}
100 "sysinit"
101 \(em 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
102 \fBsystemd-pcrphase-sysinit.service\fR(8)
103 service is started\&.)
104 .RE
105 .sp
106 .RS 4
107 .ie n \{\
108 \h'-04' 4.\h'+01'\c
109 .\}
110 .el \{\
111 .sp -1
112 .IP " 4." 4.2
113 .\}
114 "ready"
115 \(em during later boot\-up, after remote file systems have been activated (i\&.e\&. after
116 remote\-fs\&.target), but before users are permitted to log in (i\&.e\&. before
117 systemd\-user\-sessions\&.service)\&. 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
118 \fBsystemd-pcrphase-sysinit.service\fR(8)
119 service is started\&.)
120 .RE
121 .sp
122 .RS 4
123 .ie n \{\
124 \h'-04' 5.\h'+01'\c
125 .\}
126 .el \{\
127 .sp -1
128 .IP " 5." 4.2
129 .\}
130 "shutdown"
131 \(em 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
132 systemd\-pcrphase\&.service
133 service is stopped\&.)
134 .RE
135 .sp
136 .RS 4
137 .ie n \{\
138 \h'-04' 6.\h'+01'\c
139 .\}
140 .el \{\
141 .sp -1
142 .IP " 6." 4.2
143 .\}
144 "final"
145 \(em 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
146 \fBsystemd-pcrphase-sysinit.service\fR(8)
147 service is stopped\&.)
148 .RE
149 .PP
150 During a regular system lifecycle, PCR 11 is extended with the strings
151 "enter\-initrd",
152 "leave\-initrd",
153 "sysinit",
154 "ready",
155 "shutdown", and
156 "final"\&.
157 .PP
158 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
159 "enter\-initrd:leave\-initrd:sysinit:ready", while the one for the initrd is just
160 "enter\-initrd"\&. The phase path for the boot phase before the initrd is an empty string; because that\*(Aqs hard to pass around a single colon (":") 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\&.
161 .PP
162 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\*(Aqs encryption key after the system transitioned from the initrd into the host root file system\&.
163 .PP
164 Use
165 \fBsystemd-measure\fR(1)
166 to pre\-calculate expected PCR 11 values for specific boot phases (via the
167 \fB\-\-phase=\fR
168 switch)\&.
169 .PP
170 systemd\-pcrfs\-root\&.service
171 and
172 systemd\-pcrfs@\&.service
173 are automatically pulled into the initial transaction by
174 \fBsystemd-gpt-auto-generator\fR(8)
175 for the root and
176 /var/
177 file systems\&.
178 \fBsystemd-fstab-generator\fR(8)
179 will do this for all mounts with the
180 \fBx\-systemd\&.pcrfs\fR
181 mount option in
182 /etc/fstab\&.
183 .SH "OPTIONS"
184 .PP
185 The
186 /usr/lib/systemd/system\-pcrextend
187 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:
188 .PP
189 \fB\-\-bank=\fR
190 .RS 4
191 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\&.
192 .sp
193 Added in version 252\&.
194 .RE
195 .PP
196 \fB\-\-pcr=\fR
197 .RS 4
198 Takes the index of the PCR to extend\&. If
199 \fB\-\-machine\-id\fR
200 or
201 \fB\-\-file\-system=\fR
202 are specified defaults to 15, otherwise defaults to 11\&.
203 .sp
204 Added in version 255\&.
205 .RE
206 .PP
207 \fB\-\-tpm2\-device=\fR\fB\fIPATH\fR\fR
208 .RS 4
209 Controls which TPM2 device to use\&. Expects a device node path referring to the TPM2 chip (e\&.g\&.
210 /dev/tpmrm0)\&. Alternatively the special value
211 "auto"
212 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
213 "list"
214 may be used to enumerate all suitable TPM2 devices currently discovered\&.
215 .sp
216 Added in version 252\&.
217 .RE
218 .PP
219 \fB\-\-graceful\fR
220 .RS 4
221 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\&.
222 .sp
223 Added in version 253\&.
224 .RE
225 .PP
226 \fB\-\-machine\-id\fR
227 .RS 4
228 Instead of measuring a word specified on the command line into PCR 11, measure the host\*(Aqs machine ID into PCR 15\&.
229 .sp
230 Added in version 253\&.
231 .RE
232 .PP
233 \fB\-\-file\-system=\fR
234 .RS 4
235 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\&.
236 .sp
237 Added in version 253\&.
238 .RE
239 .PP
240 \fB\-h\fR, \fB\-\-help\fR
241 .RS 4
242 Print a short help text and exit\&.
243 .RE
244 .PP
245 \fB\-\-version\fR
246 .RS 4
247 Print a short version string and exit\&.
248 .RE
249 .SH "FILES"
250 .PP
251 /run/log/systemd/tpm2\-measure\&.log
252 .RS 4
253 Measurements are logged into an event log file maintained in
254 /run/log/systemd/tpm2\-measure\&.log, which contains a
255 \m[blue]\fBJSON\-SEQ\fR\m[]\&\s-2\u[1]\d\s+2
256 series of objects that follow the general structure of the
257 \m[blue]\fBTCG Canonical Event Log Format (CEL\-JSON)\fR\m[]\&\s-2\u[2]\d\s+2
258 event objects (but lack the
259 "recnum"
260 field)\&.
261 .sp
262 A
263 \fBLOCK_EX\fR
264 BSD file lock (\fBflock\fR(2)) 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
265 \fBLOCK_SH\fR
266 lock while doing so\&.
267 .sp
268 Added in version 252\&.
269 .RE
270 .SH "SEE ALSO"
271 .PP
272 \fBsystemd\fR(1), \fBsystemd-stub\fR(7), \fBsystemd-measure\fR(1), \fBsystemd-gpt-auto-generator\fR(8), \fBsystemd-fstab-generator\fR(8), \m[blue]\fBTPM2 PCR Measurements Made by systemd\fR\m[]\&\s-2\u[3]\d\s+2
273 .SH "NOTES"
274 .IP " 1." 4
275 JSON-SEQ
276 .RS 4
277 \%https://www.rfc-editor.org/rfc/rfc7464.html
278 .RE
279 .IP " 2." 4
280 TCG Canonical Event Log Format (CEL-JSON)
281 .RS 4
282 \%https://trustedcomputinggroup.org/resource/canonical-event-log-format/
283 .RE
284 .IP " 3." 4
285 TPM2 PCR Measurements Made by systemd
286 .RS 4
287 \%https://systemd.io/TPM2_PCR_MEASUREMENTS
288 .RE