mirror of
https://github.com/systemd/systemd
synced 2024-07-22 10:44:58 +00:00
127b72da2b
This allows allows shortcutting measurements of the specified files and use the information from /sys/ instead. This is not too useful on its own given that "systemd-measure status" already exists which displays the current, relevant PCR values. The main difference is how "complete" the information is. "status" will detect if the measurements make any sense, and show more than PCR 11. "calculate --current" otoh only reads PCR 11 and uses that, and that's really it. This is mainly preparation for later work to add PCR signing to the tool, where usually it makes most sense to sign prepared kernel images, but for testing it's really useful to shortcut signing to the current PCR values instead
165 lines
7 KiB
XML
165 lines
7 KiB
XML
<?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='HAVE_GNU_EFI'>
|
||
|
||
<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 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 the expected TPM2
|
||
PCR 11 values that should be seen when a unified Linux kernel image based on
|
||
<citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> is
|
||
booted up. It accepts paths to the ELF kernel image file, initial ram disk image file, devicetree file,
|
||
kernel command line file,
|
||
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file, and
|
||
boot splash 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.</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></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>calculate</command></term>
|
||
|
||
<listitem><para>Pre-calculate the expected value 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>, see below. Only <option>--linux=</option> is
|
||
mandatory.</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Options</title>
|
||
|
||
<para>The following options are understood:</para>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term><option>--linux=PATH</option></term>
|
||
<term><option>--osrel=PATH</option></term>
|
||
<term><option>--cmdline=PATH</option></term>
|
||
<term><option>--initrd=PATH</option></term>
|
||
<term><option>--splash=PATH</option></term>
|
||
<term><option>--dtb=PATH</option></term>
|
||
|
||
<listitem><para>When used with the <command>calculate</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></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>--current</option></term>
|
||
<listitem><para>When used with the <command>calculate</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></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>--bank=DIGEST</option></term>
|
||
|
||
<listitem><para>Controls the PCR banks to pre-calculate the PCR values for – in case
|
||
<command>calculate</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></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># objcopy \
|
||
--add-section .linux=vmlinux --change-section-vma .linux=0x2000000 \
|
||
--add-section .osrel=os-release.txt --change-section-vma .osrel=0x20000 \
|
||
--add-section .cmdline=cmdline.txt --change-section-vma .cmdline=0x30000 \
|
||
--add-section .initrd=initrd.cpio --change-section-vma .initrd=0x3000000 \
|
||
--add-section .splash=splash.bmp --change-section-vma .splash=0x100000 \
|
||
--add-section .dtb=devicetree.dtb --change-section-vma .dtb=0x40000 \
|
||
/usr/lib/systemd/boot/efi/linuxx64.efi.stub \
|
||
foo.efi
|
||
# systemd-measure calculate \
|
||
--linux=vmlinux \
|
||
--osrel=os-release \
|
||
--cmdline=cmdline.txt \
|
||
--initrd=initrd.cpio \
|
||
--splash=splash.bmp \
|
||
--dtb=devicetree.dtb
|
||
11:sha1=d775a7b4482450ac77e03ee19bda90bd792d6ec7
|
||
11:sha256=bc6170f9ce28eb051ab465cd62be8cf63985276766cf9faf527ffefb66f45651
|
||
11:sha384=1cf67dff4757e61e5a73d2a21a6694d668629bbc3761747d493f7f49ad720be02fd07263e1f93061243aec599d1ee4b4
|
||
11:sha512=8e79acd3ddbbc8282e98091849c3530f996303c8ac8e87a3b2378b71c8b3a6e86d5c4f41ecea9e1517090c3e8ec0c714821032038f525f744960bcd082d937da
|
||
</programlisting>
|
||
</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 project='man-pages'><refentrytitle>objcopy</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||
</para>
|
||
</refsect1>
|
||
|
||
</refentry>
|