Documentation/security/ipe.rst

Source file repositories/reference/linux-study-clean/Documentation/security/ipe.rst

File Facts

System
Linux kernel
Corpus path
Documentation/security/ipe.rst
Extension
.rst
Size
19565 bytes
Lines
447
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

Integrity Policy Enforcement (IPE) - Kernel Documentation
=========================================================

.. NOTE::

   This is documentation targeted at developers, instead of administrators.
   If you're looking for documentation on the usage of IPE, please see
   :doc:`IPE admin guide </admin-guide/LSM/ipe>`.

Historical Motivation
---------------------

The original issue that prompted IPE's implementation was the creation
of a locked-down system. This system would be born-secure, and have
strong integrity guarantees over both the executable code, and specific
*data files* on the system, that were critical to its function. These
specific data files would not be readable unless they passed integrity
policy. A mandatory access control system would be present, and
as a result, xattrs would have to be protected. This led to a selection
of what would provide the integrity claims. At the time, there were two
main mechanisms considered that could guarantee integrity for the system
with these requirements:

  1. IMA + EVM Signatures
  2. DM-Verity

Both options were carefully considered, however the choice to use DM-Verity
over IMA+EVM as the *integrity mechanism* in the original use case of IPE
was due to three main reasons:

  1. Protection of additional attack vectors:

    * With IMA+EVM, without an encryption solution, the system is vulnerable
      to offline attack against the aforementioned specific data files.

      Unlike executables, read operations (like those on the protected data
      files), cannot be enforced to be globally integrity verified. This means
      there must be some form of selector to determine whether a read should
      enforce the integrity policy, or it should not.

      At the time, this was done with mandatory access control labels. An IMA
      policy would indicate what labels required integrity verification, which
      presented an issue: EVM would protect the label, but if an attacker could
      modify filesystem offline, the attacker could wipe all the xattrs -
      including the SELinux labels that would be used to determine whether the
      file should be subject to integrity policy.

      With DM-Verity, as the xattrs are saved as part of the Merkel tree, if
      offline mount occurs against the filesystem protected by dm-verity, the
      checksum no longer matches and the file fails to be read.

    * As userspace binaries are paged in Linux, dm-verity also offers the
      additional protection against a hostile block device. In such an attack,
      the block device reports the appropriate content for the IMA hash
      initially, passing the required integrity check. Then, on the page fault
      that accesses the real data, will report the attacker's payload. Since
      dm-verity will check the data when the page fault occurs (and the disk
      access), this attack is mitigated.

  2. Performance:

    * dm-verity provides integrity verification on demand as blocks are
      read versus requiring the entire file being read into memory for
      validation.

  3. Simplicity of signing:

    * No need for two signatures (IMA, then EVM): one signature covers

Annotation

Implementation Notes