]>
Commit | Line | Data |
---|---|---|
ca1092dc LP |
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.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'> | |
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 expected TPM2 PCR values for booted unified kernel images</refpurpose> | |
21 | </refnamediv> | |
22 | ||
23 | <refsynopsisdiv> | |
24 | <cmdsynopsis> | |
25 | <command>/usr/lib/systemd/systemd-measure <arg choice="opt" rep="repeat">OPTIONS</arg></command> | |
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 the expected TPM2 | |
36 | 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, initial ram disk image file, devicetree file, | |
39 | kernel command line file, | |
40 | <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file, and | |
41 | boot splash file that make up the unified kernel image, and determines the PCR values expected to be in | |
42 | place after booting the image. Calculation starts with a zero-initialized PCR 11, and is executed in a | |
43 | fashion compatible with what <filename>systemd-stub</filename> does at boot.</para> | |
44 | </refsect1> | |
45 | ||
46 | <refsect1> | |
47 | <title>Commands</title> | |
48 | ||
49 | <para>The following commands are understood:</para> | |
50 | ||
51 | <variablelist> | |
52 | <varlistentry> | |
53 | <term><command>status</command></term> | |
54 | ||
55 | <listitem><para>This is the default command if none is specified. This queries the local system's | |
56 | TPM2 PCR 11+12+13 values and displays them. The data is written in a similar format as the | |
57 | <command>calculate</command> command below, and may be used to quickly compare expectation with | |
58 | reality.</para></listitem> | |
59 | </varlistentry> | |
60 | ||
61 | <varlistentry> | |
62 | <term><command>calculate</command></term> | |
63 | ||
64 | <listitem><para>Pre-calculate the expected value seen in PCR register 11 after boot-up of a unified | |
65 | kernel image consisting of the components specified with <option>--linux=</option>, | |
66 | <option>--osrel=</option>, <option>--cmdline=</option>, <option>--initrd=</option>, | |
67 | <option>--splash=</option>, <option>--dtb=</option>, see below. Only <option>--linux=</option> is | |
68 | mandatory.</para></listitem> | |
69 | </varlistentry> | |
70 | </variablelist> | |
71 | </refsect1> | |
72 | ||
73 | <refsect1> | |
74 | <title>Options</title> | |
75 | ||
76 | <para>The following options are understood:</para> | |
77 | ||
78 | <variablelist> | |
79 | <varlistentry> | |
80 | <term><option>--linux=PATH</option></term> | |
81 | <term><option>--osrel=PATH</option></term> | |
82 | <term><option>--cmdline=PATH</option></term> | |
83 | <term><option>--initrd=PATH</option></term> | |
84 | <term><option>--splash=PATH</option></term> | |
85 | <term><option>--dtb=PATH</option></term> | |
86 | ||
87 | <listitem><para>When used with the <command>calculate</command> verb, configures the files to read | |
88 | the unified kernel image components from. Each option corresponds with the equally named section in | |
89 | the unified kernel PE file. The <option>--linux=</option> switch expects the path to the ELF kernel | |
90 | file that the unified PE kernel will wrap. All switches except <option>--linux=</option> are | |
91 | optional. Each option may be used at most once.</para></listitem> | |
92 | </varlistentry> | |
93 | ||
127b72da LP |
94 | <varlistentry> |
95 | <term><option>--current</option></term> | |
96 | <listitem><para>When used with the <command>calculate</command> verb, takes the PCR 11 values | |
97 | currently in effect for the system (which should typically reflect the hashes of the currently booted | |
98 | kernel). This can be used in place of <option>--linux=</option> and the other switches listed | |
99 | above.</para></listitem> | |
100 | </varlistentry> | |
101 | ||
ca1092dc LP |
102 | <varlistentry> |
103 | <term><option>--bank=DIGEST</option></term> | |
104 | ||
105 | <listitem><para>Controls the PCR banks to pre-calculate the PCR values for – in case | |
106 | <command>calculate</command> is invoked –, or the banks to show in the <command>status</command> | |
107 | output. May be used more then once to specify multiple banks. If not specified, defaults to the four | |
108 | banks <literal>sha1</literal>, <literal>sha256</literal>, <literal>sha384</literal>, | |
109 | <literal>sha512</literal>.</para></listitem> | |
110 | </varlistentry> | |
111 | ||
c06b6d46 LP |
112 | <xi:include href="standard-options.xml" xpointer="json" /> |
113 | <xi:include href="standard-options.xml" xpointer="no-pager" /> | |
ca1092dc LP |
114 | <xi:include href="standard-options.xml" xpointer="help" /> |
115 | <xi:include href="standard-options.xml" xpointer="version" /> | |
116 | </variablelist> | |
117 | </refsect1> | |
118 | ||
119 | <refsect1> | |
120 | <title>Examples</title> | |
121 | ||
122 | <example> | |
123 | <title>Generate a unified kernel image, and calculate the expected TPM PCR 11 value</title> | |
124 | ||
125 | <programlisting># objcopy \ | |
126 | --add-section .linux=vmlinux --change-section-vma .linux=0x2000000 \ | |
127 | --add-section .osrel=os-release.txt --change-section-vma .osrel=0x20000 \ | |
128 | --add-section .cmdline=cmdline.txt --change-section-vma .cmdline=0x30000 \ | |
129 | --add-section .initrd=initrd.cpio --change-section-vma .initrd=0x3000000 \ | |
130 | --add-section .splash=splash.bmp --change-section-vma .splash=0x100000 \ | |
131 | --add-section .dtb=devicetree.dtb --change-section-vma .dtb=0x40000 \ | |
132 | /usr/lib/systemd/boot/efi/linuxx64.efi.stub \ | |
133 | foo.efi | |
134 | # systemd-measure calculate \ | |
135 | --linux=vmlinux \ | |
136 | --osrel=os-release \ | |
137 | --cmdline=cmdline.txt \ | |
138 | --initrd=initrd.cpio \ | |
139 | --splash=splash.bmp \ | |
140 | --dtb=devicetree.dtb | |
141 | 11:sha1=d775a7b4482450ac77e03ee19bda90bd792d6ec7 | |
142 | 11:sha256=bc6170f9ce28eb051ab465cd62be8cf63985276766cf9faf527ffefb66f45651 | |
143 | 11:sha384=1cf67dff4757e61e5a73d2a21a6694d668629bbc3761747d493f7f49ad720be02fd07263e1f93061243aec599d1ee4b4 | |
144 | 11:sha512=8e79acd3ddbbc8282e98091849c3530f996303c8ac8e87a3b2378b71c8b3a6e86d5c4f41ecea9e1517090c3e8ec0c714821032038f525f744960bcd082d937da | |
145 | </programlisting> | |
146 | </example> | |
147 | </refsect1> | |
148 | ||
149 | <refsect1> | |
150 | <title>Exit status</title> | |
151 | ||
152 | <para>On success, 0 is returned, a non-zero failure code otherwise.</para> | |
153 | </refsect1> | |
154 | ||
155 | <refsect1> | |
156 | <title>See Also</title> | |
157 | <para> | |
158 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
159 | <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>, | |
160 | <citerefentry project='man-pages'><refentrytitle>objcopy</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
161 | </para> | |
162 | </refsect1> | |
163 | ||
164 | </refentry> |