1SYSTEMD-MEASURE(1) systemd-measure SYSTEMD-MEASURE(1)
2
6 systemd-measure - Pre-calculate and sign expected TPM2 PCR values for
7 booted unified kernel images
8
10 /usr/lib/systemd/systemd-measure [OPTIONS...]
11
13 Note: this command is experimental for now. While it is likely to
14 become a regular component of systemd, it might still change in
15 behaviour and interface.
16 systemd-measure is a tool that may be used to pre-calculate and sign
18 the expected TPM2 PCR 11 values that should be seen when a Linux
19 Unified Kernel Image (UKI)[1] based on systemd-stub(7) is booted up. It
20 accepts paths to the ELF kernel image file, initrd image file,
21 devicetree file, kernel command line file, os-release(5) file, boot
22 splash file, and TPM2 PCR PEM public key file that make up the unified
23 kernel image, and determines the PCR values expected to be in place
24 after booting the image. Calculation starts with a zero-initialized PCR
25 11, and is executed in a fashion compatible with what systemd-stub does
26 at boot. The result may optionally be signed cryptographically, to
27 allow TPM2 policies that can only be unlocked if a certain set of
28 kernels is booted, for which such a PCR signature can be provided.
29 It usually doesn't make sense to call this tool directly when
31 constructing a UKI. Instead, ukify(1) should be used; it will invoke
32 systemd-measure and take care of embedding the resulting measurements
33 into the UKI.
34
36 The following commands are understood:
37 status
39 This is the default command if none is specified. This queries the
40 local system's TPM2 PCR 11+12+13 values and displays them. The data
41 is written in a similar format as the calculate command below, and
42 may be used to quickly compare expectation with reality.
43 calculate
45 Pre-calculate the expected values seen in PCR register 11 after
46 boot-up of a unified kernel image consisting of the components
47 specified with --linux=, --osrel=, --cmdline=, --initrd=,
48 --splash=, --dtb=, --sbat=, --pcrpkey= see below. Only --linux= is
49 mandatory. (Alternatively, specify --current to use the current
50 values of PCR register 11 instead.)
51 sign
53 As with the calculate command, pre-calculate the expected value
54 seen in TPM2 PCR register 11 after boot-up of a unified kernel
55 image. Then, cryptographically sign the resulting values with the
56 private/public key pair (RSA) configured via --private-key= and
57 --public-key=. This will write a JSON object to standard output
58 that contains signatures for all specified PCR banks (see the
59 --bank= option below), which may be used to unlock encrypted
60 credentials (see systemd-creds(1)) or LUKS volumes (see systemd-
61 cryptsetup@.service(8)). This allows binding secrets to a set of
62 kernels for which such PCR 11 signatures can be provided.
63 Note that a TPM2 device must be available for this signing to take
65 place, even though the result is not tied to any TPM2 device or its
66 state.
67
69 The following options are understood:
70 --linux=PATH, --osrel=PATH, --cmdline=PATH, --initrd=PATH,
72 --splash=PATH, --dtb=PATH, --sbat=PATH, --pcrpkey=PATH
73 When used with the calculate or sign verb, configures the files to
74 read the unified kernel image components from. Each option
75 corresponds with the equally named section in the unified kernel PE
76 file. The --linux= switch expects the path to the ELF kernel file
77 that the unified PE kernel will wrap. All switches except --linux=
78 are optional. Each option may be used at most once.
79 --current
81 When used with the calculate or sign verb, takes the PCR 11 values
82 currently in effect for the system (which should typically reflect
83 the hashes of the currently booted kernel). This can be used in
84 place of --linux= and the other switches listed above.
85 --bank=DIGEST
87 Controls the PCR banks to pre-calculate the PCR values for – in
88 case calculate or sign is invoked –, or the banks to show in the
89 status output. May be used more then once to specify multiple
90 banks. If not specified, defaults to the four banks "sha1",
91 "sha256", "sha384", "sha512".
92 --private-key=PATH, --public-key=PATH
94 These switches take paths to a pair of PEM encoded RSA key files,
95 for use with the sign command.
96 Note the difference between the --pcrpkey= and --public-key=
98 switches. The former selects the data to include in the ".pcrpkey"
99 PE section of the unified kernel image, the latter picks the public
100 key of the key pair used to sign the resulting PCR 11 values. The
101 former is the key that the booted system will likely use to lock
102 disk and credential encryption to, the latter is the key used for
103 unlocking such resources again. Hence, typically the same PEM key
104 should be supplied in both cases.
105 If the --public-key= is not specified but --private-key= is
107 specified the public key is automatically derived from the private
108 key.
109 --tpm2-device=PATH
111 Controls which TPM2 device to use. Expects a device node path
112 referring to the TPM2 chip (e.g. /dev/tpmrm0). Alternatively the
113 special value "auto" may be specified, in order to automatically
114 determine the device node of a suitable TPM2 device (of which there
115 must be exactly one). The special value "list" may be used to
116 enumerate all suitable TPM2 devices currently discovered.
117 --phase=PHASE
119 Controls which boot phases to calculate expected PCR 11 values for.
120 This takes a series of colon-separated strings that encode boot
121 "paths" for entering a specific phase of the boot process. Each of
122 the specified strings is measured by the
123 systemd-pcrphase-initrd.service and systemd-pcrphase.service(8)
124 into PCR 11 during different milestones of the boot process. This
125 switch may be specified multiple times to calculate PCR values for
126 multiple boot phases at once. If not used defaults to
127 "enter-initrd", "enter-initrd:leave-initrd",
128 "enter-initrd:leave-initrd:sysinit",
129 "enter-initrd:leave-initrd:sysinit:ready", i.e. calculates expected
130 PCR values for the boot phase in the initrd, during early boot,
131 during later boot, and during system runtime, but excluding the
132 phases before the initrd or when shutting down. This setting is
133 honoured both by calculate and sign. When used with the latter it's
134 particularly useful for generating PCR signatures that can only be
135 used for unlocking resources during specific parts of the boot
136 process.
137 For further details about PCR boot phases, see systemd-
139 pcrphase.service(8).
140 --append=PATH
142 When generating a PCR JSON signature (via the sign command),
143 combine it with a previously generated PCR JSON signature, and
144 output it as one. The specified path must refer to a regular file
145 that contains a valid JSON PCR signature object. The specified file
146 is not modified. It will be read first, then the newly generated
147 signature appended to it, and the resulting object is written to
148 standard output. Use this to generate a single JSON object
149 consisting from signatures made with a number of signing keys (for
150 example, to have one key per boot phase). The command will suppress
151 duplicates: if a specific signature is already included in a JSON
152 signature object it is not added a second time.
153 --json=MODE
155 Shows output formatted as JSON. Expects one of "short" (for the
156 shortest possible output without any redundant whitespace or line
157 breaks), "pretty" (for a pretty version of the same, with
158 indentation and line breaks) or "off" (to turn off JSON output, the
159 default).
160 --no-pager
162 Do not pipe output into a pager.
163 -h, --help
165 Print a short help text and exit.
166 --version
168 Print a short version string and exit.
169
171 Example 1. Generate a unified kernel image, and calculate the expected
172 TPM PCR 11 value
173 $ ukify --output=vmlinux.efi \
175 --os-release=@os-release.txt \
176 --cmdline=@cmdline.txt \
177 --splash=splash.bmp \
178 --devicetree=devicetree.dtb \
179 --measure \
180 vmlinux initrd.cpio
181 11:sha1=d775a7b4482450ac77e03ee19bda90bd792d6ec7
182 11:sha256=bc6170f9ce28eb051ab465cd62be8cf63985276766cf9faf527ffefb66f45651
183 11:sha384=1cf67dff4757e61e5...7f49ad720be02fd07263e1f93061243aec599d1ee4b4
184 11:sha512=8e79acd3ddbbc8282...0c3e8ec0c714821032038f525f744960bcd082d937da
185 ukify(1) internally calls systemd-measure. The output with hashes is
187 from systemd-measure.
188 Example 2. Generate a private/public key pair, a unified kernel image,
190 and a TPM PCR 11 signature for it, and embed the signature and the
191 public key in the image
192 $ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-private.pem
194 ..+.+++++++++......+.........+......+.......+....+.....+.+...+..........
195 $ openssl rsa -pubout -in tpm2-pcr-private.pem -out tpm2-pcr-public.pem
196 # systemd-measure sign \
197 --linux=vmlinux \
198 --osrel=os-release.txt \
199 --cmdline=cmdline.txt \
200 --initrd=initrd.cpio \
201 --splash=splash.bmp \
202 --dtb=devicetree.dtb \
203 --pcrpkey=tpm2-pcr-public.pem \
204 --bank=sha1 \
205 --bank=sha256 \
206 --private-key=tpm2-pcr-private.pem \
207 --public-key=tpm2-pcr-public.pem >tpm2-pcr-signature.json
208 # ukify --output=vmlinuz.efi \
209 --os-release=@os-release.txt \
210 --cmdline=@cmdline.txt \
211 --splash=splash.bmp \
212 --devicetree=devicetree.dtb \
213 --pcr-private-key=tpm2-pcr-private.pem \
214 --pcr-public-key=tpm2-pcr-public.pem \
215 --pcr-banks=sha1,sha256 \
216 vmlinux initrd.cpio
217 Later on, enroll the signed PCR policy on a LUKS volume:
219 # systemd-cryptenroll --tpm2-device=auto \
221 --tpm2-public-key=tpm2-pcr-public.pem \
222 --tpm2-signature=tpm2-pcr-signature.json \
223 /dev/sda5
224 And then unlock the device with the signature:
226 # /usr/lib/systemd/systemd-cryptsetup attach \
228 volume5 /dev/sda5 - \
229 tpm2-device=auto,tpm2-signature=/path/to/tpm2-pcr-signature.json
230 Note that when the generated unified kernel image vmlinux.efi is
232 booted, the signature and public key files will be placed at locations
233 systemd-cryptenroll and systemd-cryptsetup will look for anyway, and
234 thus these paths do not actually need to be specified.
235 Example 3. Introduce a second public key, signing the same kernel PCR
237 measurements, but only for the initrd boot phase
238 This example extends the previous one, but we now introduce a second
240 signing key that is only used to sign PCR policies restricted to the
241 initrd boot phase. This can be used to lock down root volumes in a way
242 that they can only be unlocked before the transition to the host
243 system. Thus we have two classes of secrets or credentials: one that
244 can be unlocked during the entire runtime, and the other that can only
245 be used in the initrd.
246 $ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-private.pem
248 .+........+.+........+.......+...+...+........+....+......+..+..........
249 $ openssl rsa -pubout -in tpm2-pcr-private.pem -out tpm2-pcr-public.pem
250 $ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-initrd-private.pem
251 ..+.......++........+........+......+........+....+.....+.+..+..........
252 $ openssl rsa -pubout -in tpm2-pcr-initrd-private.pem -out tpm2-pcr-initrd-public.pem
253 # ukify --output vmlinux-1.2.3.efi \
254 --os-release=@os-release.txt \
255 --cmdline=@cmdline.txt \
256 --splash=splash.bmp \
257 --devicetree=devicetree.dtb \
258 --pcr-private-key=tpm2-pcr-private.pem \
259 --pcr-public-key=tpm2-pcr-public.pem \
260 --phases=enter-initrd,enter-initrd:leave-initrd,enter-initrd:leave-initrd:sysinit,enter-initrd:leave-initrd:sysinit:ready \
261 --pcr-banks=sha1,sha256 \
262 --pcr-private-key=tpm2-pcr-initrd-private.pem \
263 --pcr-public-key=tpm2-pcr-initrd-public.pem \
264 --phases=enter-initrd \
265 vmlinux-1.2.3 initrd.cpio \
266 --uname=1.2.3
267 + /usr/lib/systemd/systemd-measure sign --linux=vmlinux-1.2.3 \
268 --osrel=os-release.txt --cmdline=cmdline.txt --dtb=devicetree.dtb \
269 --splash=splash.bmp --initrd=initrd.cpio --bank=sha1 --bank=sha256 \
270 --private-key=tpm2-pcr-private.pem --public-key=tpm2-pcr-public.pem \
271 --phase=enter-initrd --phase=enter-initrd:leave-initrd \
272 --phase=enter-initrd:leave-initrd:sysinit \
273 --phase=enter-initrd:leave-initrd:sysinit:ready
274 + /usr/lib/systemd/systemd-measure sign --linux=vmlinux-1.2.3 \
275 --osrel=os-release.txt --cmdline=cmdline.txt --dtb=devicetree.dtb \
276 --splash=splash.bmp --initrd=initrd.cpio --bank=sha1 --bank=sha256 \
277 --private-key=tpm2-pcr-initrd-private.pem \
278 --public-key=tpm2-pcr-initrd-public.pem \
279 --phase=enter-initrd
280 Wrote unsigned vmlinux-1.2.3.efi
281 ukify prints out both invocations of systemd-measure as informative
284 output (the lines starting with "+"); this allows us to see how
285 systemd-measure is called. It then merges the output of both
286 invocations into the ".pcrsig" section. systemd-measure may also do
287 this merge itself using the --append= option.
288 Note that in this example the ".pcrpkey" PE section contains the key
290 specified by the first --pcr-private-key= option, covering all boot
291 phases. The ".pcrpkey" section is used in the default policies of
292 systemd-cryptenroll and systemd-creds. To use the stricter policy bound
293 to tpm-pcr-initrd-public.pem, specify --tpm2-public-key= on the command
294 line of those tools.
295
297 On success, 0 is returned, a non-zero failure code otherwise.
298
300 systemd(1), systemd-stub(7), ukify(1), systemd-creds(1), systemd-
301 cryptsetup@.service(8), systemd-pcrphase.service(8)
302
304 1. Unified Kernel Image (UKI)
305 https://uapi-group.org/specifications/specs/unified_kernel_image/
306systemd 254 SYSTEMD-MEASURE(1)