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