summaryrefslogtreecommitdiffstats
path: root/man/systemd-measure.xml
blob: ff3abc429f5248456421c171b80f7002eaf5e031 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
<?xml version="1.0"?>
<!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="systemd-measure" xmlns:xi="http://www.w3.org/2001/XInclude" conditional='ENABLE_BOOTLOADER'>

  <refentryinfo>
    <title>systemd-measure</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>systemd-measure</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>systemd-measure</refname>
    <refpurpose>Pre-calculate and sign expected TPM2 PCR values for booted unified kernel images</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>/usr/lib/systemd/systemd-measure <arg choice="opt" rep="repeat">OPTIONS</arg></command>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para>Note: this command is experimental for now. While it is likely to become a regular component of
    systemd, it might still change in behaviour and interface.</para>

    <para><command>systemd-measure</command> is a tool that may be used to pre-calculate and sign the
    expected TPM2 PCR 11 values that should be seen when a Linux <ulink
    url="https://uapi-group.org/specifications/specs/unified_kernel_image/">Unified Kernel Image
    (UKI)</ulink> based on
    <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> is
    booted up. It accepts paths to the ELF kernel image file, initrd image file, devicetree file, kernel
    command line file,
    <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file, boot
    splash file, and TPM2 PCR PEM public key file that make up the unified kernel image, and determines the
    PCR values expected to be in place after booting the image. Calculation starts with a zero-initialized
    PCR 11, and is executed in a fashion compatible with what <filename>systemd-stub</filename> does at boot.
    The result may optionally be signed cryptographically, to allow TPM2 policies that can only be unlocked
    if a certain set of kernels is booted, for which such a PCR signature can be provided.</para>

    <para>It usually doesn't make sense to call this tool directly when constructing a UKI. Instead,
    <citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry> should be used;
    it will invoke <command>systemd-measure</command> and take care of embedding the resulting measurements
    into the UKI.</para>
  </refsect1>

  <refsect1>
    <title>Commands</title>

    <para>The following commands are understood:</para>

    <variablelist>
      <varlistentry>
        <term><command>status</command></term>

        <listitem><para>This is the default command if none is specified. This queries the local system's
        TPM2 PCR 11+12+13 values and displays them. The data is written in a similar format as the
        <command>calculate</command> command below, and may be used to quickly compare expectation with
        reality.</para>

        <xi:include href="version-info.xml" xpointer="v252"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><command>calculate</command></term>

        <listitem><para>Pre-calculate the expected values seen in PCR register 11 after boot-up of a unified
        kernel image consisting of the components specified with <option>--linux=</option>,
        <option>--osrel=</option>, <option>--cmdline=</option>, <option>--initrd=</option>,
        <option>--splash=</option>, <option>--dtb=</option>, <option>--uname=</option>,
        <option>--sbat=</option>, <option>--pcrpkey=</option> see below. Only <option>--linux=</option> is
        mandatory. (Alternatively, specify <option>--current</option> to use the current values of PCR
        register 11 instead.)</para>

        <xi:include href="version-info.xml" xpointer="v252"/>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>sign</command></term>

        <listitem><para>As with the <command>calculate</command> command, pre-calculate the expected value
        seen in TPM2 PCR register 11 after boot-up of a unified kernel image. Then, cryptographically sign
        the resulting values with the private/public key pair (RSA) configured via
        <option>--private-key=</option> and <option>--public-key=</option>. This will write a JSON object to
        standard output that contains signatures for all specified PCR banks (see the
        <option>--bank=</option> option below), which may be used to unlock encrypted credentials (see
        <citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry>) or
        LUKS volumes (see
        <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>).
        This allows binding secrets to a set of kernels for which such PCR 11 signatures can be
        provided.</para>

        <para>Note that a TPM2 device must be available for this signing to take place, even though the
        result is not tied to any TPM2 device or its state.</para>

        <xi:include href="version-info.xml" xpointer="v252"/></listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Options</title>

    <para>The following options are understood:</para>

    <variablelist>
      <varlistentry>
        <term><option>--linux=<replaceable>PATH</replaceable></option></term>
        <term><option>--osrel=<replaceable>PATH</replaceable></option></term>
        <term><option>--cmdline=<replaceable>PATH</replaceable></option></term>
        <term><option>--initrd=<replaceable>PATH</replaceable></option></term>
        <term><option>--splash=<replaceable>PATH</replaceable></option></term>
        <term><option>--dtb=<replaceable>PATH</replaceable></option></term>
        <term><option>--uname=<replaceable>PATH</replaceable></option></term>
        <term><option>--sbat=<replaceable>PATH</replaceable></option></term>
        <term><option>--pcrpkey=<replaceable>PATH</replaceable></option></term>

        <listitem><para>When used with the <command>calculate</command> or <command>sign</command> verb,
        configures the files to read the unified kernel image components from. Each option corresponds with
        the equally named section in the unified kernel PE file. The <option>--linux=</option> switch expects
        the path to the ELF kernel file that the unified PE kernel will wrap. All switches except
        <option>--linux=</option> are optional. Each option may be used at most once.</para>

        <xi:include href="version-info.xml" xpointer="v252"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--current</option></term>
        <listitem><para>When used with the <command>calculate</command> or <command>sign</command> verb,
        takes the PCR 11 values currently in effect for the system (which should typically reflect the hashes
        of the currently booted kernel). This can be used in place of <option>--linux=</option> and the other
        switches listed above.</para>

        <xi:include href="version-info.xml" xpointer="v252"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--bank=<replaceable>DIGEST</replaceable></option></term>

        <listitem><para>Controls the PCR banks to pre-calculate the PCR values for  in case
        <command>calculate</command> or <command>sign</command> is invoked –, or the banks to show in the
        <command>status</command> output. May be used more then once to specify multiple banks. If not
        specified, defaults to the four banks <literal>sha1</literal>, <literal>sha256</literal>,
        <literal>sha384</literal>, <literal>sha512</literal>.</para>

        <xi:include href="version-info.xml" xpointer="v252"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--private-key=<replaceable>PATH</replaceable></option></term>
        <term><option>--public-key=<replaceable>PATH</replaceable></option></term>

        <listitem><para>These switches take paths to a pair of PEM encoded RSA key files, for use with
        the <command>sign</command> command.</para>

        <para>Note the difference between the <option>--pcrpkey=</option> and <option>--public-key=</option>
        switches. The former selects the data to include in the <literal>.pcrpkey</literal> PE section of the
        unified kernel image, the latter picks the public key of the key pair used to sign the resulting PCR
        11 values. The former is the key that the booted system will likely use to lock disk and credential
        encryption to, the latter is the key used for unlocking such resources again. Hence, typically the
        same PEM key should be supplied in both cases.</para>

        <para>If the <option>--public-key=</option> is not specified but <option>--private-key=</option> is
        specified the public key is automatically derived from the private key.</para>

        <xi:include href="version-info.xml" xpointer="v252"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--tpm2-device=</option><replaceable>PATH</replaceable></term>

        <listitem><para>Controls which TPM2 device to use. Expects a device node path referring to the TPM2
        chip (e.g. <filename>/dev/tpmrm0</filename>). Alternatively the special value <literal>auto</literal>
        may be specified, in order to automatically determine the device node of a suitable TPM2 device (of
        which there must be exactly one). The special value <literal>list</literal> may be used to enumerate
        all suitable TPM2 devices currently discovered.</para>

        <xi:include href="version-info.xml" xpointer="v252"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--phase=</option><replaceable>PHASE</replaceable></term>

        <listitem><para>Controls which boot phases to calculate expected PCR 11 values for. This takes a
        series of colon-separated strings that encode boot "paths" for entering a specific phase of the boot
        process. Each of the specified strings is measured by the
        <filename>systemd-pcrphase-initrd.service</filename>,
        <filename>systemd-pcrphase-sysinit.service</filename>, and
        <citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
        into PCR 11 during different milestones of the boot process. This switch may be specified multiple
        times to calculate PCR values for multiple boot phases at once. If not used defaults to
        <literal>enter-initrd</literal>, <literal>enter-initrd:leave-initrd</literal>,
        <literal>enter-initrd:leave-initrd:sysinit</literal>,
        <literal>enter-initrd:leave-initrd:sysinit:ready</literal>, i.e. calculates expected PCR values for
        the boot phase in the initrd, during early boot, during later boot, and during system runtime, but
        excluding the phases before the initrd or when shutting down. This setting is honoured both by
        <command>calculate</command> and <command>sign</command>. When used with the latter it's particularly
        useful for generating PCR signatures that can only be used for unlocking resources during specific
        parts of the boot process.</para>

        <para>For further details about PCR boot phases, see
        <citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>

        <xi:include href="version-info.xml" xpointer="v252"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--append=</option><replaceable>PATH</replaceable></term>

        <listitem><para>When generating a PCR JSON signature (via the <command>sign</command> command),
        combine it with a previously generated PCR JSON signature, and output it as one. The specified path
        must refer to a regular file that contains a valid JSON PCR signature object. The specified file is
        not modified. It will be read first, then the newly generated signature appended to it, and the
        resulting object is written to standard output. Use this to generate a single JSON object consisting
        from signatures made with a number of signing keys (for example, to have one key per boot phase). The
        command will suppress duplicates: if a specific signature is already included in a JSON signature
        object it is not added a second time.</para>

        <xi:include href="version-info.xml" xpointer="v253"/></listitem>
      </varlistentry>

      <xi:include href="standard-options.xml" xpointer="json" />
      <xi:include href="standard-options.xml" xpointer="no-pager" />
      <xi:include href="standard-options.xml" xpointer="help" />
      <xi:include href="standard-options.xml" xpointer="version" />
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Examples</title>

    <example>
      <title>Generate a unified kernel image, and calculate the expected TPM PCR 11 value</title>

      <programlisting>$ ukify --output=vmlinux.efi \
     --os-release=@os-release.txt \
     --cmdline=@cmdline.txt \
     --splash=splash.bmp \
     --devicetree=devicetree.dtb \
     --measure \
     vmlinux initrd.cpio
11:sha1=d775a7b4482450ac77e03ee19bda90bd792d6ec7
11:sha256=bc6170f9ce28eb051ab465cd62be8cf63985276766cf9faf527ffefb66f45651
11:sha384=1cf67dff4757e61e5...7f49ad720be02fd07263e1f93061243aec599d1ee4b4
11:sha512=8e79acd3ddbbc8282...0c3e8ec0c714821032038f525f744960bcd082d937da
</programlisting>

      <para><citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry>
      internally calls <command>systemd-measure</command>. The output with hashes is from
      <command>systemd-measure</command>.</para>
    </example>

    <example>
      <title>Generate a private/public key pair, a unified kernel image, and a TPM PCR 11 signature for
      it, and embed the signature and the public key in the image</title>

      <programlisting>$ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-private.pem
..+.+++++++++......+.........+......+.......+....+.....+.+...+..........
$ openssl rsa -pubout -in tpm2-pcr-private.pem -out tpm2-pcr-public.pem
# systemd-measure sign \
     --linux=vmlinux \
     --osrel=os-release.txt \
     --cmdline=cmdline.txt \
     --initrd=initrd.cpio \
     --splash=splash.bmp \
     --dtb=devicetree.dtb \
     --pcrpkey=tpm2-pcr-public.pem \
     --bank=sha1 \
     --bank=sha256 \
     --private-key=tpm2-pcr-private.pem \
     --public-key=tpm2-pcr-public.pem >tpm2-pcr-signature.json
# ukify --output=vmlinuz.efi \
     --os-release=@os-release.txt \
     --cmdline=@cmdline.txt \
     --splash=splash.bmp \
     --devicetree=devicetree.dtb \
     --pcr-private-key=tpm2-pcr-private.pem \
     --pcr-public-key=tpm2-pcr-public.pem \
     --pcr-banks=sha1,sha256 \
     vmlinux initrd.cpio</programlisting>

     <para>Later on, enroll the signed PCR policy on a LUKS volume:</para>

     <programlisting># systemd-cryptenroll --tpm2-device=auto \
     --tpm2-public-key=tpm2-pcr-public.pem \
     --tpm2-signature=tpm2-pcr-signature.json \
     /dev/sda5</programlisting>

     <para>And then unlock the device with the signature:</para>

     <programlisting># systemd-cryptsetup attach \
     volume5 /dev/sda5 - \
     tpm2-device=auto,tpm2-signature=/path/to/tpm2-pcr-signature.json</programlisting>

     <para>Note that when the generated unified kernel image <filename>vmlinux.efi</filename> is booted, the
     signature and public key files will be placed at locations <command>systemd-cryptenroll</command> and
     <command>systemd-cryptsetup</command> will look for anyway, and thus these paths do not actually need to
     be specified.</para>
    </example>

    <example>
      <title>Introduce a second public key, signing the same kernel PCR measurements, but only for the initrd boot phase</title>

      <para>This example extends the previous one, but we now introduce a second signing key that is only
      used to sign PCR policies restricted to the initrd boot phase. This can be used to lock down root
      volumes in a way that they can only be unlocked before the transition to the host system. Thus we have
      two classes of secrets or credentials: one that can be unlocked during the entire runtime, and the
      other that can only be used in the initrd.</para>

      <programlisting>$ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-private.pem
.+........+.+........+.......+...+...+........+....+......+..+..........
$ openssl rsa -pubout -in tpm2-pcr-private.pem -out tpm2-pcr-public.pem
$ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-initrd-private.pem
..+.......++........+........+......+........+....+.....+.+..+..........
$ openssl rsa -pubout -in tpm2-pcr-initrd-private.pem -out tpm2-pcr-initrd-public.pem
# ukify --output vmlinux-1.2.3.efi \
     --os-release=@os-release.txt \
     --cmdline=@cmdline.txt \
     --splash=splash.bmp \
     --devicetree=devicetree.dtb \
     --pcr-private-key=tpm2-pcr-private.pem \
     --pcr-public-key=tpm2-pcr-public.pem \
     --phases=enter-initrd,enter-initrd:leave-initrd,enter-initrd:leave-initrd:sysinit,enter-initrd:leave-initrd:sysinit:ready \
     --pcr-banks=sha1,sha256 \
     --pcr-private-key=tpm2-pcr-initrd-private.pem \
     --pcr-public-key=tpm2-pcr-initrd-public.pem \
     --phases=enter-initrd \
     vmlinux-1.2.3 initrd.cpio \
     --uname=1.2.3
+ /usr/lib/systemd/systemd-measure sign --linux=vmlinux-1.2.3 \
--osrel=os-release.txt --cmdline=cmdline.txt --dtb=devicetree.dtb \
--splash=splash.bmp --initrd=initrd.cpio --bank=sha1 --bank=sha256 \
--private-key=tpm2-pcr-private.pem --public-key=tpm2-pcr-public.pem \
--phase=enter-initrd --phase=enter-initrd:leave-initrd \
--phase=enter-initrd:leave-initrd:sysinit \
--phase=enter-initrd:leave-initrd:sysinit:ready
+ /usr/lib/systemd/systemd-measure sign --linux=vmlinux-1.2.3 \
--osrel=os-release.txt --cmdline=cmdline.txt --dtb=devicetree.dtb \
--splash=splash.bmp --initrd=initrd.cpio --bank=sha1 --bank=sha256 \
--private-key=tpm2-pcr-initrd-private.pem \
--public-key=tpm2-pcr-initrd-public.pem \
--phase=enter-initrd
Wrote unsigned vmlinux-1.2.3.efi
      </programlisting>

      <para><command>ukify</command> prints out both invocations of <command>systemd-measure</command> as
      informative output (the lines starting with <literal>+</literal>); this allows us to see how
      <command>systemd-measure</command> is called. It then merges the output of both invocations into the
      <literal>.pcrsig</literal> section. <command>systemd-measure</command> may also do this merge itself
      using the <option>--append=</option> option.</para>

      <para>Note that in this example the <literal>.pcrpkey</literal> PE section contains the key specified
      by the first <option>--pcr-private-key=</option> option, covering all boot phases. The
      <literal>.pcrpkey</literal> section is used in the default policies of
      <command>systemd-cryptenroll</command> and <command>systemd-creds</command>. To use the stricter policy
      bound to <filename>tpm-pcr-initrd-public.pem</filename>, specify <option>--tpm2-public-key=</option> on
      the command line of those tools.</para>
    </example>
  </refsect1>

  <refsect1>
    <title>Exit status</title>

    <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
     </para>
  </refsect1>

</refentry>