man/systemd-measure.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.5/docbookx.dtd">
   5 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   6 <refentry id="systemd-measure" xmlns:xi="http://www.w3.org/2001/XInclude" conditional='HAVE_TPM2'>
   7
   8   <refentryinfo>
   9     <title>systemd-measure</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>systemd-measure</refentrytitle>
  15     <manvolnum>1</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>systemd-measure</refname>
  20     <refpurpose>Pre-calculate and sign expected TPM2 PCR values for booted unified kernel images</refpurpose>
  21   </refnamediv>
  22
  23   <refsynopsisdiv>
  24     <cmdsynopsis>
  25       <command>/usr/lib/systemd/systemd-measure</command> <arg choice="opt" rep="repeat">OPTIONS</arg>
  26     </cmdsynopsis>
  27   </refsynopsisdiv>
  28
  29   <refsect1>
  30     <title>Description</title>
  31
  32     <para>Note: this command is experimental for now. While it is likely to become a regular component of
  33     systemd, it might still change in behaviour and interface.</para>
  34
  35     <para><command>systemd-measure</command> is a tool that may be used to pre-calculate and sign the
  36     expected TPM2 PCR 11 values that should be seen when a Linux <ulink
  37     url="https://uapi-group.org/specifications/specs/unified_kernel_image/">Unified Kernel Image
  38     (UKI)</ulink> based on
  39     <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> is
  40     booted up. It accepts paths to the ELF kernel image file, initrd image file, devicetree file, kernel
  41     command line file,
  42     <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file, boot
  43     splash file, and TPM2 PCR PEM public key file that make up the unified kernel image, and determines the
  44     PCR values expected to be in place after booting the image. Calculation starts with a zero-initialized
  45     PCR 11, and is executed in a fashion compatible with what <filename>systemd-stub</filename> does at boot.
  46     The result may optionally be signed cryptographically, to allow TPM2 policies that can only be unlocked
  47     if a certain set of kernels is booted, for which such a PCR signature can be provided.</para>
  48
  49     <para>It usually doesn't make sense to call this tool directly when constructing a UKI. Instead,
  50     <citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry> should be used;
  51     it will invoke <command>systemd-measure</command> and take care of embedding the resulting measurements
  52     into the UKI.</para>
  53   </refsect1>
  54
  55   <refsect1>
  56     <title>Commands</title>
  57
  58     <para>The following commands are understood:</para>
  59
  60     <variablelist>
  61       <varlistentry>
  62         <term><command>status</command></term>
  63
  64         <listitem><para>This is the default command if none is specified. This queries the local system's
  65         TPM2 PCR 11+12+13 values and displays them. The data is written in a similar format as the
  66         <command>calculate</command> command below, and may be used to quickly compare expectation with
  67         reality.</para>
  68
  69         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
  70       </varlistentry>
  71
  72       <varlistentry>
  73         <term><command>calculate</command></term>
  74
  75         <listitem><para>Pre-calculate the expected values seen in PCR register 11 after boot-up of a unified
  76         kernel image consisting of the components specified with <option>--linux=</option>,
  77         <option>--osrel=</option>, <option>--cmdline=</option>, <option>--initrd=</option>,
  78         <option>--splash=</option>, <option>--dtb=</option>, <option>--uname=</option>,
  79         <option>--sbat=</option>, <option>--pcrpkey=</option> see below. Only <option>--linux=</option> is
  80         mandatory. (Alternatively, specify <option>--current</option> to use the current values of PCR
  81         register 11 instead.)</para>
  82
  83         <xi:include href="version-info.xml" xpointer="v252"/>
  84         </listitem>
  85       </varlistentry>
  86
  87       <varlistentry>
  88         <term><command>sign</command></term>
  89
  90         <listitem><para>As with the <command>calculate</command> command, pre-calculate the expected value
  91         seen in TPM2 PCR register 11 after boot-up of a unified kernel image. Then, cryptographically sign
  92         the resulting values with the private/public key pair (RSA) configured via
  93         <option>--private-key=</option> and <option>--public-key=</option>. This will write a JSON object to
  94         standard output that contains signatures for all specified PCR banks (see the
  95         <option>--bank=</option> option below), which may be used to unlock encrypted credentials (see
  96         <citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry>) or
  97         LUKS volumes (see
  98         <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>).
  99         This allows binding secrets to a set of kernels for which such PCR 11 signatures can be
 100         provided.</para>
 101
 102         <para>Note that a TPM2 device must be available for this signing to take place, even though the
 103         result is not tied to any TPM2 device or its state.</para>
 104
 105         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 106       </varlistentry>
 107     </variablelist>
 108   </refsect1>
 109
 110   <refsect1>
 111     <title>Options</title>
 112
 113     <para>The following options are understood:</para>
 114
 115     <variablelist>
 116       <varlistentry>
 117         <term><option>--linux=<replaceable>PATH</replaceable></option></term>
 118         <term><option>--osrel=<replaceable>PATH</replaceable></option></term>
 119         <term><option>--cmdline=<replaceable>PATH</replaceable></option></term>
 120         <term><option>--initrd=<replaceable>PATH</replaceable></option></term>
 121         <term><option>--splash=<replaceable>PATH</replaceable></option></term>
 122         <term><option>--dtb=<replaceable>PATH</replaceable></option></term>
 123         <term><option>--uname=<replaceable>PATH</replaceable></option></term>
 124         <term><option>--sbat=<replaceable>PATH</replaceable></option></term>
 125         <term><option>--pcrpkey=<replaceable>PATH</replaceable></option></term>
 126
 127         <listitem><para>When used with the <command>calculate</command> or <command>sign</command> verb,
 128         configures the files to read the unified kernel image components from. Each option corresponds with
 129         the equally named section in the unified kernel PE file. The <option>--linux=</option> switch expects
 130         the path to the ELF kernel file that the unified PE kernel will wrap. All switches except
 131         <option>--linux=</option> are optional. Each option may be used at most once.</para>
 132
 133         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 134       </varlistentry>
 135
 136       <varlistentry>
 137         <term><option>--current</option></term>
 138         <listitem><para>When used with the <command>calculate</command> or <command>sign</command> verb,
 139         takes the PCR 11 values currently in effect for the system (which should typically reflect the hashes
 140         of the currently booted kernel). This can be used in place of <option>--linux=</option> and the other
 141         switches listed above.</para>
 142
 143         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 144       </varlistentry>
 145
 146       <varlistentry>
 147         <term><option>--bank=<replaceable>DIGEST</replaceable></option></term>
 148
 149         <listitem><para>Controls the PCR banks to pre-calculate the PCR values for – in case
 150         <command>calculate</command> or <command>sign</command> is invoked –, or the banks to show in the
 151         <command>status</command> output. May be used more then once to specify multiple banks. If not
 152         specified, defaults to the four banks <literal>sha1</literal>, <literal>sha256</literal>,
 153         <literal>sha384</literal>, <literal>sha512</literal>.</para>
 154
 155         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 156       </varlistentry>
 157
 158       <varlistentry>
 159         <term><option>--private-key=<replaceable>PATH</replaceable></option></term>
 160         <term><option>--public-key=<replaceable>PATH</replaceable></option></term>
 161
 162         <listitem><para>These switches take paths to a pair of PEM encoded RSA key files, for use with
 163         the <command>sign</command> command.</para>
 164
 165         <para>Note the difference between the <option>--pcrpkey=</option> and <option>--public-key=</option>
 166         switches. The former selects the data to include in the <literal>.pcrpkey</literal> PE section of the
 167         unified kernel image, the latter picks the public key of the key pair used to sign the resulting PCR
 168         11 values. The former is the key that the booted system will likely use to lock disk and credential
 169         encryption to, the latter is the key used for unlocking such resources again. Hence, typically the
 170         same PEM key should be supplied in both cases.</para>
 171
 172         <para>If the <option>--public-key=</option> is not specified but <option>--private-key=</option> is
 173         specified the public key is automatically derived from the private key.</para>
 174
 175         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 176       </varlistentry>
 177
 178       <varlistentry>
 179         <term><option>--tpm2-device=</option><replaceable>PATH</replaceable></term>
 180
 181         <listitem><para>Controls which TPM2 device to use. Expects a device node path referring to the TPM2
 182         chip (e.g. <filename>/dev/tpmrm0</filename>). Alternatively the special value <literal>auto</literal>
 183         may be specified, in order to automatically determine the device node of a suitable TPM2 device (of
 184         which there must be exactly one). The special value <literal>list</literal> may be used to enumerate
 185         all suitable TPM2 devices currently discovered.</para>
 186
 187         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 188       </varlistentry>
 189
 190       <varlistentry>
 191         <term><option>--phase=</option><replaceable>PHASE</replaceable></term>
 192
 193         <listitem><para>Controls which boot phases to calculate expected PCR 11 values for. This takes a
 194         series of colon-separated strings that encode boot "paths" for entering a specific phase of the boot
 195         process. Each of the specified strings is measured by the
 196         <filename>systemd-pcrphase-initrd.service</filename>,
 197         <filename>systemd-pcrphase-sysinit.service</filename>, and
 198         <citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 199         into PCR 11 during different milestones of the boot process. This switch may be specified multiple
 200         times to calculate PCR values for multiple boot phases at once. If not used defaults to
 201         <literal>enter-initrd</literal>, <literal>enter-initrd:leave-initrd</literal>,
 202         <literal>enter-initrd:leave-initrd:sysinit</literal>,
 203         <literal>enter-initrd:leave-initrd:sysinit:ready</literal>, i.e. calculates expected PCR values for
 204         the boot phase in the initrd, during early boot, during later boot, and during system runtime, but
 205         excluding the phases before the initrd or when shutting down. This setting is honoured both by
 206         <command>calculate</command> and <command>sign</command>. When used with the latter it's particularly
 207         useful for generating PCR signatures that can only be used for unlocking resources during specific
 208         parts of the boot process.</para>
 209
 210         <para>For further details about PCR boot phases, see
 211         <citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 212
 213         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 214       </varlistentry>
 215
 216       <varlistentry>
 217         <term><option>--append=</option><replaceable>PATH</replaceable></term>
 218
 219         <listitem><para>When generating a PCR JSON signature (via the <command>sign</command> command),
 220         combine it with a previously generated PCR JSON signature, and output it as one. The specified path
 221         must refer to a regular file that contains a valid JSON PCR signature object. The specified file is
 222         not modified. It will be read first, then the newly generated signature appended to it, and the
 223         resulting object is written to standard output. Use this to generate a single JSON object consisting
 224         from signatures made with a number of signing keys (for example, to have one key per boot phase). The
 225         command will suppress duplicates: if a specific signature is already included in a JSON signature
 226         object it is not added a second time.</para>
 227
 228         <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 229       </varlistentry>
 230
 231       <xi:include href="standard-options.xml" xpointer="json" />
 232       <xi:include href="standard-options.xml" xpointer="no-pager" />
 233       <xi:include href="standard-options.xml" xpointer="help" />
 234       <xi:include href="standard-options.xml" xpointer="version" />
 235     </variablelist>
 236   </refsect1>
 237
 238   <refsect1>
 239     <title>Examples</title>
 240
 241     <example>
 242       <title>Generate a unified kernel image, and calculate the expected TPM PCR 11 value</title>
 243
 244       <programlisting>$ ukify --output=vmlinux.efi \
 245      --os-release=@os-release.txt \
 246      --cmdline=@cmdline.txt \
 247      --splash=splash.bmp \
 248      --devicetree=devicetree.dtb \
 249      --measure \
 250      vmlinux initrd.cpio
 251 11:sha1=d775a7b4482450ac77e03ee19bda90bd792d6ec7
 252 11:sha256=bc6170f9ce28eb051ab465cd62be8cf63985276766cf9faf527ffefb66f45651
 253 11:sha384=1cf67dff4757e61e5...7f49ad720be02fd07263e1f93061243aec599d1ee4b4
 254 11:sha512=8e79acd3ddbbc8282...0c3e8ec0c714821032038f525f744960bcd082d937da
 255 </programlisting>
 256
 257       <para><citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 258       internally calls <command>systemd-measure</command>. The output with hashes is from
 259       <command>systemd-measure</command>.</para>
 260     </example>
 261
 262     <example>
 263       <title>Generate a private/public key pair, a unified kernel image, and a TPM PCR 11 signature for
 264       it, and embed the signature and the public key in the image</title>
 265
 266       <programlisting>$ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-private.pem
 267 ..+.+++++++++......+.........+......+.......+....+.....+.+...+..........
 268 $ openssl rsa -pubout -in tpm2-pcr-private.pem -out tpm2-pcr-public.pem
 269 # systemd-measure sign \
 270      --linux=vmlinux \
 271      --osrel=os-release.txt \
 272      --cmdline=cmdline.txt \
 273      --initrd=initrd.cpio \
 274      --splash=splash.bmp \
 275      --dtb=devicetree.dtb \
 276      --pcrpkey=tpm2-pcr-public.pem \
 277      --bank=sha1 \
 278      --bank=sha256 \
 279      --private-key=tpm2-pcr-private.pem \
 280      --public-key=tpm2-pcr-public.pem >tpm2-pcr-signature.json
 281 # ukify --output=vmlinuz.efi \
 282      --os-release=@os-release.txt \
 283      --cmdline=@cmdline.txt \
 284      --splash=splash.bmp \
 285      --devicetree=devicetree.dtb \
 286      --pcr-private-key=tpm2-pcr-private.pem \
 287      --pcr-public-key=tpm2-pcr-public.pem \
 288      --pcr-banks=sha1,sha256 \
 289      vmlinux initrd.cpio</programlisting>
 290
 291      <para>Later on, enroll the signed PCR policy on a LUKS volume:</para>
 292
 293      <programlisting># systemd-cryptenroll --tpm2-device=auto \
 294      --tpm2-public-key=tpm2-pcr-public.pem \
 295      --tpm2-signature=tpm2-pcr-signature.json \
 296      /dev/sda5</programlisting>
 297
 298      <para>And then unlock the device with the signature:</para>
 299
 300      <programlisting># systemd-cryptsetup attach \
 301      volume5 /dev/sda5 - \
 302      tpm2-device=auto,tpm2-signature=/path/to/tpm2-pcr-signature.json</programlisting>
 303
 304      <para>Note that when the generated unified kernel image <filename>vmlinux.efi</filename> is booted, the
 305      signature and public key files will be placed at locations <command>systemd-cryptenroll</command> and
 306      <command>systemd-cryptsetup</command> will look for anyway, and thus these paths do not actually need to
 307      be specified.</para>
 308     </example>
 309
 310     <example>
 311       <title>Introduce a second public key, signing the same kernel PCR measurements, but only for the initrd boot phase</title>
 312
 313       <para>This example extends the previous one, but we now introduce a second signing key that is only
 314       used to sign PCR policies restricted to the initrd boot phase. This can be used to lock down root
 315       volumes in a way that they can only be unlocked before the transition to the host system. Thus we have
 316       two classes of secrets or credentials: one that can be unlocked during the entire runtime, and the
 317       other that can only be used in the initrd.</para>
 318
 319       <programlisting>$ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-private.pem
 320 .+........+.+........+.......+...+...+........+....+......+..+..........
 321 $ openssl rsa -pubout -in tpm2-pcr-private.pem -out tpm2-pcr-public.pem
 322 $ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-initrd-private.pem
 323 ..+.......++........+........+......+........+....+.....+.+..+..........
 324 $ openssl rsa -pubout -in tpm2-pcr-initrd-private.pem -out tpm2-pcr-initrd-public.pem
 325 # ukify --output vmlinux-1.2.3.efi \
 326      --os-release=@os-release.txt \
 327      --cmdline=@cmdline.txt \
 328      --splash=splash.bmp \
 329      --devicetree=devicetree.dtb \
 330      --pcr-private-key=tpm2-pcr-private.pem \
 331      --pcr-public-key=tpm2-pcr-public.pem \
 332      --phases=enter-initrd,enter-initrd:leave-initrd,enter-initrd:leave-initrd:sysinit,enter-initrd:leave-initrd:sysinit:ready \
 333      --pcr-banks=sha1,sha256 \
 334      --pcr-private-key=tpm2-pcr-initrd-private.pem \
 335      --pcr-public-key=tpm2-pcr-initrd-public.pem \
 336      --phases=enter-initrd \
 337      vmlinux-1.2.3 initrd.cpio \
 338      --uname=1.2.3
 339 + /usr/lib/systemd/systemd-measure sign --linux=vmlinux-1.2.3 \
 340 --osrel=os-release.txt --cmdline=cmdline.txt --dtb=devicetree.dtb \
 341 --splash=splash.bmp --initrd=initrd.cpio --bank=sha1 --bank=sha256 \
 342 --private-key=tpm2-pcr-private.pem --public-key=tpm2-pcr-public.pem \
 343 --phase=enter-initrd --phase=enter-initrd:leave-initrd \
 344 --phase=enter-initrd:leave-initrd:sysinit \
 345 --phase=enter-initrd:leave-initrd:sysinit:ready
 346 + /usr/lib/systemd/systemd-measure sign --linux=vmlinux-1.2.3 \
 347 --osrel=os-release.txt --cmdline=cmdline.txt --dtb=devicetree.dtb \
 348 --splash=splash.bmp --initrd=initrd.cpio --bank=sha1 --bank=sha256 \
 349 --private-key=tpm2-pcr-initrd-private.pem \
 350 --public-key=tpm2-pcr-initrd-public.pem \
 351 --phase=enter-initrd
 352 Wrote unsigned vmlinux-1.2.3.efi
 353       </programlisting>
 354
 355       <para><command>ukify</command> prints out both invocations of <command>systemd-measure</command> as
 356       informative output (the lines starting with <literal>+</literal>); this allows us to see how
 357       <command>systemd-measure</command> is called. It then merges the output of both invocations into the
 358       <literal>.pcrsig</literal> section. <command>systemd-measure</command> may also do this merge itself
 359       using the <option>--append=</option> option.</para>
 360
 361       <para>Note that in this example the <literal>.pcrpkey</literal> PE section contains the key specified
 362       by the first <option>--pcr-private-key=</option> option, covering all boot phases. The
 363       <literal>.pcrpkey</literal> section is used in the default policies of
 364       <command>systemd-cryptenroll</command> and <command>systemd-creds</command>. To use the stricter policy
 365       bound to <filename>tpm-pcr-initrd-public.pem</filename>, specify <option>--tpm2-public-key=</option> on
 366       the command line of those tools.</para>
 367     </example>
 368   </refsect1>
 369
 370   <refsect1>
 371     <title>Exit status</title>
 372
 373     <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
 374   </refsect1>
 375
 376   <refsect1>
 377     <title>See Also</title>
 378     <para><simplelist type="inline">
 379       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 380       <member><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 381       <member><citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 382       <member><citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 383       <member><citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 384       <member><citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 385      </simplelist></para>
 386   </refsect1>
 387
 388 </refentry>