Debian Codegraph @

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

raw
1 '\" t
2 .TH "SYSTEMD\-PCRPHASE\&.SERVICE" "8" "" "systemd 261~rc3" "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-pcrosseparator.service, systemd-pcrproduct.service, [email protected], systemd-pcrfs-root.service, [email protected], systemd-pcrnvdone.service, systemd-pcrextend \- Measure boot phases, machine ID, product UUID, user records and file system identity into TPM PCRs and NvPCRs
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\-pcrosseparator\&.service
35 .PP
36 systemd\-pcrproduct\&.service
37 .PP
38 systemd\-pcrlogin@\&.service
39 .PP
40 systemd\-pcrfs\-root\&.service
41 .PP
42 systemd\-pcrfs@\&.service
43 .PP
44 systemd\-pcrnvdone\&.service
45 .PP
46 /usr/lib/systemd/systemd\-pcrextend
47 [\fISTRING\fR]
48 .SH "DESCRIPTION"
49 .PP
50 systemd\-pcrphase\&.service,
51 systemd\-pcrphase\-sysinit\&.service, and
52 systemd\-pcrphase\-initrd\&.service
53 are system services that measure specific strings into TPM2 PCR 11 during boot at various milestones of the boot process\&.
54 .PP
55 systemd\-pcrmachine\&.service
56 is a system service that measures the machine ID (see
57 \fBmachine-id\fR(5)) into PCR 15\&.
58 .PP
59 systemd\-pcrosseparator\&.service
60 is a system service that measures the word
61 "os\-separator"
62 into PCRs 0\-7, 9, 12\-14\&. This acts as additional separator measurement separating pre\-boot (i\&.e\&. firmware + bootloader) measurements from OS measurements, and in particular "seals" off the firmware PCRs\&.
63 .PP
64 systemd\-pcrproduct\&.service
65 is a system service that measures the firmware product UUID (as provided by one of SMBIOS, Devicetree, \&...) into a NvPCR named
66 "hardware"\&.
67 .PP
68 systemd\-pcrlogin@\&.service
69 is a template service that measures the (reduced, canonical JSON) user record of the user indicated by its instance identifier (a UID) into a NvPCR named
70 "login"\&. It is started by
71 \fBsystemd-logind.service\fR(8)
72 on the user\*(Aqs first login of the current boot, much like
73 \[email protected]\fR(5)\&. Unlike the latter it is intentionally never stopped again: it is a
74 \fIType=oneshot\fR
75 service with
76 \fIRemainAfterExit=yes\fR
77 in
78 system\&.slice, so each user is measured exactly once per boot regardless of how often they log in and out (NvPCR extensions form a hash chain, so measuring the same record twice would otherwise make the NvPCR value unpredictable)\&. The resulting
79 "login"
80 NvPCR (together with the
81 /run/log/systemd/tpm2\-measure\&.log
82 event log) thus provides a TPM\-backed, append\-only record of which user identities were activated during the current boot\&.
83 .PP
84 systemd\-pcrnvdone\&.service
85 is a system service that measures a separator event into PCR 9 once all NvPCRs have completed initialization\&.
86 .PP
87 systemd\-pcrfs\-root\&.service
88 and
89 systemd\-pcrfs@\&.service
90 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\&.
91 systemd\-pcrfs\-root\&.service
92 does so for the root file system,
93 systemd\-pcrfs@\&.service
94 is a template unit that measures the file system indicated by its instance identifier instead\&.
95 .PP
96 These services require
97 \fBsystemd-stub\fR(7)
98 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:
99 .sp
100 .RS 4
101 .ie n \{\
102 \h'-04' 1.\h'+01'\c
103 .\}
104 .el \{\
105 .sp -1
106 .IP " 1." 4.2
107 .\}
108 "enter\-initrd"
109 \(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
110 \fBsystemd-pcrphase-initrd.service\fR(8)
111 service is started\&.)
112 .RE
113 .sp
114 .RS 4
115 .ie n \{\
116 \h'-04' 2.\h'+01'\c
117 .\}
118 .el \{\
119 .sp -1
120 .IP " 2." 4.2
121 .\}
122 "leave\-initrd"
123 \(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
124 \fBsystemd-pcrphase-sysinit.service\fR(8)
125 service is stopped\&.)
126 .RE
127 .sp
128 .RS 4
129 .ie n \{\
130 \h'-04' 3.\h'+01'\c
131 .\}
132 .el \{\
133 .sp -1
134 .IP " 3." 4.2
135 .\}
136 "sysinit"
137 \(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
138 \fBsystemd-pcrphase-sysinit.service\fR(8)
139 service is started\&.)
140 .RE
141 .sp
142 .RS 4
143 .ie n \{\
144 \h'-04' 4.\h'+01'\c
145 .\}
146 .el \{\
147 .sp -1
148 .IP " 4." 4.2
149 .\}
150 "ready"
151 \(em during later boot\-up, after remote file systems have been activated (i\&.e\&. after
152 remote\-fs\&.target), but before users are permitted to log in (i\&.e\&. before
153 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
154 \fBsystemd-pcrphase-sysinit.service\fR(8)
155 service is started\&.)
156 .RE
157 .sp
158 .RS 4
159 .ie n \{\
160 \h'-04' 5.\h'+01'\c
161 .\}
162 .el \{\
163 .sp -1
164 .IP " 5." 4.2
165 .\}
166 "shutdown"
167 \(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
168 systemd\-pcrphase\&.service
169 service is stopped\&.)
170 .RE
171 .sp
172 .RS 4
173 .ie n \{\
174 \h'-04' 6.\h'+01'\c
175 .\}
176 .el \{\
177 .sp -1
178 .IP " 6." 4.2
179 .\}
180 "final"
181 \(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
182 \fBsystemd-pcrphase-sysinit.service\fR(8)
183 service is stopped\&.)
184 .RE
185 .PP
186 During a regular system lifecycle, PCR 11 is extended with the strings
187 "enter\-initrd",
188 "leave\-initrd",
189 "sysinit",
190 "ready",
191 "shutdown", and
192 "final"\&.
193 .PP
194 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
195 "enter\-initrd:leave\-initrd:sysinit:ready", while the one for the initrd is just
196 "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\&.
197 .PP
198 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\&.
199 .PP
200 Use
201 \fBsystemd-measure\fR(1)
202 to pre\-calculate expected PCR 11 values for specific boot phases (via the
203 \fB\-\-phase=\fR
204 switch)\&.
205 .PP
206 systemd\-pcrfs\-root\&.service
207 and
208 systemd\-pcrfs@\&.service
209 are automatically pulled into the initial transaction by
210 \fBsystemd-gpt-auto-generator\fR(8)
211 for the root and
212 /var/
213 file systems\&.
214 \fBsystemd-fstab-generator\fR(8)
215 will do this for all mounts with the
216 \fBx\-systemd\&.pcrfs\fR
217 mount option in
218 /etc/fstab\&.
219 .SH "OPTIONS"
220 .PP
221 The
222 /usr/lib/systemd/systemd\-pcrextend
223 executable may also be invoked from the command line, where it expects the word to extend into a PCR or NvPCR, as well as the following switches:
224 .PP
225 \fB\-\-bank=\fR
226 .RS 4
227 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\&.
228 .sp
229 Added in version 252\&.
230 .RE
231 .PP
232 \fB\-\-pcr=\fR
233 .RS 4
234 Takes the index of the PCR to extend\&. If
235 \fB\-\-machine\-id\fR
236 or
237 \fB\-\-file\-system=\fR
238 are specified defaults to 15, otherwise (and unless
239 \fB\-\-product\-id\fR
240 is specified) defaults to 11\&. May be specified multiple times, in order to measure to multiple PCRs at the same time\&. May not be combined with
241 \fB\-\-nvpcr=\fR\&.
242 .sp
243 Added in version 255\&.
244 .RE
245 .PP
246 \fB\-\-nvpcr=\fR
247 .RS 4
248 Takes a name of an NvPCR to extend\&. NvPCRs are additional PCRs implemented via TPM NV indexes\&. The name should be a short string such as
249 "hardware"
250 or
251 "disk\-encryption"\&. If
252 \fB\-\-product\-id\fR
253 is specified defaults
254 "hardware"\&. May not be combined with
255 \fB\-\-pcr=\fR\&.
256 .sp
257 Added in version 259\&.
258 .RE
259 .PP
260 \fB\-\-tpm2\-device=\fR\fB\fIPATH\fR\fR
261 .RS 4
262 Controls which TPM2 device to use\&. Expects a device node path referring to the TPM2 chip (e\&.g\&.
263 /dev/tpmrm0)\&. Alternatively the special value
264 "auto"
265 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
266 "list"
267 may be used to enumerate all suitable TPM2 devices currently discovered\&.
268 .sp
269 Added in version 252\&.
270 .RE
271 .PP
272 \fB\-\-graceful\fR
273 .RS 4
274 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\&.
275 .sp
276 Added in version 253\&.
277 .RE
278 .PP
279 \fB\-\-early\fR
280 .RS 4
281 Selects early\-boot mode\&. Specifically this means that the NvPCR anchor secret is not attempted to be written into
282 /var/lib/
283 and the boot loader partition in addition to
284 /run/\&. (Unlike the latter the former are generally not mounted and writable during early boot or in the initrd\&.)
285 .sp
286 Added in version 259\&.
287 .RE
288 .PP
289 \fB\-\-machine\-id\fR
290 .RS 4
291 Instead of measuring a word specified on the command line into PCR 11, measure the host\*(Aqs machine ID into PCR 15\&.
292 .sp
293 Added in version 253\&.
294 .RE
295 .PP
296 \fB\-\-product\-id\fR
297 .RS 4
298 Instead of measuring a word specified on the command line into PCR 11, measure the firmware\*(Aqs product UUID into an NvPCR named
299 "hardware"\&.
300 .sp
301 Added in version 259\&.
302 .RE
303 .PP
304 \fB\-\-login=\fR
305 .RS 4
306 Instead of measuring a word specified on the command line into PCR 11, measure the user record of the specified user into an NvPCR named
307 "login"\&. The parameter must be a user name or numeric UID\&. The record is reduced to its
308 "regular",
309 "perMachine"
310 and
311 "binding"
312 sections (i\&.e\&. the privileged, secret, status and signature sections are stripped, so that for example password hash changes do not perturb the NvPCR), normalized and serialized to canonical JSON before measurement\&. This is primarily used by
313 systemd\-pcrlogin@\&.service\&.
314 .sp
315 Added in version 261\&.
316 .RE
317 .PP
318 \fB\-\-file\-system=\fR
319 .RS 4
320 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\&.
321 .sp
322 Added in version 253\&.
323 .RE
324 .PP
325 \fB\-\-event\-type=\fR
326 .RS 4
327 Set the event log event type for this measurement\&. Pass
328 "help"
329 for a list of currently defined identifiers\&. Defaults to an appropriate value for
330 \fB\-\-machine\-id\fR,
331 \fB\-\-product\-id\fR,
332 \fB\-\-file\-system=\fR,
333 \fB\-\-login=\fR, and otherwise to
334 "phase"\&.
335 .sp
336 Added in version 259\&.
337 .RE
338 .PP
339 \fB\-h\fR, \fB\-\-help\fR
340 .RS 4
341 Print a short help text and exit\&.
342 .RE
343 .PP
344 \fB\-\-version\fR
345 .RS 4
346 Print a short version string and exit\&.
347 .RE
348 .SH "FILES"
349 .PP
350 /run/log/systemd/tpm2\-measure\&.log
351 .RS 4
352 Measurements are logged into an event log file maintained in
353 /run/log/systemd/tpm2\-measure\&.log, which contains a
354 \m[blue]\fBJSON\-SEQ\fR\m[]\&\s-2\u[1]\d\s+2
355 series of objects that follow the general structure of the
356 \m[blue]\fBTCG Canonical Event Log Format (CEL\-JSON)\fR\m[]\&\s-2\u[2]\d\s+2
357 event objects (but lack the
358 "recnum"
359 field)\&.
360 .sp
361 A
362 \fBLOCK_EX\fR
363 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
364 \fBLOCK_SH\fR
365 lock while doing so\&.
366 .sp
367 Added in version 252\&.
368 .RE
369 .PP
370 /usr/lib/nvpcr/*\&.nvpcr
371 .RS 4
372 Definition files for NvPCRs\&.
373 .sp
374 Added in version 259\&.
375 .RE
376 .SH "SEE ALSO"
377 .PP
378 \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
379 .SH "NOTES"
380 .IP " 1." 4
381 JSON-SEQ
382 .RS 4
383 \%https://www.rfc-editor.org/rfc/rfc7464.html
384 .RE
385 .IP " 2." 4
386 TCG Canonical Event Log Format (CEL-JSON)
387 .RS 4
388 \%https://trustedcomputinggroup.org/resource/canonical-event-log-format/
389 .RE
390 .IP " 3." 4
391 TPM2 PCR Measurements Made by systemd
392 .RS 4
393 \%https://systemd.io/TPM2_PCR_MEASUREMENTS
394 .RE