]>
Commit | Line | Data |
---|---|---|
e2062109 LP |
1 | <?xml version='1.0'?> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
e2062109 LP |
4 | <refentry id="systemd.pcrlock" |
5 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
6 | ||
7 | <refentryinfo> | |
8 | <title>systemd.pcrlock</title> | |
9 | <productname>systemd</productname> | |
10 | </refentryinfo> | |
11 | ||
12 | <refmeta> | |
13 | <refentrytitle>systemd.pcrlock</refentrytitle> | |
14 | <manvolnum>5</manvolnum> | |
15 | </refmeta> | |
16 | ||
17 | <refnamediv> | |
18 | <refname>systemd.pcrlock</refname> | |
19 | <refname>systemd.pcrlock.d</refname> | |
20 | <refpurpose>PCR measurement prediction files</refpurpose> | |
21 | </refnamediv> | |
22 | ||
23 | <refsynopsisdiv> | |
73e97bb0 ZJS |
24 | <para><simplelist> |
25 | <member><filename>/etc/pcrlock.d/*.pcrlock</filename></member> | |
26 | <member><filename>/etc/pcrlock.d/*.pcrlock.d/*.pcrlock</filename></member> | |
27 | <member><filename>/run/pcrlock.d/*.pcrlock</filename></member> | |
28 | <member><filename>/run/pcrlock.d/*.pcrlock.d/*.pcrlock</filename></member> | |
29 | <member><filename>/var/lib/pcrlock.d/*.pcrlock</filename></member> | |
30 | <member><filename>/var/lib/pcrlock.d/*.pcrlock.d/*.pcrlock</filename></member> | |
31 | <member><filename>/usr/local/pcrlock.d/*.pcrlock</filename></member> | |
32 | <member><filename>/usr/local/pcrlock.d/*.pcrlock.d/*.pcrlock</filename></member> | |
33 | <member><filename>/usr/lib/pcrlock.d/*.pcrlock</filename></member> | |
34 | <member><filename>/usr/lib/pcrlock.d/*.pcrlock.d/*.pcrlock</filename></member> | |
35 | </simplelist></para> | |
e2062109 LP |
36 | </refsynopsisdiv> |
37 | ||
38 | <refsect1> | |
39 | <title>Description</title> | |
40 | ||
41 | <para><filename>*.pcrlock</filename> files define expected TPM2 PCR measurements of components involved | |
42 | in the boot | |
43 | process. <citerefentry><refentrytitle>systemd-pcrlock</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
44 | uses such pcrlock files to analyze and predict TPM2 PCR measurements. The pcrlock files are JSON arrays | |
45 | that follow a subset of the <ulink | |
46 | url="https://trustedcomputinggroup.org/resource/canonical-event-log-format/">TCG Common Event Log Format | |
47 | (CEL-JSON)</ulink> specification. Specifically the <literal>recnum</literal>, <literal>content</literal>, | |
48 | and <literal>content_type</literal> record fields are not used and ignored if present. Each pcrlock file | |
49 | defines one set of expected, ordered PCR measurements of a specific component of the boot.</para> | |
50 | ||
e423b40d YW |
51 | <para>*.pcrlock files may be placed in various <filename>.d/</filename> drop-in directories (see above |
52 | for a full list). All matching files discovered in these directories are sorted alphabetically by their | |
53 | file name (without taking the actual directory they were found in into account): pcrlock files with | |
e2062109 LP |
54 | alphabetically earlier names are expected to cover measurements done before those with alphabetically |
55 | later names. In order to make positioning pcrlock files in the boot process convenient the files are | |
56 | expected (by convention, this is not enforced) to be named | |
57 | <literal><replaceable>NNN</replaceable>-<replaceable>component</replaceable>.pcrlock</literal> (where | |
58 | <replaceable>NNN</replaceable> is a three-digit decimal number), for example | |
59 | <filename>750-enter-initrd.pcrlock</filename>.</para> | |
60 | ||
61 | <para>For various components of the boot process more than one alternative pcrlock file shall be | |
62 | supported (i.e. "variants"). For example to cover multiple kernels installed in parallel in the access | |
63 | policy, or multiple versions of the boot loader. This can be done by placing | |
64 | <filename>*.pcrlock.d/*.pcrlock</filename> in the drop-in dirs, i.e. a common directory for a specific | |
65 | component, that contains one or more pcrlock files each covering one <emphasis>variant</emphasis> of the | |
66 | component. Example: <filename>650-kernel.pcrlock.d/6.5.5-200.fc38.x86_64.pcrlock</filename> and | |
67 | <filename>650-kernel.pcrlock.d/6.5.7-100.fc38.x86_64.pcrlock</filename></para> | |
68 | ||
69 | <para>Use <command>systemd-pcrlock list-components</command> to list all pcrlock files currently | |
70 | installed.</para> | |
71 | ||
72 | <para>Use the various <command>lock-*</command> commands of <command>systemd-pcrlock</command> to | |
73 | automatically generate suitable pcrlock files for various types of resources.</para> | |
74 | </refsect1> | |
75 | ||
76 | <refsect1> | |
77 | <title>Well-known Components</title> | |
78 | ||
79 | <para>Components of the boot process may be defined freely by the administrator or OS vendor. The | |
80 | following components are well-known however, and are defined by systemd. The list below is useful for | |
81 | ordering local pcrlock files properly against these components of the boot.</para> | |
82 | ||
83 | <variablelist> | |
84 | ||
85 | <varlistentry> | |
86 | <term><filename>240-secureboot-policy.pcrlock</filename></term> | |
87 | ||
88 | <listitem><para>The SecureBoot policy, as recorded to PCR 7. May be generated via | |
89 | <command>systemd-pcrlock lock-secureboot-policy</command>.</para> | |
90 | ||
91 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
92 | </varlistentry> | |
93 | ||
94 | <varlistentry> | |
95 | <term><filename>250-firmware-code-early.pcrlock</filename></term> | |
96 | ||
97 | <listitem><para>Firmware code measurements, as recorded to PCR 0 and 2, up to the separator | |
98 | measurement (see <filename>400-secureboot-separator.pcrlock.</filename> below). May be generated via | |
99 | <command>systemd-pcrlock lock-firmware-code</command>.</para> | |
100 | ||
101 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
102 | </varlistentry> | |
103 | ||
104 | <varlistentry> | |
105 | <term><filename>250-firmware-config-early.pcrlock</filename></term> | |
106 | ||
107 | <listitem><para>Firmware configuration measurements, as recorded to PCR 1 and 3, up to the separator | |
108 | measurement (see <filename>400-secureboot-separator.pcrlock.</filename> below). May be generated via | |
109 | <command>systemd-pcrlock lock-firmware-config</command>.</para> | |
110 | ||
111 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
112 | </varlistentry> | |
113 | ||
114 | <varlistentry> | |
115 | <term><filename>350-action-efi-application.pcrlock</filename></term> | |
116 | ||
117 | <listitem><para>The EFI "Application" measurement done once by the firmware. Statically defined.</para> | |
118 | ||
119 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
120 | </varlistentry> | |
121 | ||
122 | <varlistentry> | |
123 | <term><filename>400-secureboot-separator.pcrlock</filename></term> | |
124 | ||
125 | <listitem><para>The EFI "separator" measurement on PCR 7 done once by the firmware to indicate where | |
126 | firmware control transitions into boot loader/OS control. Statically defined.</para> | |
127 | ||
128 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
129 | </varlistentry> | |
130 | ||
131 | <varlistentry> | |
132 | <term><filename>500-separator.pcrlock</filename></term> | |
133 | ||
134 | <listitem><para>The EFI "separator" measurements on PCRs 0-6 done once by the firmware to indicate | |
135 | where firmware control transitions into boot loader/OS control. Statically defined.</para> | |
136 | ||
137 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
138 | </varlistentry> | |
139 | ||
140 | <varlistentry> | |
141 | <term><filename>550-firmware-code-late.pcrlock</filename></term> | |
142 | ||
143 | <listitem><para>Firmware code measurements, as recorded to PCR 0 and 2, after the separator | |
144 | measurement (see <filename>400-secureboot-separator.pcrlock.</filename> above). May be generated via | |
145 | <command>systemd-pcrlock lock-firmware-code</command>.</para> | |
146 | ||
147 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
148 | </varlistentry> | |
149 | ||
150 | <varlistentry> | |
151 | <term><filename>550-firmware-config-late.pcrlock</filename></term> | |
152 | ||
153 | <listitem><para>Firmware configuration measurements, as recorded to PCR 1 and 3, after the separator | |
154 | measurement (see <filename>400-secureboot-separator.pcrlock.</filename> above). May be generated via | |
155 | <command>systemd-pcrlock lock-firmware-config</command>.</para> | |
156 | ||
157 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
158 | </varlistentry> | |
159 | ||
160 | <varlistentry> | |
161 | <term><filename>600-gpt.pcrlock</filename></term> | |
162 | ||
163 | <listitem><para>The GPT partition table of the booted medium, as recorded to PCR 5 by the | |
164 | firmware. May be generated via <command>systemd-pcrlock lock-gpt</command>.</para> | |
165 | ||
166 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
167 | </varlistentry> | |
168 | ||
169 | <varlistentry> | |
170 | <term><filename>620-secureboot-authority.pcrlock</filename></term> | |
171 | ||
172 | <listitem><para>The SecureBoot authority, as recorded to PCR 7. May be generated via | |
173 | <command>systemd-pcrlock lock-secureboot-authority</command>.</para> | |
174 | ||
175 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
176 | </varlistentry> | |
177 | ||
178 | <varlistentry> | |
179 | <term><filename>700-action-efi-exit-boot-services.pcrlock</filename></term> | |
180 | ||
181 | <listitem><para>The EFI action generated when <function>ExitBootServices()</function> is generated, | |
182 | i.e. the UEFI environment is left and the OS takes over. Covers the PCR 5 measurement. Statically | |
183 | defined.</para> | |
184 | ||
185 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
186 | </varlistentry> | |
187 | ||
188 | <varlistentry> | |
189 | <term><filename>710-kernel-cmdline.pcrlock</filename></term> | |
190 | ||
191 | <listitem><para>The kernel command line, as measured by the Linux kernel to PCR 9. May be generated | |
192 | via <command>systemd-pcrlock lock-kernel-cmdline</command>.</para> | |
193 | ||
194 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
195 | </varlistentry> | |
196 | ||
197 | <varlistentry> | |
198 | <term><filename>720-kernel-initrd.pcrlock</filename></term> | |
199 | ||
200 | <listitem><para>The kernel initrd, as measured by the Linux kernel to PCR 9. May be generated | |
201 | via <command>systemd-pcrlock lock-kernel-initrd</command>.</para> | |
202 | ||
203 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
204 | </varlistentry> | |
205 | ||
206 | <varlistentry> | |
207 | <term><filename>750-enter-initrd.pcrlock</filename></term> | |
208 | ||
209 | <listitem><para>The measurement to PCR 11 | |
210 | <citerefentry><refentrytitle>systemd-pcrphase-initrd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
211 | makes when the initrd initializes. Statically defined.</para> | |
212 | ||
213 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
214 | </varlistentry> | |
215 | ||
216 | <varlistentry> | |
217 | <term><filename>800-leave-initrd.pcrlock</filename></term> | |
218 | ||
219 | <listitem><para>The measurement to PCR 11 | |
220 | <citerefentry><refentrytitle>systemd-pcrphase-initrd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
221 | makes when the initrd finishes. Statically defined.</para> | |
222 | ||
223 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
224 | </varlistentry> | |
225 | ||
226 | <varlistentry> | |
227 | <term><filename>820-machine-id.pcrlock</filename></term> | |
228 | ||
229 | <listitem><para>The measurement to PCR 15 | |
230 | <citerefentry><refentrytitle>systemd-pcrmachine.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
231 | makes at boot, covering <filename>/etc/machine-id</filename> contents. May be generated via | |
232 | <command>systemd-pcrlock lock-machine-id</command>.</para> | |
233 | ||
234 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
235 | </varlistentry> | |
236 | ||
237 | <varlistentry> | |
238 | <term><filename>830-root-file-system.pcrlock</filename></term> | |
239 | ||
240 | <listitem><para>The measurement to PCR 15 | |
241 | <citerefentry><refentrytitle>systemd-pcrfs-root.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
242 | makes at boot, covering the root file system identity. May be generated | |
243 | via <command>systemd-pcrlock lock-file-system</command>.</para> | |
244 | ||
245 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
246 | </varlistentry> | |
247 | ||
248 | <varlistentry> | |
249 | <term><filename>850-sysinit.pcrlock</filename></term> | |
250 | ||
251 | <listitem><para>The measurement to PCR 11 | |
252 | <citerefentry><refentrytitle>systemd-pcrphase-sysinit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
253 | makes when the main userspace did basic initialization and will now proceed to start regular system | |
254 | services. Statically defined.</para> | |
255 | ||
256 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
257 | </varlistentry> | |
258 | ||
259 | <varlistentry> | |
260 | <term><filename>900-ready.pcrlock</filename></term> | |
261 | ||
262 | <listitem><para>The measurement to PCR 11 | |
263 | <citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
264 | makes when the system fully booted up. Statically defined.</para> | |
265 | ||
266 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
267 | </varlistentry> | |
268 | ||
269 | <varlistentry> | |
270 | <term><filename>950-shutdown.pcrlock</filename></term> | |
271 | ||
272 | <listitem><para>The measurement to PCR 11 | |
273 | <citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
274 | makes when the system begins shutdown. Statically defined.</para> | |
275 | ||
276 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
277 | </varlistentry> | |
278 | ||
279 | <varlistentry> | |
280 | <term><filename>990-final.pcrlock</filename></term> | |
281 | ||
282 | <listitem><para>The measurement to PCR 11 | |
283 | <citerefentry><refentrytitle>systemd-pcrphase-sysinit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
284 | makes when the system is close to finishing shutdown. Statically defined.</para> | |
285 | ||
286 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
287 | </varlistentry> | |
288 | </variablelist> | |
289 | </refsect1> | |
290 | ||
291 | <refsect1> | |
292 | <title>See Also</title> | |
13a69c12 DT |
293 | <para><simplelist type="inline"> |
294 | <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
295 | <member><citerefentry><refentrytitle>systemd-pcrlock</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
296 | </simplelist></para> | |
e2062109 LP |
297 | </refsect1> |
298 | ||
299 | </refentry> |