diff options
author | Lennart Poettering <lennart@poettering.net> | 2022-07-26 00:13:16 +0200 |
---|---|---|
committer | Lennart Poettering <lennart@poettering.net> | 2022-08-02 10:28:49 +0200 |
commit | ca1092dc15ce49d2b677aa326836588839bb6fe1 (patch) | |
tree | b75345da0218fb4857547f9c0982011680130450 /man/systemd-measure.xml | |
parent | 51470e1e5601c8fb5371fbc9e1b3ed69ca61c7a0 (diff) | |
download | systemd-ca1092dc15ce49d2b677aa326836588839bb6fe1.tar.gz |
measure: add new tool to precalculate PCR values for a kernel image
For now, this simply outputs the PCR hash values expected for a kernel
image, if it's measured like sd-stub would do it.
(Later on, we can extend the tool, to optionally sign these
pre-calculated measurements, in order to implement signed PCR policies
for disk encryption.)
Diffstat (limited to 'man/systemd-measure.xml')
-rw-r--r-- | man/systemd-measure.xml | 154 |
1 files changed, 154 insertions, 0 deletions
diff --git a/man/systemd-measure.xml b/man/systemd-measure.xml new file mode 100644 index 0000000000..e6b8d31a88 --- /dev/null +++ b/man/systemd-measure.xml @@ -0,0 +1,154 @@ +<?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>--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="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> |