Skip to content

Add stand-alone dm integrity support #20902

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 15, 2021
Merged

Add stand-alone dm integrity support #20902

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9a2a6ec
dm-verity: Remove usage of integrity
tasleson Oct 13, 2021
1f1a224
Add stand-alone dm-integrity support
tasleson Sep 26, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/ENVIRONMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,10 @@ All tools:
useful for debugging. Currently only supported by
`systemd-cryptsetup-generator`.

* `$SYSTEMD_INTEGRITYTAB` — if set, use this path instead of
`/etc/integritytab`. Only useful for debugging. Currently only supported by
`systemd-integritysetup-generator`.

* `$SYSTEMD_VERITYTAB` — if set, use this path instead of
`/etc/veritytab`. Only useful for debugging. Currently only supported by
`systemd-veritysetup-generator`.
Expand Down
161 changes: 161 additions & 0 deletions man/integritytab.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
<?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="integritytab" conditional='HAVE_LIBCRYPTSETUP' xmlns:xi="http://www.w3.org/2001/XInclude">

<refentryinfo>
<title>integritytab</title>
<productname>systemd</productname>
</refentryinfo>

<refmeta>
<refentrytitle>integritytab</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>

<refnamediv>
<refname>integritytab</refname>
<refpurpose>Configuration for integrity block devices</refpurpose>
</refnamediv>

<refsynopsisdiv>
<para><filename>/etc/integritytab</filename></para>
</refsynopsisdiv>

<refsect1>
<title>Description</title>

<para>The <filename>/etc/integritytab</filename> file describes
integrity protected block devices that are set up during
system boot.</para>

<para>Empty lines and lines starting with the <literal>#</literal>
character are ignored. Each of the remaining lines describes one
verity integrity protected block device. Fields are delimited by
white space.</para>

<para>Each line is in the form<programlisting><replaceable>volume-name</replaceable> <replaceable>block-device</replaceable>
<replaceable>[keyfile|-]</replaceable> <replaceable>[options|-]</replaceable></programlisting>
The first two fields are mandatory, the remaining two are optional and only required if user specified non-default options during integrity format.</para>

<para>The first field contains the name of the resulting integrity volume; its block device is set up
below <filename>/dev/mapper/</filename>.</para>

<para>The second field contains a path to the underlying block device, or a specification of a block device via
<literal>UUID=</literal> followed by the UUID,
<literal>PARTUUID=</literal> followed by the partition UUID,
<literal>LABEL=</literal> followed by the label,
<literal>PARTLABEL=</literal> followed by the partition label,
</para>

<para>The third field if present contains an absolute filename path to a key file or a <literal>-</literal>
to specify none. When the filename is present, the "integrity-algorithm" defaults to <literal>hmac-sha256</literal>
with the key length derived from the number of bytes in the key file. At this time the only supported integrity algorithm
when using key file is hmac-sha256. The maximum size of the key file is 4096 bytes.
</para>

<para>The fourth field, if present, is a comma-delimited list of options or a <literal>-</literal> to specify none. The following options are
recognized:</para>
<variablelist>

<varlistentry>
<term><option>allow-discards</option></term>

<listitem><para>
Allow the use of discard (TRIM) requests for the device.
This option is available since the Linux kernel version 5.7.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>journal-watermark=[0..100]%</option></term>

<listitem><para>
Journal watermark in percent. When the journal percentage exceeds this watermark, the journal flush will be started. Setting a value of
"0%" uses default value.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>journal-commit-time=[0..N]</option></term>

<listitem><para>
Commit time in milliseconds. When this time passes (and no explicit flush operation was issued), the journal is written. Setting a value of
zero uses default value.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>data-device=/dev/disk/by-...</option></term>

<listitem><para>
Specify a separate block device that contains existing data. The second field specified in the
integritytab for block device then will contain calculated integrity tags and journal for data-device,
but not the end user data.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>integrity-algorithm=[crc32c|crc32|sha1|sha256|hmac-sha256]</option></term>

<listitem><para>
The algorithm used for integrity checking. The default is crc32c. Must match option used during format.
</para></listitem>
</varlistentry>
</variablelist>

<para>At early boot and when the system manager configuration is
reloaded, this file is translated into native systemd units by
<citerefentry><refentrytitle>systemd-integritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
</refsect1>

<refsect1>
<title>Examples</title>
<example>
<title>/etc/integritytab</title>
<para>Set up two integrity protected block devices. </para>

<programlisting>home PARTUUID=4973d0b8-1b15-c449-96ec-94bab7f6a7b8 - journal-commit-time=10,allow-discards,journal-watermark=55%
data PARTUUID=5d4b1808-be76-774d-88af-03c4c3a41761 - allow-discards
</programlisting>
</example>

<example>
<title>/etc/integritytab</title>
<para>Set up 1 integrity protected block device using defaults </para>

<programlisting>home PARTUUID=4973d0b8-1b15-c449-96ec-94bab7f6a7b8</programlisting>
</example>

<example>
<title>/etc/integritytab</title>
<para>Set up 1 integrity device using existing data block device which contains user data </para>

<programlisting>home PARTUUID=4973d0b8-1b15-c449-96ec-94bab7f6a7b8 - data-device=/dev/disk/by-uuid/9276d9c0-d4e3-4297-b4ff-3307cd0d092f</programlisting>
</example>

<example>
<title>/etc/integritytab</title>
<para>Set up 1 integrity device using a HMAC key file using defaults </para>

<programlisting>home PARTUUID=4973d0b8-1b15-c449-96ec-94bab7f6a7b8 /etc/hmac.key</programlisting>
</example>

</refsect1>

<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-integritysetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-integritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry project='die-net'><refentrytitle>integritysetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
</para>
</refsect1>

</refentry>
6 changes: 6 additions & 0 deletions man/rules/meson.build
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ manpages = [
['hostname', '5', [], ''],
['hostnamectl', '1', [], 'ENABLE_HOSTNAMED'],
['hwdb', '7', [], 'ENABLE_HWDB'],
['integritytab', '5', [], 'HAVE_LIBCRYPTSETUP'],
['journal-remote.conf', '5', ['journal-remote.conf.d'], 'HAVE_MICROHTTPD'],
['journal-upload.conf', '5', ['journal-upload.conf.d'], 'HAVE_MICROHTTPD'],
['journalctl', '1', [], ''],
Expand Down Expand Up @@ -882,6 +883,11 @@ manpages = [
'8',
['systemd-initctl', 'systemd-initctl.socket'],
'HAVE_SYSV_COMPAT'],
['systemd-integritysetup-generator', '8', [], 'HAVE_LIBCRYPTSETUP'],
['systemd-integritysetup@.service',
'8',
['systemd-integritysetup'],
'HAVE_LIBCRYPTSETUP'],
['systemd-journal-gatewayd.service',
'8',
['systemd-journal-gatewayd', 'systemd-journal-gatewayd.socket'],
Expand Down
48 changes: 48 additions & 0 deletions man/systemd-integritysetup-generator.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
<?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-integritysetup-generator" conditional='HAVE_LIBCRYPTSETUP'>

<refentryinfo>
<title>systemd-integritysetup-generator</title>
<productname>systemd</productname>
</refentryinfo>

<refmeta>
<refentrytitle>systemd-integritysetup-generator</refentrytitle>
<manvolnum>8</manvolnum>
</refmeta>

<refnamediv>
<refname>systemd-integritysetup-generator</refname>
<refpurpose>Unit generator for integrity protected block devices</refpurpose>
</refnamediv>

<refsynopsisdiv>
<para><filename>/usr/lib/systemd/system-generators/systemd-integritysetup-generator</filename></para>
</refsynopsisdiv>

<refsect1>
<title>Description</title>

<para><filename>systemd-integritysetup-generator</filename> is a generator that translates <filename>/etc/integritytab</filename> entries into
native systemd units early at boot. This will create
<citerefentry><refentrytitle>systemd-integritysetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
units as necessary.</para>

<para><command>systemd-integritysetup-generator</command> implements
<citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
</refsect1>

<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-integritysetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry project='die-net'><refentrytitle>integritysetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
</para>
</refsect1>

</refentry>
95 changes: 95 additions & 0 deletions man/systemd-integritysetup@.service.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
<?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-integritysetup@.service" conditional='HAVE_LIBCRYPTSETUP'>

<refentryinfo>
<title>systemd-integritysetup@.service</title>
<productname>systemd</productname>
</refentryinfo>

<refmeta>
<refentrytitle>systemd-integritysetup@.service</refentrytitle>
<manvolnum>8</manvolnum>
</refmeta>

<refnamediv>
<refname>systemd-integritysetup@.service</refname>
<refname>systemd-integritysetup</refname>
<refpurpose>Disk integrity protection logic</refpurpose>
</refnamediv>

<refsynopsisdiv>
<para><filename>systemd-integritysetup@.service</filename></para>
<para><filename>/usr/lib/systemd/systemd-integritysetup</filename></para>
</refsynopsisdiv>

<refsect1>
<title>Description</title>

<para><filename>systemd-integritysetup@.service</filename> is a service responsible for setting up integrity
protected block devices. It should be instantiated for each device that requires integrity
protection.</para>

<para>At early boot and when the system manager configuration is reloaded, entries from /etc/integritytab are converted into
<filename>systemd-integritysetup@.service</filename> units by
<citerefentry><refentrytitle>systemd-integritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>

<para><filename>systemd-integritysetup@.service</filename> calls <command>systemd-integritysetup</command>.</para>
</refsect1>

<refsect1>
<title>Commands</title>

<para>The following commands are understood by <command>systemd-integritysetup</command>:</para>

<variablelist>
<varlistentry>
<term>
<option>attach</option>
<replaceable>volume</replaceable>
<replaceable>device</replaceable>
[<replaceable>key-file|-</replaceable>]
[<replaceable>option(s)|-</replaceable>]
</term>

<listitem><para>Create a block device <replaceable>volume</replaceable> using
<replaceable>device</replaceable>. See integritytab man page and
<ulink url="https://www.kernel.org/doc/html/latest/admin-guide/device-mapper/dm-integrity.html">
Kernel dm-integrity</ulink> documentation for details.
</para></listitem>
</varlistentry>

<varlistentry>
<term>
<option>detach</option>
<replaceable>volume</replaceable>
</term>

<listitem><para>Detach (destroy) the block device
<replaceable>volume</replaceable>.</para></listitem>
</varlistentry>

<varlistentry>
<term>
<option>help</option>
</term>

<listitem><para>Print short information about command syntax.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>integritytab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-integritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry project='die-net'><refentrytitle>integritysetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>
</refsect1>

</refentry>
8 changes: 4 additions & 4 deletions man/systemd-veritysetup-generator.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@

<refnamediv>
<refname>systemd-veritysetup-generator</refname>
<refpurpose>Unit generator for integrity protected block devices</refpurpose>
<refpurpose>Unit generator for verity protected block devices</refpurpose>
</refnamediv>

<refsynopsisdiv>
Expand All @@ -28,7 +28,7 @@
<title>Description</title>

<para><filename>systemd-veritysetup-generator</filename> is a generator that translates kernel command line options
configuring integrity-protected block devices (verity) into native systemd units early at boot and when
configuring verity protected block devices into native systemd units early at boot and when
configuration of the system manager is reloaded. This will create
<citerefentry><refentrytitle>systemd-veritysetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
units as necessary.</para>
Expand Down Expand Up @@ -66,7 +66,7 @@
data devices to use are automatically derived from the specified hash value. Specifically, the data partition
device is looked for under a GPT partition UUID derived from the first 128bit of the root hash, the hash
partition device is looked for under a GPT partition UUID derived from the last 128bit of the root hash. Hence
it is usually sufficient to specify the root hash to boot from an integrity protected root file system, as
it is usually sufficient to specify the root hash to boot from a verity protected root file system, as
device paths are automatically determined from it — as long as the partition table is properly set up.</para>
</listitem>
</varlistentry>
Expand All @@ -76,7 +76,7 @@
<term><varname>systemd.verity_root_hash=</varname></term>

<listitem><para>These two settings take block device paths as arguments and may be used to explicitly
configure the data partition and hash partition to use for setting up the integrity protection for the root file
configure the data partition and hash partition to use for setting up the verity protection for the root file
system. If not specified, these paths are automatically derived from the <varname>roothash=</varname> argument
(see above).</para></listitem>
</varlistentry>
Expand Down
8 changes: 4 additions & 4 deletions man/systemd-veritysetup@.service.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
<refnamediv>
<refname>systemd-veritysetup@.service</refname>
<refname>systemd-veritysetup</refname>
<refpurpose>Disk integrity protection logic</refpurpose>
<refpurpose>Disk verity protection logic</refpurpose>
</refnamediv>

<refsynopsisdiv>
Expand All @@ -29,12 +29,12 @@
<refsect1>
<title>Description</title>

<para><filename>systemd-veritysetup@.service</filename> is a service responsible for setting up integrity
protection (verity) block devices. It should be instantiated for each device that requires integrity
<para><filename>systemd-veritysetup@.service</filename> is a service responsible for setting up verity
protection block devices. It should be instantiated for each device that requires verity
protection.</para>

<para>At early boot and when the system manager configuration is reloaded kernel command line configuration for
integrity protected block devices is translated into <filename>systemd-veritysetup@.service</filename> units by
verity protected block devices is translated into <filename>systemd-veritysetup@.service</filename> units by
<citerefentry><refentrytitle>systemd-veritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>

<para><filename>systemd-veritysetup@.service</filename> calls <command>systemd-veritysetup</command>.</para>
Expand Down
Loading