man/systemd-pcrlock.xml

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