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-measure" xmlns:
xi=
"http://www.w3.org/2001/XInclude" conditional='HAVE_GNU_EFI'
>
9 <title>systemd-measure
</title>
10 <productname>systemd
</productname>
14 <refentrytitle>systemd-measure
</refentrytitle>
15 <manvolnum>1</manvolnum>
19 <refname>systemd-measure
</refname>
20 <refpurpose>Pre-calculate and sign expected TPM2 PCR values for booted unified kernel images
</refpurpose>
25 <command>/usr/lib/systemd/systemd-measure
<arg choice=
"opt" rep=
"repeat">OPTIONS
</arg></command>
30 <title>Description
</title>
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>
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 unified Linux kernel image based on
37 <citerefentry><refentrytitle>systemd-stub
</refentrytitle><manvolnum>7</manvolnum></citerefentry> is
38 booted up. It accepts paths to the ELF kernel image file, initrd image file, devicetree file, kernel
40 <citerefentry><refentrytitle>os-release
</refentrytitle><manvolnum>5</manvolnum></citerefentry> file, boot
41 splash file, and TPM2 PCR PEM public key file that make up the unified kernel image, and determines the
42 PCR values expected to be in place after booting the image. Calculation starts with a zero-initialized
43 PCR
11, and is executed in a fashion compatible with what
<filename>systemd-stub
</filename> does at
44 boot. The result may optionally be signed cryptographically, to allow TPM2 policies that can only be
45 unlocked if a certain set of kernels is booted, for which such a PCR signature can be provided.
</para>
49 <title>Commands
</title>
51 <para>The following commands are understood:
</para>
55 <term><command>status
</command></term>
57 <listitem><para>This is the default command if none is specified. This queries the local system's
58 TPM2 PCR
11+
12+
13 values and displays them. The data is written in a similar format as the
59 <command>calculate
</command> command below, and may be used to quickly compare expectation with
60 reality.
</para></listitem>
64 <term><command>calculate
</command></term>
66 <listitem><para>Pre-calculate the expected values seen in PCR register
11 after boot-up of a unified
67 kernel image consisting of the components specified with
<option>--linux=
</option>,
68 <option>--osrel=
</option>,
<option>--cmdline=
</option>,
<option>--initrd=
</option>,
69 <option>--splash=
</option>,
<option>--dtb=
</option>,
<option>--pcrpkey=
</option> see below. Only
70 <option>--linux=
</option> is mandatory. (Alternatively, specify
<option>--current
</option> to use the
71 current values of PCR register
11 instead.)
</para></listitem>
75 <term><command>sign
</command></term>
77 <listitem><para>As with the
<command>calculate
</command> command, pre-calculate the expected value
78 seen in TPM2 PCR register
11 after boot-up of a unified kernel image. Then, cryptographically sign
79 the resulting values with the private/public key pair (RSA) configured via
80 <option>--private-key=
</option> and
<option>--public-key=
</option>. This will write a JSON object to
81 standard output that contains signatures for all specified PCR banks (see the
82 <option>--pcr-bank=
</option> option below), which may be used to unlock encrypted credentials (see
83 <citerefentry><refentrytitle>systemd-creds
</refentrytitle><manvolnum>1</manvolnum></citerefentry>) or
85 <citerefentry><refentrytitle>systemd-cryptsetup@.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>).
86 This allows binding secrets to a set of kernels for which such PCR
11 signatures can be
89 <para>Note that a TPM2 device must be available for this signing to take place, even though the
90 result is not tied to any TPM2 device or its state.
</para></listitem>
96 <title>Options
</title>
98 <para>The following options are understood:
</para>
102 <term><option>--linux=
<replaceable>PATH
</replaceable></option></term>
103 <term><option>--osrel=
<replaceable>PATH
</replaceable></option></term>
104 <term><option>--cmdline=
<replaceable>PATH
</replaceable></option></term>
105 <term><option>--initrd=
<replaceable>PATH
</replaceable></option></term>
106 <term><option>--splash=
<replaceable>PATH
</replaceable></option></term>
107 <term><option>--dtb=
<replaceable>PATH
</replaceable></option></term>
108 <term><option>--pcrpkey=
<replaceable>PATH
</replaceable></option></term>
110 <listitem><para>When used with the
<command>calculate
</command> or
<command>sign
</command> verb,
111 configures the files to read the unified kernel image components from. Each option corresponds with
112 the equally named section in the unified kernel PE file. The
<option>--linux=
</option> switch expects
113 the path to the ELF kernel file that the unified PE kernel will wrap. All switches except
114 <option>--linux=
</option> are optional. Each option may be used at most once.
</para></listitem>
118 <term><option>--current
</option></term>
119 <listitem><para>When used with the
<command>calculate
</command> or
<command>sign
</command> verb,
120 takes the PCR
11 values currently in effect for the system (which should typically reflect the hashes
121 of the currently booted kernel). This can be used in place of
<option>--linux=
</option> and the other
122 switches listed above.
</para></listitem>
126 <term><option>--bank=
<replaceable>DIGEST
</replaceable></option></term>
128 <listitem><para>Controls the PCR banks to pre-calculate the PCR values for – in case
129 <command>calculate
</command> or
<command>sign
</command> is invoked –, or the banks to show in the
130 <command>status
</command> output. May be used more then once to specify multiple banks. If not
131 specified, defaults to the four banks
<literal>sha1
</literal>,
<literal>sha256
</literal>,
132 <literal>sha384
</literal>,
<literal>sha512
</literal>.
</para></listitem>
136 <term><option>--private-key=
<replaceable>PATH
</replaceable></option></term>
137 <term><option>--public-key=
<replaceable>PATH
</replaceable></option></term>
139 <listitem><para>These switches take paths to a pair of PEM encoded RSA key files, for use with
140 the
<command>sign
</command> command.
</para>
142 <para>Note the difference between the
<option>--pcrpkey=
</option> and
<option>--public-key=
</option>
143 switches. The former selects the data to include in the
<literal>.pcrpkey
</literal> PE section of the
144 unified kernel image, the latter picks the public key of the key pair used to sign the resulting PCR
145 11 values. The former is the key that the booted system will likely use to lock disk and credential
146 encryption to, the latter is the key used for unlocking such resources again. Hence, typically the
147 same PEM key should be supplied in both cases.
</para>
149 <para>If the
<option>--public-key=
</option> is not specified but
<option>--private-key=
</option> is
150 specified the public key is automatically derived from the private key.
</para></listitem>
154 <term><option>--tpm2-device=
</option><replaceable>PATH
</replaceable></term>
156 <listitem><para>Controls which TPM2 device to use. Expects a device node path referring to the TPM2
157 chip (e.g.
<filename>/dev/tpmrm0
</filename>). Alternatively the special value
<literal>auto
</literal>
158 may be specified, in order to automatically determine the device node of a suitable TPM2 device (of
159 which there must be exactly one). The special value
<literal>list
</literal> may be used to enumerate
160 all suitable TPM2 devices currently discovered.
</para></listitem>
164 <term><option>--phase=
</option><replaceable>PHASE
</replaceable></term>
166 <listitem><para>Controls which boot phases to calculate expected PCR
11 values for. This takes a
167 series of colon-separated strings that encode boot
"paths" for entering a specific phase of the boot
168 process. Each of the specified strings is measured by the
169 <filename>systemd-pcrphase-initrd.service
</filename> and
170 <citerefentry><refentrytitle>systemd-pcrphase.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
171 into PCR
11 during different milestones of the boot process. This switch may be specified multiple
172 times to calculate PCR values for multiple boot phases at once. If not used defaults to
173 <literal>enter-initrd
</literal>,
<literal>enter-initrd:leave-initrd
</literal>,
174 <literal>enter-initrd:leave-initrd:sysinit
</literal>,
175 <literal>enter-initrd:leave-initrd:sysinit:ready
</literal>, i.e. calculates expected PCR values for
176 the boot phase in the initrd, during early boot, during later boot, and during system runtime, but
177 excluding the phases before the initrd or when shutting down. This setting is honoured both by
178 <command>calculate
</command> and
<command>sign
</command>. When used with the latter it's particularly
179 useful for generating PCR signatures that can only be used for unlocking resources during specific
180 parts of the boot process.
</para>
182 <para>For further details about PCR boot phases, see
183 <citerefentry><refentrytitle>systemd-pcrphase.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para></listitem>
187 <term><option>--append=
</option><replaceable>PATH
</replaceable></term>
189 <listitem><para>When generating a PCR JSON signature (via the
<command>sign
</command> command),
190 combine it with a previously generated PCR JSON signature, and output it as one. The specified path
191 must refer to a regular file that contains a valid JSON PCR signature object. The specified file is
192 not modified. It will be read first, then the newly generated signature appended to it, and the
193 resulting object is written to standard output. Use this to generate a single JSON object consisting
194 from signatures made with a number of signing keys (for example, to have one key per boot phase). The
195 command will suppress duplicates: if a specific signature is already included in a JSON signature
196 object it is not added a second time.
</para></listitem>
199 <xi:include href=
"standard-options.xml" xpointer=
"json" />
200 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
201 <xi:include href=
"standard-options.xml" xpointer=
"help" />
202 <xi:include href=
"standard-options.xml" xpointer=
"version" />
207 <title>Examples
</title>
210 <title>Generate a unified kernel image, and calculate the expected TPM PCR
11 value
</title>
212 <programlisting># objcopy \
213 --add-section .linux=vmlinux --change-section-vma .linux=
0x2000000 \
214 --add-section .osrel=os-release.txt --change-section-vma .osrel=
0x20000 \
215 --add-section .cmdline=cmdline.txt --change-section-vma .cmdline=
0x30000 \
216 --add-section .initrd=initrd.cpio --change-section-vma .initrd=
0x3000000 \
217 --add-section .splash=splash.bmp --change-section-vma .splash=
0x100000 \
218 --add-section .dtb=devicetree.dtb --change-section-vma .dtb=
0x40000 \
219 /usr/lib/systemd/boot/efi/linuxx64.efi.stub \
221 # systemd-measure calculate \
223 --osrel=os-release.txt \
224 --cmdline=cmdline.txt \
225 --initrd=initrd.cpio \
226 --splash=splash.bmp \
228 11:sha1=d775a7b4482450ac77e03ee19bda90bd792d6ec7
229 11:sha256=bc6170f9ce28eb051ab465cd62be8cf63985276766cf9faf527ffefb66f45651
230 11:sha384=
1cf67dff4757e61e5a73d2a21a6694d668629bbc3761747d493f7f49ad720be02fd07263e1f93061243aec599d1ee4b4
231 11:sha512=
8e79acd3ddbbc8282e98091849c3530f996303c8ac8e87a3b2378b71c8b3a6e86d5c4f41ecea9e1517090c3e8ec0c714821032038f525f744960bcd082d937da
236 <title>Generate a private/public key pair, and a unified kernel image, and a TPM PCR
11 signature for
237 it, and embed the signature and the public key in the image
</title>
239 <programlisting># openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:
2048 -out tpm2-pcr-private.pem
240 # openssl rsa -pubout -in tpm2-pcr-private.pem -out tpm2-pcr-public.pem
241 # systemd-measure sign \
243 --osrel=os-release.txt \
244 --cmdline=cmdline.txt \
245 --initrd=initrd.cpio \
246 --splash=splash.bmp \
247 --dtb=devicetree.dtb \
248 --pcrpkey=tpm2-pcr-public.pem \
251 --private-key=tpm2-pcr-private.pem \
252 --public-key=tpm2-pcr-public.pem
> tpm2-pcr-signature.json
254 --add-section .linux=vmlinux --change-section-vma .linux=
0x2000000 \
255 --add-section .osrel=os-release.txt --change-section-vma .osrel=
0x20000 \
256 --add-section .cmdline=cmdline.txt --change-section-vma .cmdline=
0x30000 \
257 --add-section .initrd=initrd.cpio --change-section-vma .initrd=
0x3000000 \
258 --add-section .splash=splash.bmp --change-section-vma .splash=
0x100000 \
259 --add-section .dtb=devicetree.dtb --change-section-vma .dtb=
0x40000 \
260 --add-section .pcrsig=tpm2-pcr-signature.json --change-section-vma .pcrsig=
0x80000 \
261 --add-section .pcrpkey=tpm2-pcr-public.pem --change-section-vma .pcrpkey=
0x90000 \
262 /usr/lib/systemd/boot/efi/linuxx64.efi.stub \
263 foo.efi
</programlisting>
265 <para>Later on, enroll the signed PCR policy on a LUKS volume:
</para>
267 <programlisting># systemd-cryptenroll --tpm2-device=auto --tpm2-public-key=tpm2-pcr-public.pem --tpm2-signature=tpm2-pcr-signature.json /dev/sda5
</programlisting>
269 <para>And then unlock the device with the signature:
</para>
271 <programlisting># /usr/lib/systemd/systemd-cryptsetup attach myvolume /dev/sda5 - tpm2-device=auto,tpm2-signature=/path/to/tpm2-pcr-signature.json
</programlisting>
273 <para>Note that when the generated unified kernel image
<filename>foo.efi
</filename> is booted the
274 signature and public key files will be placed at locations
<command>systemd-cryptenroll
</command> and
275 <command>systemd-cryptsetup
</command> will look for anyway, and thus these paths do not actually need to
280 <title>Introduce a second public key, signing the same kernel PCR measurements, but only for the initrd boot phase
</title>
282 <para>This example extends the previous one, but we now introduce a second signing key that is only
283 used to sign PCR policies restricted to the initrd boot phase. This can be used to lock down root
284 volumes in a way that they can only be unlocked before the transition to the host system. Thus we have
285 two classes of secrets or credentials: one that can be unlocked during the entire runtime, and the
286 other that can only be used in the initrd.
</para>
288 <programlisting># openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:
2048 -out tpm2-pcr-private.pem
289 # openssl rsa -pubout -in tpm2-pcr-private.pem -out tpm2-pcr-public.pem
290 # systemd-measure sign \
292 --osrel=os-release.txt \
293 --cmdline=cmdline.txt \
294 --initrd=initrd.cpio \
295 --splash=splash.bmp \
296 --dtb=devicetree.dtb \
297 --pcrpkey=tpm2-pcr-public.pem \
300 --private-key=tpm2-pcr-private.pem \
301 --public-key=tpm2-pcr-public.pem
>tpm2-pcr-signature.json.tmp
302 # openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:
2048 -out tpm2-pcr-initrd-private.pem
303 # openssl rsa -pubout -in tpm2-pcr-initrd-private.pem -out tpm2-pcr-initrd-public.pem
304 # systemd-measure sign \
306 --osrel=os-release.txt \
307 --cmdline=cmdline.txt \
308 --initrd=initrd.cpio \
309 --splash=splash.bmp \
310 --dtb=devicetree.dtb \
311 --pcrpkey=tpm2-pcr-public.pem \
314 --private-key=tpm2-pcr-initrd-private.pem \
315 --public-key=tpm2-pcr-initrd-public.pem \
316 --phase=enter-initrd \
317 --append=tpm2-pcr-signature.json.tmp
>tpm2-pcr-signature.json
319 --add-section .linux=vmlinux --change-section-vma .linux=
0x2000000 \
320 --add-section .osrel=os-release.txt --change-section-vma .osrel=
0x20000 \
321 --add-section .cmdline=cmdline.txt --change-section-vma .cmdline=
0x30000 \
322 --add-section .initrd=initrd.cpio --change-section-vma .initrd=
0x3000000 \
323 --add-section .splash=splash.bmp --change-section-vma .splash=
0x100000 \
324 --add-section .dtb=devicetree.dtb --change-section-vma .dtb=
0x40000 \
325 --add-section .pcrsig=tpm2-pcr-signature.json --change-section-vma .pcrsig=
0x80000 \
326 --add-section .pcrpkey=tpm2-pcr-public.pem --change-section-vma .pcrpkey=
0x90000 \
327 /usr/lib/systemd/boot/efi/linuxx64.efi.stub \
328 foo.efi
</programlisting>
331 <para>Note that in this example the
<literal>.pcrpkey
</literal> PE section contains the key covering all
332 boot phases. The
<literal>.pcrpkey
</literal> is used in the default policies of
333 <command>systemd-cryptenroll
</command> and
<command>systemd-creds
</command>. To use the stricter
334 <filename>tpm-pcr-initrd-public.pem
</filename>-bound policy, specify
<option>--tpm2-public-key=
</option>
335 on the command line of those tools.
</para>
339 <title>Exit status
</title>
341 <para>On success,
0 is returned, a non-zero failure code otherwise.
</para>
345 <title>See Also
</title>
347 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
348 <citerefentry><refentrytitle>systemd-stub
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
349 <citerefentry project='man-pages'
><refentrytitle>objcopy
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
350 <citerefentry><refentrytitle>systemd-creds
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
351 <citerefentry><refentrytitle>systemd-cryptsetup@.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
352 <citerefentry><refentrytitle>systemd-pcrphase.service
</refentrytitle><manvolnum>1</manvolnum></citerefentry>