]>
Commit | Line | Data |
---|---|---|
e2062109 LP |
1 | <?xml version="1.0"?> |
2 | <!--*-nxml-*--> | |
3 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
eea10b26 | 4 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
e2062109 | 5 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
ec3cf73f ZJS |
6 | <refentry id="systemd-pcrlock" conditional='ENABLE_BOOTLOADER HAVE_OPENSSL HAVE_TPM2' |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
e2062109 LP |
8 | |
9 | <refentryinfo> | |
10 | <title>systemd-pcrlock</title> | |
11 | <productname>systemd</productname> | |
12 | </refentryinfo> | |
13 | ||
14 | <refmeta> | |
15 | <refentrytitle>systemd-pcrlock</refentrytitle> | |
16 | <manvolnum>8</manvolnum> | |
17 | </refmeta> | |
18 | ||
19 | <refnamediv> | |
20 | <refname>systemd-pcrlock</refname> | |
21 | <refname>systemd-pcrlock-file-system.service</refname> | |
22 | <refname>systemd-pcrlock-firmware-code.service</refname> | |
23 | <refname>systemd-pcrlock-firmware-config.service</refname> | |
24 | <refname>systemd-pcrlock-machine-id.service</refname> | |
25 | <refname>systemd-pcrlock-make-policy.service</refname> | |
26 | <refname>systemd-pcrlock-secureboot-authority.service</refname> | |
27 | <refname>systemd-pcrlock-secureboot-policy.service</refname> | |
28 | <refpurpose>Analyze and predict TPM2 PCR states and generate an access policy from the prediction</refpurpose> | |
29 | </refnamediv> | |
30 | ||
31 | <refsynopsisdiv> | |
32 | <cmdsynopsis> | |
dfa6c32a | 33 | <command>/usr/lib/systemd/systemd-pcrlock</command> <arg choice="opt" rep="repeat">OPTIONS</arg> |
e2062109 LP |
34 | </cmdsynopsis> |
35 | </refsynopsisdiv> | |
36 | ||
37 | <refsect1> | |
38 | <title>Description</title> | |
39 | ||
40 | <para>Note: this command is experimental for now. While it is likely to become a regular component of | |
41 | systemd, it might still change in behaviour and interface.</para> | |
42 | ||
43 | <para><command>systemd-pcrlock</command> is a tool that may be used to analyze and predict TPM2 PCR | |
44 | measurements, and generate TPM2 access policies from the prediction which it stores in a TPM2 NV index | |
45 | (i.e. in the TPM2 non-volatile memory). This may then be used to restrict access to TPM2 objects (such as | |
46 | disk encryption keys) to system boot-ups in which only specific, trusted components are used.</para> | |
47 | ||
48 | <para><command>systemd-pcrlock</command> uses as input for its analysis and prediction:</para> | |
49 | ||
50 | <itemizedlist> | |
51 | <listitem><para>The UEFI firmware TPM2 event log | |
52 | (i.e. <filename>/sys/kernel/security/tpm0/binary_bios_measurements</filename>) of the current | |
53 | boot.</para></listitem> | |
54 | ||
55 | <listitem><para>The userspace TPM2 event log | |
56 | (i.e. <filename>/run/log/systemd/tpm2-measure.log</filename>) of the current | |
57 | boot.</para></listitem> | |
58 | ||
59 | <listitem><para>The current PCR state of the TPM2 chip.</para></listitem> | |
60 | ||
61 | <listitem><para>Boot component definition files (<filename>*.pcrlock</filename> and | |
62 | <filename>*.pcrlock.d/*.pcrlock</filename>, see | |
63 | <citerefentry><refentrytitle>systemd.pcrlock</refentrytitle><manvolnum>5</manvolnum></citerefentry>) | |
64 | that each define expected measurements for one component of the boot process, permitting alternative | |
c309b9e9 | 65 | variants for each. (Variants may be used to bless multiple kernel versions or boot loader versions |
e2062109 LP |
66 | at the same time.)</para></listitem> |
67 | </itemizedlist> | |
68 | ||
69 | <para>It uses these inputs to generate a combined event log, validating it against the PCR states. It | |
70 | then attempts to recognize event log records and matches them against the defined components. For each PCR | |
71 | where this can be done comprehensively (i.e. where all listed records and all defined components have | |
72 | been matched) this may then be used to predict future PCR measurements, taking the alternative variants | |
73 | defined for each component into account. This prediction may then be converted into a TPM2 access policy | |
74 | (consisting of TPM2 <function>PolicyPCR</function> and <function>PolicyOR</function> items), which is | |
75 | then stored in an NV index in the TPM2. This may be used to then lock secrets (such as disk encryption | |
76 | keys) to these policies (via a TPM2 <function>PolicyAuthorizeNV</function> policy).</para> | |
77 | ||
78 | <para>Use tools such as | |
79 | <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
80 | or <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry> to | |
81 | bind disk encryption to such a <command>systemd-pcrlock</command> TPM2 policy. Specifically, see the | |
82 | <option>--tpm2-pcrlock=</option> switches of these tools.</para> | |
83 | ||
84 | <para>The access policy logic requires a TPM2 device that implements the | |
85 | <literal>PolicyAuthorizeNV</literal> command, i.e. implements TPM 2.0 version 1.38 or newer.</para> | |
86 | </refsect1> | |
87 | ||
88 | <refsect1> | |
89 | <title>Commands</title> | |
90 | ||
91 | <para>The following commands are understood:</para> | |
92 | ||
93 | <variablelist> | |
94 | <varlistentry> | |
95 | <term><command>log</command></term> | |
96 | ||
97 | <listitem><para>This reads the combined TPM2 event log, validates it, matches it against the current | |
98 | PCR values, and outputs both in tabular form. Combine with <option>--json=</option> to generate | |
99 | output in JSON format.</para> | |
100 | ||
101 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
102 | </varlistentry> | |
103 | ||
104 | <varlistentry> | |
105 | <term><command>cel</command></term> | |
106 | ||
107 | <listitem><para>This reads the combined TPM2 event log and writes it to STDOUT in <ulink | |
108 | url="https://trustedcomputinggroup.org/resource/canonical-event-log-format/">TCG Common Event Log | |
109 | Format (CEL-JSON)</ulink> format.</para> | |
110 | ||
111 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
112 | </varlistentry> | |
113 | ||
114 | <varlistentry> | |
115 | <term><command>list-components</command></term> | |
116 | ||
117 | <listitem><para>Shows a list of component definitions and their variants, i.e. the | |
118 | <filename>*.pcrlock</filename> files discovered in <filename>/var/lib/pcrlock.d/</filename>, | |
119 | <filename>/usr/lib/pcrlock.d/</filename>, and the other supported directories. See | |
120 | <citerefentry><refentrytitle>systemd.pcrlock</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
121 | for details on these files and the full list of directories searched.</para> | |
122 | ||
123 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
124 | </varlistentry> | |
125 | ||
126 | <varlistentry> | |
127 | <term><command>predict</command></term> | |
128 | ||
129 | <listitem><para>Predicts the PCR state on future boots. This will analyze the TPM2 event log as | |
130 | described above, recognize components, and then generate all possible resulting PCR values for all | |
131 | combinations of component variants. Note that no prediction is made for PCRs whose value does not | |
132 | match the event log records, for which unrecognized measurements are discovered or for which | |
133 | components are defined that cannot be found in the event log. This is a safety measure to ensure that | |
134 | any generated access policy can be fulfilled correctly on current and future boots.</para> | |
135 | ||
136 | <xi:include href="version-info.xml" xpointer="v255"/> | |
137 | </listitem> | |
138 | </varlistentry> | |
139 | ||
140 | <varlistentry> | |
141 | <term><command>make-policy</command></term> | |
142 | ||
143 | <listitem><para>This predicts the PCR state for future boots, much like the | |
144 | <command>predict</command> command above. It then uses this data to generate a TPM2 access policy | |
145 | which it stores in a TPM2 NV index. The prediction and information about the used TPM2 and its NV | |
146 | index are written to <filename>/var/lib/systemd/pcrlock.json</filename>.</para> | |
147 | ||
148 | <para>The NV index is allocated on first invocation, and updated on subsequent invocations.</para> | |
149 | ||
150 | <para>The NV index contents may be changed (and thus the policy stored in it updated) by providing an | |
151 | access PIN. This PIN is normally generated automatically and stored in encrypted form (with an access | |
152 | policy binding it to the NV index itself) in the aforementioned JSON policy file. This PIN may be | |
153 | chosen by the user, via the <option>--recovery-pin=</option> switch. If specified it may be used as | |
154 | alternative path of access to update the policy.</para> | |
155 | ||
156 | <para>If the new prediction matches the old this command terminates quickly and executes no further | |
157 | operation. (Unless <option>--force</option> is specified, see below.)</para> | |
158 | ||
452486cd LP |
159 | <para>Starting with v256, a copy of the <filename>/var/lib/systemd/pcrlock.json</filename> policy |
160 | file is encoded in a credential (see | |
161 | <citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry> for | |
162 | details) and written to the EFI System Partition or XBOOTLDR partition, in the | |
163 | <filename>/loader/credentials/</filename> subdirectory. There it is picked up at boot by | |
164 | <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> and | |
165 | passed to the invoked initrd, where it can be used to unlock the root file system (which typically | |
166 | contains <filename>/var/</filename>, which is where the primary copy of the policy is located, which | |
167 | hence cannot be used to unlock the root file system). The credential file is named after the boot | |
168 | entry token of the installation (see | |
169 | <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>), which | |
170 | is configurable via the <option>--entry-token=</option> switch, see below.</para> | |
171 | ||
e2062109 LP |
172 | <xi:include href="version-info.xml" xpointer="v255"/> |
173 | </listitem> | |
174 | </varlistentry> | |
175 | ||
176 | <varlistentry> | |
177 | <term><command>remove-policy</command></term> | |
178 | ||
179 | <listitem><para>Removes a previously generated policy. Deletes the | |
180 | <filename>/var/lib/systemd/pcrlock.json</filename> file, and deallocates the NV index.</para> | |
181 | ||
182 | <xi:include href="version-info.xml" xpointer="v255"/> | |
183 | </listitem> | |
184 | </varlistentry> | |
185 | ||
186 | <varlistentry> | |
187 | <term><command>lock-firmware-code</command></term> | |
188 | <term><command>unlock-firmware-code</command></term> | |
189 | ||
190 | <listitem><para>Generates/removes <filename>.pcrlock</filename> files based on the TPM2 event log of | |
191 | the current boot covering all records for PCRs 0 ("platform-code") and 2 ("external-code").</para> | |
192 | ||
193 | <para>This operation allows locking the boot process to the current version of the firmware of the | |
194 | system and its extension cards. This operation should only be used if the system vendor does not | |
195 | provide suitable pcrlock data ahead of time.</para> | |
196 | ||
197 | <para>Note that this data only matches the current version of the firmware. If a firmware update is | |
198 | applied this data will be out-of-date and any access policy generated from it will no longer pass. It | |
199 | is thus recommended to invoke <command>unlock-firmware-code</command> before doing a firmware update, | |
200 | followed by <command>make-policy</command> to refresh the policy.</para> | |
201 | ||
202 | <para><command>systemd-pcrlock lock-firmware-code</command> is invoked automatically at boot via the | |
203 | <filename>systemd-pcrlock-firmware-code.service</filename> unit, if enabled. This ensures that an | |
204 | access policy managed by <command>systemd-pcrlock</command> is automatically locked to the new | |
205 | firmware version whenever the policy has been relaxed temporarily, in order to cover for firmware | |
206 | updates, as described above.</para> | |
207 | ||
208 | <para>The files are only generated from the event log if the event log matches the current TPM2 PCR | |
209 | state.</para> | |
210 | ||
211 | <para>This writes/removes the files | |
212 | <filename>/var/lib/pcrlock.d/250-firmware-code-early.pcrlock.d/generated.pcrlock</filename> and | |
213 | <filename>/var/lib/pcrlock.d/550-firmware-code-late.pcrlock.d/generated.pcrlock</filename>.</para> | |
214 | ||
215 | <xi:include href="version-info.xml" xpointer="v255"/> | |
216 | </listitem> | |
217 | </varlistentry> | |
218 | ||
219 | <varlistentry> | |
220 | <term><command>lock-firmware-config</command></term> | |
221 | <term><command>unlock-firmware-config</command></term> | |
222 | ||
223 | <listitem><para>This is similar to | |
224 | <command>lock-firmware-code</command>/<command>unlock-firmware-code</command> but locks down the | |
225 | firmware configuration, i.e. PCRs 1 ("platform-config") and 3 ("external-config").</para> | |
226 | ||
227 | <para>This functionality should be used with care as in most scenarios a minor firmware configuration | |
228 | change should not invalidate access policies to TPM2 objects. Also note that some systems measure | |
229 | unstable and unpredictable information (e.g. current CPU voltages, temperatures, as part of SMBIOS | |
230 | data) to these PCRs, which means this form of lockdown cannot be used reliably on such systems. Use | |
231 | this functionality only if the system and hardware is well known and does not suffer by these | |
232 | limitations, for example in virtualized environments.</para> | |
233 | ||
234 | <para>Use <command>unlock-firmware-config</command> before making firmware configuration changes. If | |
235 | the <filename>systemd-pcrlock-firmware-config.service</filename> unit is enabled it will | |
236 | automatically generate a pcrlock file from the new measurements.</para> | |
237 | ||
238 | <para>This writes/removes the files | |
239 | <filename>/var/lib/pcrlock.d/250-firmware-config-early.pcrlock.d/generated.pcrlock</filename> and | |
240 | <filename>/var/lib/pcrlock.d/550-firmware-config-late.pcrlock.d/generated.pcrlock</filename>.</para> | |
241 | ||
242 | <xi:include href="version-info.xml" xpointer="v255"/> | |
243 | </listitem> | |
244 | </varlistentry> | |
245 | ||
246 | <varlistentry> | |
247 | <term><command>lock-secureboot-policy</command></term> | |
248 | <term><command>unlock-secureboot-policy</command></term> | |
249 | ||
250 | <listitem><para>Generates/removes a <filename>.pcrlock</filename> file based on the SecureBoot policy | |
251 | currently enforced. This looks at the SecureBoot, PK, KEK, db, dbx, dbt, dbr EFI variables and | |
252 | predicts their measurements to PCR 7 ("secure-boot-policy") on the next boot.</para> | |
253 | ||
254 | <para>Use <command>unlock-firmware-config</command> before applying SecureBoot policy updates. If | |
255 | the <filename>systemd-pcrlock-secureboot-policy.service</filename> unit is enabled it will | |
256 | automatically generate a pcrlock file from the policy discovered.</para> | |
257 | ||
258 | <para>This writes/removes the file | |
259 | <filename>/var/lib/pcrlock.d/230-secureboot-policy.pcrlock.d/generated.pcrlock</filename>.</para> | |
260 | ||
261 | <xi:include href="version-info.xml" xpointer="v255"/> | |
262 | </listitem> | |
263 | </varlistentry> | |
264 | ||
265 | <varlistentry> | |
266 | <term><command>lock-secureboot-authority</command></term> | |
267 | <term><command>unlock-secureboot-authority</command></term> | |
268 | ||
269 | <listitem><para>Generates/removes a <filename>.pcrlock</filename> file based on the SecureBoot | |
270 | authorities used to validate the boot path. SecureBoot authorities are the specific SecureBoot | |
271 | database entries that where used to validate the UEFI PE binaries executed at boot. This looks at the | |
272 | event log of the current boot, and uses relevant measurements on PCR 7 | |
273 | ("secure-boot-policy").</para> | |
274 | ||
275 | <para>This writes/removes the file | |
276 | <filename>/var/lib/pcrlock.d/620-secureboot-authority.pcrlock.d/generated.pcrlock</filename>.</para> | |
277 | ||
278 | <xi:include href="version-info.xml" xpointer="v255"/> | |
279 | </listitem> | |
280 | </varlistentry> | |
281 | ||
282 | <varlistentry> | |
932abebf | 283 | <term><command>lock-gpt</command> <optional><replaceable>DEVICE</replaceable></optional></term> |
e2062109 LP |
284 | <term><command>unlock-gpt</command></term> |
285 | ||
286 | <listitem><para>Generates/removes a <filename>.pcrlock</filename> file based on the GPT partition | |
287 | table of the specified disk. If no disk is specified automatically determines the block device | |
288 | backing the root file system. This locks the state of the disk partitioning of the booted medium, | |
289 | which firmware measures to PCR 5 ("boot-loader-config").</para> | |
290 | ||
291 | <para>This writes/removes the file | |
292 | <filename>/var/lib/pcrlock.d/600-gpt.pcrlock.d/generated.pcrlock</filename>.</para> | |
293 | ||
294 | <xi:include href="version-info.xml" xpointer="v255"/> | |
295 | </listitem> | |
296 | </varlistentry> | |
297 | ||
298 | <varlistentry> | |
932abebf | 299 | <term><command>lock-pe</command> <optional><replaceable>BINARY</replaceable></optional></term> |
e2062109 LP |
300 | <term><command>unlock-pe</command></term> |
301 | ||
302 | <listitem><para>Generates/removes a <filename>.pcrlock</filename> file based on the specified PE | |
303 | binary. This is useful for predicting measurements the firmware makes to PCR 4 ("boot-loader-code") | |
304 | if the specified binary is part of the UEFI boot process. Use this on boot loader binaries and | |
305 | suchlike. Use <command>lock-uki</command> (see below) for PE binaries that are unified kernel images | |
306 | (UKIs).</para> | |
307 | ||
308 | <para>Expects a path to the PE binary as argument. If not specified, reads the binary from STDIN | |
309 | instead.</para> | |
310 | ||
311 | <para>The pcrlock file to write must be specified via the <option>--pcrlock=</option> switch.</para> | |
312 | ||
313 | <xi:include href="version-info.xml" xpointer="v255"/> | |
314 | </listitem> | |
315 | </varlistentry> | |
316 | ||
317 | <varlistentry> | |
932abebf | 318 | <term><command>lock-uki</command> <optional><replaceable>UKI</replaceable></optional></term> |
e2062109 LP |
319 | <term><command>unlock-uki</command></term> |
320 | ||
321 | <listitem><para>Generates/removes a <filename>.pcrlock</filename> file based on the specified UKI PE | |
322 | binary. This is useful for predicting measurements the firmware makes to PCR 4 ("boot-loader-code"), | |
323 | and <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> | |
324 | makes to PCR 11 ("kernel-boot"), if the specified UKI is booted. This is a superset of | |
325 | <command>lock-pe</command>.</para> | |
326 | ||
327 | <para>Expects a path to the UKI PE binary as argument. If not specified, reads the binary from STDIN | |
328 | instead.</para> | |
329 | ||
330 | <para>The pcrlock file to write must be specified via the <option>--pcrlock=</option> switch.</para> | |
331 | ||
332 | <xi:include href="version-info.xml" xpointer="v255"/> | |
333 | </listitem> | |
334 | </varlistentry> | |
335 | ||
336 | <varlistentry> | |
337 | <term><command>lock-machine-id</command></term> | |
338 | <term><command>unlock-machine-id</command></term> | |
339 | ||
340 | <listitem><para>Generates/removes a <filename>.pcrlock</filename> file based on | |
341 | <filename>/etc/machine-id</filename>. This is useful for predicting measurements | |
342 | <citerefentry><refentrytitle>systemd-pcrmachine.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
343 | makes to PCR 15 ("system-identity").</para> | |
344 | ||
345 | <para>This writes/removes the file | |
346 | <filename>/var/lib/pcrlock.d/820-machine-id.pcrlock</filename>.</para> | |
347 | ||
348 | <xi:include href="version-info.xml" xpointer="v255"/> | |
349 | </listitem> | |
350 | </varlistentry> | |
351 | ||
352 | <varlistentry> | |
932abebf DT |
353 | <term><command>lock-file-system</command> <optional><replaceable>PATH</replaceable></optional></term> |
354 | <term><command>unlock-file-system</command> <optional><replaceable>PATH</replaceable></optional></term> | |
e2062109 LP |
355 | |
356 | <listitem><para>Generates/removes a <filename>.pcrlock</filename> file based on file system | |
357 | identity. This is useful for predicting measurements | |
358 | <citerefentry><refentrytitle>systemd-pcrfs@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
359 | makes to PCR 15 ("system-identity") for the root and <filename>/var/</filename> file systems.</para> | |
360 | ||
361 | <para>This writes/removes the files | |
362 | <filename>/var/lib/pcrlock.d/830-root-file-system.pcrlock</filename> and | |
363 | <filename>/var/lib/pcrlock.d/840-file-system-<replaceable>path</replaceable>.pcrlock</filename>.</para> | |
364 | ||
365 | <xi:include href="version-info.xml" xpointer="v255"/> | |
366 | </listitem> | |
367 | </varlistentry> | |
368 | ||
369 | <varlistentry> | |
932abebf | 370 | <term><command>lock-kernel-cmdline</command> <optional><replaceable>FILE</replaceable></optional></term> |
e2062109 LP |
371 | <term><command>unlock-kernel-cmdline</command></term> |
372 | ||
373 | <listitem><para>Generates/removes a <filename>.pcrlock</filename> file based on | |
374 | <filename>/proc/cmdline</filename> (or the specified file if given). This is useful for predicting | |
375 | measurements the Linux kernel makes to PCR 9 ("kernel-initrd").</para> | |
376 | ||
377 | <para>This writes/removes the file | |
378 | <filename>/var/lib/pcrlock.d/710-kernel-cmdline.pcrlock/generated.pcrlock</filename>.</para> | |
379 | ||
380 | <xi:include href="version-info.xml" xpointer="v255"/> | |
381 | </listitem> | |
382 | </varlistentry> | |
383 | ||
384 | <varlistentry> | |
385 | <term><command>lock-kernel-initrd</command> <replaceable>FILE</replaceable></term> | |
386 | <term><command>unlock-kernel-initrd</command></term> | |
387 | ||
388 | <listitem><para>Generates/removes a <filename>.pcrlock</filename> file based on a kernel initrd cpio | |
389 | archive. This is useful for predicting measurements the Linux kernel makes to PCR 9 | |
390 | ("kernel-initrd"). Do not use for <command>systemd-stub</command> UKIs, as the initrd is combined | |
391 | dynamically from various sources and hence does not take a single input, like this command.</para> | |
392 | ||
393 | <para>This writes/removes the file | |
394 | <filename>/var/lib/pcrlock.d/720-kernel-initrd.pcrlock/generated.pcrlock</filename>.</para> | |
395 | ||
396 | <xi:include href="version-info.xml" xpointer="v255"/> | |
397 | </listitem> | |
398 | </varlistentry> | |
399 | ||
400 | <varlistentry> | |
932abebf | 401 | <term><command>lock-raw</command> <optional><replaceable>FILE</replaceable></optional></term> |
e2062109 LP |
402 | <term><command>unlock-raw</command></term> |
403 | ||
404 | <listitem><para>Generates/removes a <filename>.pcrlock</filename> file based on raw binary data. The | |
405 | data is either read from the specified file or from STDIN (if none is specified). This requires that | |
cc59d101 | 406 | <option>--pcrs=</option> is specified. The generated .pcrlock file is written to the file specified |
e2062109 LP |
407 | via <option>--pcrlock=</option> or to STDOUT (if none is specified).</para> |
408 | ||
409 | <xi:include href="version-info.xml" xpointer="v255"/> | |
410 | </listitem> | |
411 | </varlistentry> | |
412 | ||
413 | </variablelist> | |
414 | </refsect1> | |
415 | ||
416 | <refsect1> | |
417 | <title>Options</title> | |
418 | ||
419 | <para>The following options are understood:</para> | |
420 | ||
421 | <variablelist> | |
422 | <varlistentry> | |
423 | <term><option>--raw-description</option></term> | |
424 | ||
425 | <listitem><para>When displaying the TPM2 event log do not attempt to decode the records to provide a | |
426 | friendly event log description string. Instead, show the binary payload data in escaped form.</para> | |
427 | ||
428 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
429 | </varlistentry> | |
430 | ||
431 | <varlistentry> | |
432 | <term><option>--pcr=</option></term> | |
433 | ||
434 | <listitem><para>Specifies the PCR number to use. May be specified more than once to select multiple | |
435 | PCRs.</para> | |
436 | ||
437 | <para>This is used by <command>lock-raw</command> and <command>lock-pe</command> to select the | |
438 | PCR to lock against.</para> | |
439 | ||
440 | <para>If used with <command>predict</command> and <command>make-policy</command> this will override | |
441 | which PCRs to include in the prediction and policy. If unspecified this defaults to PCRs 0-5, 7, | |
442 | 11-15. Note that these commands will not include any PCRs in the prediction/policy (even if specified | |
443 | explicitly) if there are measurements in the event log that do not match the current PCR value, or | |
444 | there are unrecognized measurements in the event log, or components define measurements not seen in | |
445 | the event log.</para> | |
446 | ||
447 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
448 | </varlistentry> | |
449 | ||
450 | <varlistentry> | |
451 | <term><option>--nv-index=</option></term> | |
452 | ||
cc59d101 | 453 | <listitem><para>Specifies the NV index to store the policy in. Honoured by |
e2062109 LP |
454 | <command>make-policy</command>. If not specified the command will automatically pick a free NV |
455 | index.</para> | |
456 | ||
457 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
458 | </varlistentry> | |
459 | ||
460 | <varlistentry> | |
461 | <term><option>--components=</option></term> | |
462 | ||
463 | <listitem><para>Takes a path to read <filename>*.pcrlock</filename> and | |
464 | <filename>*.pcrlock.d/*.pcrlock</filename> files from. May be used more than once to specify multiple | |
465 | such directories. If not specified defaults to <filename>/etc/pcrlock.d/</filename>, | |
466 | <filename>/run/pcrlock.d/</filename>, <filename>/var/lib/pcrlock.d/</filename>, | |
467 | <filename>/usr/local/pcrlock.d/</filename>, <filename>/usr/lib/pcrlock.d/</filename>.</para> | |
468 | ||
469 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
470 | </varlistentry> | |
471 | ||
472 | <varlistentry> | |
473 | <term><option>--location=</option></term> | |
474 | ||
475 | <listitem><para>Takes either a string or a colon-separated pair of strings. Configures up to which | |
476 | point in the sorted list of defined components to analyze/predict PCRs to. Typically, the | |
477 | <command>systemd-pcrlock</command> tool is invoked from a fully booted system after boot-up and | |
478 | before shutdown. This means various components that are defined for shutdown have not been measured | |
dfb4a66f LB |
479 | yet, and should not be searched for. This option allows one to restrict which components are |
480 | considered for analysis (taking only components before some point into account, ignoring components | |
481 | after them). The expected string is ordered against the filenames of the components defined. Any | |
482 | components with a lexicographically later name are ignored. This logic applies to the | |
483 | <command>log</command>, <command>predict</command>, and <command>make-policy</command> verbs. If a | |
484 | colon-separated pair of strings are specified then they select which phases of the boot to include | |
485 | in the prediction/policy. The first string defines where the first prediction shall be made, and the | |
486 | second string defines where the last prediction shall be made. All such predictions are then combined | |
487 | into one set.</para> | |
e2062109 LP |
488 | |
489 | <para>If used with <command>list-components</command> the selected location range will be highlighted | |
490 | in the component list.</para> | |
491 | ||
492 | <para>Defaults to <literal>760-:940-</literal>, which means the policies generated by default will | |
493 | basically cover the whole runtime of the OS userspace, from the initrd (as <literal>760-</literal> | |
494 | closely follows <filename>750-enter-initrd.pcrlock</filename>) until (and including) the main runtime | |
495 | of the system (as <literal>940-</literal> is closely followed by | |
496 | <filename>950-shutdown.pcrlock</filename>). See | |
497 | <citerefentry><refentrytitle>systemd.pcrlock</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
498 | for a full list of well-known components, that illustrate where this range is placed by | |
499 | default.</para> | |
500 | ||
501 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
502 | </varlistentry> | |
503 | ||
504 | <varlistentry> | |
505 | <term><option>--recovery-pin=</option></term> | |
506 | ||
43a59b8b LP |
507 | <listitem><para>Takes one of <literal>hide</literal>, <literal>show</literal> or |
508 | <literal>query</literal>. Defaults to <literal>hide</literal>. Honoured by | |
509 | <command>make-policy</command>. If <literal>query</literal>, will query the user for a PIN to unlock | |
510 | the TPM2 NV index with. If no policy was created before, this PIN is used to protect the newly | |
511 | allocated NV index. If a policy has been created before, the PIN is used to unlock write access to | |
512 | the NV index. If either <literal>hide</literal> or <literal>show</literal> is used, a PIN is | |
513 | automatically generated, and — only in case of <literal>show</literal> — displayed on | |
514 | screen. Regardless if user supplied or automatically generated, it is stored in encrypted form in the | |
515 | policy metadata file. The recovery PIN may be used to regain write access to an NV index in case the | |
516 | access policy became out of date.</para> | |
e2062109 LP |
517 | |
518 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
519 | </varlistentry> | |
520 | ||
521 | <varlistentry> | |
522 | <term><option>--pcrlock=</option></term> | |
523 | ||
524 | <listitem><para>Takes a file system path as argument. If specified overrides where to write the | |
525 | generated pcrlock data to. Honoured by the various <command>lock-*</command> commands. If not | |
526 | specified, a default path is generally used, as documented above.</para> | |
527 | ||
528 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
529 | </varlistentry> | |
530 | ||
531 | <varlistentry> | |
532 | <term><option>--policy=</option></term> | |
533 | ||
534 | <listitem><para>Takes a file system path as argument. If specified overrides where to write pcrlock | |
535 | policy metadata to. If not specified defaults to | |
536 | <filename>/var/lib/systemd/pcrlock.json</filename>.</para> | |
537 | ||
538 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
539 | </varlistentry> | |
540 | ||
541 | <varlistentry> | |
542 | <term><option>--force</option></term> | |
543 | ||
544 | <listitem><para>If specified with <command>make-policy</command>, the predicted policy will be | |
545 | written to the NV index even if it is detected to be the same as the previously stored | |
546 | one.</para> | |
547 | ||
548 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
549 | </varlistentry> | |
550 | ||
452486cd LP |
551 | <varlistentry> |
552 | <term><option>--entry-token=</option></term> | |
553 | ||
554 | <listitem><para>Sets the boot entry token to use for the file name for the pcrlock policy credential | |
555 | in the EFI System Partition or XBOOTLDR partition. See the | |
556 | <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> option of | |
557 | the same regarding expected values. This switch has an effect on the | |
558 | <command>make-policy</command> command only.</para> | |
559 | ||
560 | <xi:include href="version-info.xml" xpointer="v256"/></listitem> | |
561 | </varlistentry> | |
562 | ||
e2062109 LP |
563 | <xi:include href="standard-options.xml" xpointer="json" /> |
564 | <xi:include href="standard-options.xml" xpointer="no-pager" /> | |
565 | <xi:include href="standard-options.xml" xpointer="help" /> | |
566 | <xi:include href="standard-options.xml" xpointer="version" /> | |
567 | </variablelist> | |
568 | </refsect1> | |
569 | ||
570 | <refsect1> | |
571 | <title>Exit status</title> | |
572 | ||
573 | <para>On success, 0 is returned, a non-zero failure code otherwise.</para> | |
574 | </refsect1> | |
575 | ||
576 | <refsect1> | |
577 | <title>See Also</title> | |
13a69c12 DT |
578 | <para><simplelist type="inline"> |
579 | <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
580 | <member><citerefentry><refentrytitle>systemd.pcrlock</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
581 | <member><citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
582 | <member><citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
583 | <member><citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
584 | <member><citerefentry><refentrytitle>systemd-pcrmachine.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
452486cd LP |
585 | <member><citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> |
586 | <member><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry></member> | |
587 | <member><citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
13a69c12 | 588 | </simplelist></para> |
e2062109 LP |
589 | </refsect1> |
590 | ||
591 | </refentry> |