diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/systemd-measure.xml | 159 | ||||
| -rw-r--r-- | man/udev.xml | 15 | ||||
| -rw-r--r-- | man/ukify.xml | 35 |
3 files changed, 123 insertions, 86 deletions
diff --git a/man/systemd-measure.xml b/man/systemd-measure.xml index 950aeebc54..0df3602223 100644 --- a/man/systemd-measure.xml +++ b/man/systemd-measure.xml @@ -33,16 +33,23 @@ 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 and sign the - expected TPM2 PCR 11 values that should be seen when a unified Linux kernel image based on + expected TPM2 PCR 11 values that should be seen when a Linux <ulink + url="https://uapi-group.org/specifications/specs/unified_kernel_image/">Unified Kernel Image + (UKI)</ulink> based on <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> is booted up. It accepts paths to the ELF kernel image file, initrd image file, devicetree file, kernel command line file, <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file, boot splash file, and TPM2 PCR PEM public key 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. The result may optionally be signed cryptographically, to allow TPM2 policies that can only be - unlocked if a certain set of kernels is booted, for which such a PCR signature can be provided.</para> + PCR 11, and is executed in a fashion compatible with what <filename>systemd-stub</filename> does at boot. + The result may optionally be signed cryptographically, to allow TPM2 policies that can only be unlocked + if a certain set of kernels is booted, for which such a PCR signature can be provided.</para> + + <para>It usually doesn't make sense to call this tool directly when constructing a UKI. Instead, + <citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry> should be used; + it will invoke <command>systemd-measure</command> and take care of embedding the resulting measurements + into the UKI.</para> </refsect1> <refsect1> @@ -209,26 +216,31 @@ <example> <title>Generate a unified kernel image, and calculate the expected TPM PCR 11 value</title> - <programlisting># ukify --output foo.efi \ - --os-release @os-release.txt \ - --cmdline @cmdline.txt \ - --splash splash.bmp \ - --devicetree devicetree.dtb \ + <programlisting>$ ukify --output=vmlinux.efi \ + --os-release=@os-release.txt \ + --cmdline=@cmdline.txt \ + --splash=splash.bmp \ + --devicetree=devicetree.dtb \ --measure \ vmlinux initrd.cpio 11:sha1=d775a7b4482450ac77e03ee19bda90bd792d6ec7 11:sha256=bc6170f9ce28eb051ab465cd62be8cf63985276766cf9faf527ffefb66f45651 -11:sha384=1cf67dff4757e61e5a73d2a21a6694d668629bbc3761747d493f7f49ad720be02fd07263e1f93061243aec599d1ee4b4 -11:sha512=8e79acd3ddbbc8282e98091849c3530f996303c8ac8e87a3b2378b71c8b3a6e86d5c4f41ecea9e1517090c3e8ec0c714821032038f525f744960bcd082d937da +11:sha384=1cf67dff4757e61e5...7f49ad720be02fd07263e1f93061243aec599d1ee4b4 +11:sha512=8e79acd3ddbbc8282...0c3e8ec0c714821032038f525f744960bcd082d937da </programlisting> + + <para><citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry> + internally calls <command>systemd-measure</command>. The output with hashes is from + <command>systemd-measure</command>.</para> </example> <example> - <title>Generate a private/public key pair, and a unified kernel image, and a TPM PCR 11 signature for + <title>Generate a private/public key pair, a unified kernel image, and a TPM PCR 11 signature for it, and embed the signature and the public key in the image</title> - <programlisting># openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-private.pem -# openssl rsa -pubout -in tpm2-pcr-private.pem -out tpm2-pcr-public.pem + <programlisting>$ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-private.pem +..+.+++++++++......+.........+......+.......+....+.....+.+...+.......... +$ openssl rsa -pubout -in tpm2-pcr-private.pem -out tpm2-pcr-public.pem # systemd-measure sign \ --linux=vmlinux \ --osrel=os-release.txt \ @@ -241,25 +253,30 @@ --bank=sha256 \ --private-key=tpm2-pcr-private.pem \ --public-key=tpm2-pcr-public.pem >tpm2-pcr-signature.json -# ukify --output foo.efi \ - --os-release @os-release.txt \ - --cmdline @cmdline.txt \ - --splash splash.bmp \ - --devicetree devicetree.dtb \ - --pcr-private-key tpm2-pcr-private.pem \ - --pcr-public-key tpm2-pcr-public.pem \ - --pcr-banks sha1,sha256 \ +# ukify --output=vmlinuz.efi \ + --os-release=@os-release.txt \ + --cmdline=@cmdline.txt \ + --splash=splash.bmp \ + --devicetree=devicetree.dtb \ + --pcr-private-key=tpm2-pcr-private.pem \ + --pcr-public-key=tpm2-pcr-public.pem \ + --pcr-banks=sha1,sha256 \ vmlinux initrd.cpio</programlisting> <para>Later on, enroll the signed PCR policy on a LUKS volume:</para> - <programlisting># systemd-cryptenroll --tpm2-device=auto --tpm2-public-key=tpm2-pcr-public.pem --tpm2-signature=tpm2-pcr-signature.json /dev/sda5</programlisting> + <programlisting># systemd-cryptenroll --tpm2-device=auto \ + --tpm2-public-key=tpm2-pcr-public.pem \ + --tpm2-signature=tpm2-pcr-signature.json \ + /dev/sda5</programlisting> <para>And then unlock the device with the signature:</para> - <programlisting># /usr/lib/systemd/systemd-cryptsetup attach myvolume /dev/sda5 - tpm2-device=auto,tpm2-signature=/path/to/tpm2-pcr-signature.json</programlisting> + <programlisting># /usr/lib/systemd/systemd-cryptsetup attach \ + volume5 /dev/sda5 - \ + tpm2-device=auto,tpm2-signature=/path/to/tpm2-pcr-signature.json</programlisting> - <para>Note that when the generated unified kernel image <filename>foo.efi</filename> is booted the + <para>Note that when the generated unified kernel image <filename>vmlinux.efi</filename> is booted, the signature and public key files will be placed at locations <command>systemd-cryptenroll</command> and <command>systemd-cryptsetup</command> will look for anyway, and thus these paths do not actually need to be specified.</para> @@ -274,53 +291,55 @@ two classes of secrets or credentials: one that can be unlocked during the entire runtime, and the other that can only be used in the initrd.</para> - <programlisting># openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-private.pem -# openssl rsa -pubout -in tpm2-pcr-private.pem -out tpm2-pcr-public.pem -# systemd-measure sign \ - --linux=vmlinux \ - --osrel=os-release.txt \ - --cmdline=cmdline.txt \ - --initrd=initrd.cpio \ + <programlisting>$ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-private.pem +.+........+.+........+.......+...+...+........+....+......+..+.......... +$ openssl rsa -pubout -in tpm2-pcr-private.pem -out tpm2-pcr-public.pem +$ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-initrd-private.pem +..+.......++........+........+......+........+....+.....+.+..+.......... +$ openssl rsa -pubout -in tpm2-pcr-initrd-private.pem -out tpm2-pcr-initrd-public.pem +# ukify --output vmlinux-1.2.3.efi \ + --os-release=@os-release.txt \ + --cmdline=@cmdline.txt \ --splash=splash.bmp \ - --dtb=devicetree.dtb \ - --pcrpkey=tpm2-pcr-public.pem \ - --bank=sha1 \ - --bank=sha256 \ - --private-key=tpm2-pcr-private.pem \ - --public-key=tpm2-pcr-public.pem >tpm2-pcr-signature.json.tmp -# openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-initrd-private.pem -# openssl rsa -pubout -in tpm2-pcr-initrd-private.pem -out tpm2-pcr-initrd-public.pem -# systemd-measure sign \ - --linux=vmlinux \ - --osrel=os-release.txt \ - --cmdline=cmdline.txt \ - --initrd=initrd.cpio \ - --splash=splash.bmp \ - --dtb=devicetree.dtb \ - --pcrpkey=tpm2-pcr-public.pem \ - --bank=sha1 \ - --bank=sha256 \ - --private-key=tpm2-pcr-initrd-private.pem \ - --public-key=tpm2-pcr-initrd-public.pem \ - --phase=enter-initrd \ - --append=tpm2-pcr-signature.json.tmp >tpm2-pcr-signature.json -# ukify --output foo.efi \ - --os-release @os-release.txt \ - --cmdline @cmdline.txt \ - --splash splash.bmp \ - --devicetree devicetree.dtb \ - --pcr-private-key tpm2-pcr-initrd-private.pem \ - --pcr-public-key tpm2-pcr-initrd-public.pem \ - --section .pcrsig=@tpm2-pcr-signature.json \ - --section .pcrpkey=@tpm2-pcr-public.pem \ - vmlinux initrd.cpio</programlisting> + --devicetree=devicetree.dtb \ + --pcr-private-key=tpm2-pcr-private.pem \ + --pcr-public-key=tpm2-pcr-public.pem \ + --phases=enter-initrd,enter-initrd:leave-initrd,enter-initrd:leave-initrd:sysinit,enter-initrd:leave-initrd:sysinit:ready \ + --pcr-banks=sha1,sha256 \ + --pcr-private-key=tpm2-pcr-initrd-private.pem \ + --pcr-public-key=tpm2-pcr-initrd-public.pem \ + --phases=enter-initrd \ + vmlinux-1.2.3 initrd.cpio \ + --uname=1.2.3 ++ /usr/lib/systemd/systemd-measure sign --linux=vmlinux-1.2.3 \ +--osrel=os-release.txt --cmdline=cmdline.txt --dtb=devicetree.dtb \ +--splash=splash.bmp --initrd=initrd.cpio --bank=sha1 --bank=sha256 \ +--private-key=tpm2-pcr-private.pem --public-key=tpm2-pcr-public.pem \ +--phase=enter-initrd --phase=enter-initrd:leave-initrd \ +--phase=enter-initrd:leave-initrd:sysinit \ +--phase=enter-initrd:leave-initrd:sysinit:ready ++ /usr/lib/systemd/systemd-measure sign --linux=vmlinux-1.2.3 \ +--osrel=os-release.txt --cmdline=cmdline.txt --dtb=devicetree.dtb \ +--splash=splash.bmp --initrd=initrd.cpio --bank=sha1 --bank=sha256 \ +--private-key=tpm2-pcr-initrd-private.pem \ +--public-key=tpm2-pcr-initrd-public.pem \ +--phase=enter-initrd +Wrote unsigned vmlinux-1.2.3.efi + </programlisting> + + <para><command>ukify</command> prints out both invocations of <command>systemd-measure</command> as + informative output (the lines starting with <literal>+</literal>); this allows us to see how + <command>systemd-measure</command> is called. It then merges the output of both invocations into the + <literal>.pcrsig</literal> section. <command>systemd-measure</command> may also do this merge itself + using the <option>--append=</option> option.</para> + + <para>Note that in this example the <literal>.pcrpkey</literal> PE section contains the key specified + by the first <option>--pcr-private-key=</option> option, covering all boot phases. The + <literal>.pcrpkey</literal> section is used in the default policies of + <command>systemd-cryptenroll</command> and <command>systemd-creds</command>. To use the stricter policy + bound to <filename>tpm-pcr-initrd-public.pem</filename>, specify <option>--tpm2-public-key=</option> on + the command line of those tools.</para> </example> - - <para>Note that in this example the <literal>.pcrpkey</literal> PE section contains the key covering all - boot phases. The <literal>.pcrpkey</literal> is used in the default policies of - <command>systemd-cryptenroll</command> and <command>systemd-creds</command>. To use the stricter - <filename>tpm-pcr-initrd-public.pem</filename>-bound policy, specify <option>--tpm2-public-key=</option> - on the command line of those tools.</para> </refsect1> <refsect1> diff --git a/man/udev.xml b/man/udev.xml index 142f295f3e..332c7ac096 100644 --- a/man/udev.xml +++ b/man/udev.xml @@ -186,10 +186,10 @@ <varlistentry> <term><varname>SYMLINK</varname></term> <listitem> - <para>Match the name of a symlink targeting the node. It can - be used once a SYMLINK key has been set in one of the preceding - rules. There may be multiple symlinks; only one needs to match. - </para> + <para>Match the name of a symlink targeting the node. It can be used once a SYMLINK key has + been set in one of the preceding rules. There may be multiple symlinks; only one needs to + match. If the operator is <literal>!=</literal>, the token returns true only if there is no + symlink matched.</para> </listitem> </varlistentry> @@ -287,14 +287,17 @@ <varlistentry> <term><varname>TAG</varname></term> <listitem> - <para>Match against a device tag.</para> + <para>Match against one of device tags. It can be used once a TAG key has been set in one of + the preceding rules. There may be multiple tags; only one needs to match. If the operator is + <literal>!=</literal>, the token returns true only if there is no tag matched.</para> </listitem> </varlistentry> <varlistentry> <term><varname>TAGS</varname></term> <listitem> - <para>Search the devpath upwards for a device with matching tag.</para> + <para>Search the devpath upwards for a device with matching tag. If the operator is + <literal>!=</literal>, the token returns true only if there is no tag matched.</para> </listitem> </varlistentry> diff --git a/man/ukify.xml b/man/ukify.xml index c3c0d3f2df..c6bfbdc9d9 100644 --- a/man/ukify.xml +++ b/man/ukify.xml @@ -17,14 +17,14 @@ <refnamediv> <refname>ukify</refname> - <refpurpose>Combine kernel and initrd into a signed Unified Kernel Image</refpurpose> + <refpurpose>Combine components into a signed Unified Kernel Image for UEFI systems</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>/usr/lib/systemd/ukify</command> - <arg choice="plain"><replaceable>LINUX</replaceable></arg> - <arg choice="plain" rep="repeat"><replaceable>INITRD</replaceable></arg> + <arg choice="opt"><replaceable>LINUX</replaceable></arg> + <arg choice="opt" rep="repeat"><replaceable>INITRD</replaceable></arg> <arg choice="opt" rep="repeat">OPTIONS</arg> </cmdsynopsis> </refsynopsisdiv> @@ -35,8 +35,8 @@ <para>Note: this command is experimental for now. While it is intended to become a regular component of systemd, it might still change in behaviour and interface.</para> - <para><command>ukify</command> is a tool that combines a kernel and an initrd with - a UEFI boot stub to create a + <para><command>ukify</command> is a tool that combines components (e.g.: a kernel and an initrd with + a UEFI boot stub) to create a <ulink url="https://uapi-group.org/specifications/specs/unified_kernel_image/">Unified Kernel Image (UKI)</ulink> — a PE binary that can be executed by the firmware to start the embedded linux kernel. See <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> @@ -53,6 +53,9 @@ and <option>--section=</option> below.</para> + <para><command>ukify</command> can also be used to assemble a PE binary that is not executable but + contains auxiliary data, for example additional kernel command line entries.</para> + <para>If PCR signing keys are provided via the <option>--pcr-public-key=</option> and <option>--pcr-private-key=</option> options, PCR values that will be seen after booting with the given kernel, initrd, and other sections, will be calculated, signed, and embedded in the UKI. @@ -60,7 +63,7 @@ used to perform this calculation and signing.</para> <para>The calculation of PCR values is done for specific boot phase paths. Those can be specified with - <option>--phases=</option> option. If not specified, the default provided by + the <option>--phases=</option> option. If not specified, the default provided by <command>systemd-measure</command> is used. It is also possible to specify the <option>--pcr-private-key=</option>, <option>--pcr-public-key=</option>, and <option>--phases=</option> arguments more than once. Signatures will be then performed with each of the specified keys. When both @@ -78,10 +81,9 @@ <refsect1> <title>Options</title> - <para>Note that the <replaceable>LINUX</replaceable> positional argument is mandatory. The - <replaceable>INITRD</replaceable> positional arguments are optional. If more than one is specified, they - will all be combined into a single PE section. This is useful to for example prepend microcode before the - actual initrd.</para> + <para>The <replaceable>LINUX</replaceable> and <replaceable>INITRD</replaceable> positional arguments are + optional. If more than one <replaceable>INITRD</replaceable> are specified, they will all be combined into + a single PE section. This is useful to for example prepend microcode before the actual initrd.</para> <para>The following options are understood:</para> @@ -296,6 +298,19 @@ key <filename index='false'>pcr-private-system-key.pem</filename>. The Linux binary and the resulting combined image will be signed with the SecureBoot key <filename index='false'>sb.key</filename>.</para> </example> + + <example> + <title>Kernel command line auxiliary PE</title> + + <programlisting>ukify \ + --secureboot-private-key=sb.key \ + --secureboot-certificate=sb.cert \ + --cmdline='debug' \ + --output=debug.cmdline.efi + </programlisting> + + <para>This creates a signed PE binary that contains an additional kernel command line parameter.</para> + </example> </refsect1> <refsect1> |