Documentation/security/ipe.rst

1 .. SPDX-License-Identifier: GPL-2.0
3 Integrity Policy Enforcement (IPE) - Kernel Documentation
10    :doc:`IPE admin guide </admin-guide/LSM/ipe>`.
13 ---------------------
16 of a locked-down system. This system would be born-secure, and have
20 policy. A mandatory access control system would be present, and
27   2. DM-Verity
29 Both options were carefully considered, however the choice to use DM-Verity
41       enforce the integrity policy, or it should not.
44       policy would indicate what labels required integrity verification, which
46       modify filesystem offline, the attacker could wipe all the xattrs -
48       file should be subject to integrity policy.
50       With DM-Verity, as the xattrs are saved as part of the Merkel tree, if
51       offline mount occurs against the filesystem protected by dm-verity, the
54     * As userspace binaries are paged in Linux, dm-verity also offers the
59       dm-verity will check the data when the page fault occurs (and the disk
64     * dm-verity provides integrity verification on demand as blocks are
73     * The signature supports an x.509-based signing infrastructure.
75 The next step was to choose a *policy* to enforce the integrity mechanism.
76 The minimum requirements for the policy were:
78   1. The policy itself must be integrity verified (preventing trivial
80   2. The policy itself must be resistant to rollback attacks.
81   3. The policy enforcement must have a permissive-like mode.
82   4. The policy must be able to be updated, in its entirety, without
84   5. Policy updates must be atomic.
85   6. The policy must support *revocations* of previously authored
87   7. The policy must be auditable, at any point-of-time.
89 IMA, as the only integrity policy mechanism at the time, was
97      kernel, and therefore might impact users.
100      separation of measurement policy from local integrity policy
104 whose responsibility would be only the local integrity policy enforcement.
107 --------------
109 IPE, as its name implies, is fundamentally an integrity policy enforcement
114 level of security guarantees; and IPE allows sysadmins to express policy for
120 integrity is independent of the policy for enforcing that integrity claim.
128 -----------------
130 IPE was designed after evaluating existing integrity policy solutions
136   2. A single, non-customizable action was implicitly taken as a default.
137   3. Debugging the policy required manual steps to determine what rule was violated.
138   4. Authoring a policy required an in-depth knowledge of the larger system,
143 Policy  section in Design Rationale:
149 IPE's policy is plain-text. This introduces slightly larger policy files than
150 other LSMs, but solves two major problems that occurs with some integrity policy
154 the policy has to be some form of string representation (be it structured,
155 through XML, JSON, YAML, etcetera), to allow the policy author to understand
156 what is being written. In a hypothetical binary policy design, a serializer
157 is necessary to write the policy from the human readable form, to the binary
159 structure in the kernel.
162 back into the human-readable form with as much information preserved. This is because a
170 quickly resulting in the need to recover the policy or fund extensive infrastructure
171 to track what each policy contains.
174 policy avoids the binary format, there is only one required serializer: from the
175 human-readable form to the data structure in kernel, saving on code maintenance,
179 access based on the trust of the system's resources, it's policy must also be
184 the signer is aware of what they are signing. A binary policy can cause
186 plain-text policy, on the other hand, the signers see the actual policy
189 Boot Policy
192 IPE, if configured appropriately, is able to enforce a policy as soon as a
193 kernel is booted and usermode starts. That implies some level of storage
194 of the policy to apply the minute usermode starts. Generally, that storage
197   1. The policy file(s) live on disk and the kernel loads the policy prior
199   2. The policy file(s) are passed by the bootloader to the kernel, who
200      parses the policy.
201   3. There is a policy file that is compiled into the kernel that is
204 The first option has problems: the kernel reading files from userspace
205 is typically discouraged and very uncommon in the kernel.
208 across its entire ecosystem - every bootloader would have to support this
210 result in more drastic changes to the kernel startup than necessary.
212 The third option is the best but it's important to be aware that the policy
213 will take disk space against the kernel it's compiled in. It's important to
214 keep this policy generalized enough that userspace can load a new, more
215 complicated policy, but restrictive enough that it will not overauthorize
219 kernel starts with a minimal policy, that trusts the initramfs only. Inside
221 it deploys and activates a policy that trusts the new root filesystem.
222 This prevents overauthorization at any step, and keeps the kernel policy
228 Not every system, however starts with an initramfs, so the startup policy
229 compiled into the kernel will need some flexibility to express how trust
231 make the compiled-in policy a full IPE policy, it allows system builders
234 Updatable, Rebootless Policy
238 trusted applications, keys roll, etcetera). Updating a kernel to change the
240 always risk-free, and blocking a security update leaves systems vulnerable.
241 This means IPE requires a policy that can be completely updated (allowing
242 revocations of existing policy) from a source external to the kernel (allowing
243 policies to be updated without updating the kernel).
245 Additionally, since the kernel is stateless between invocations, and reading
246 policy files off the disk from kernel space is a bad idea(tm), then the
247 policy updates have to be done rebootlessly.
250 so this policy needs to have a way to be identified as trusted. This is
251 done via a signature chained to a trust source in the kernel. Arbitrarily,
253 populated at kernel compile-time, as this matches the expectation that the
254 author of the compiled-in policy described above is the same entity that can
255 deploy policy updates.
257 Anti-Rollback / Anti-Replay
261 trusted anymore. IPE's policy has no exception to this. There can be
262 instances where a mistaken policy author deploys an insecure policy,
263 before correcting it with a secure policy.
265 Assuming that as soon as the insecure policy is signed, and an attacker
266 acquires the insecure policy, IPE needs a way to prevent rollback
267 from the secure policy update to the insecure policy update.
269 Initially, IPE's policy can have a policy_version that states the
275   However, since the kernel is stateless across boots, this policy
279   opportunity is minimal for an attacker to deploy the insecure policy.
291   1. A policy in which failure to match any rules in the policy results
293   2. A policy in which failure to match any rules in the policy results
295   3. A policy in which the action taken when no rules are matched is
296      specified by the policy author.
298 The first option could make a policy like this::
305 This would result in a policy like this (assuming each line is
313 This is somewhat clear if you read the docs, understand the policy
333 and override the default with an empty rule, force the end-user
343 Policy Debugging:
346 When developing a policy, it is useful to know what line of the policy
349 policy systems do not provide this information, instead providing the
351 with the policy to evaluate what went wrong.
354 of the investigation to the exact policy line (in the case of a specific
356 and investigation times when policy failures are observed while evaluating
359 IPE's policy engine is also designed in a way that it makes it obvious to
360 a human of how to investigate a policy failure. Each line is evaluated in
364 the policy. In those systems, it requires multiple steps to debug, and the
365 algorithm may not always be clear to the end-user without reading the code first.
367 Simplified Policy:
370 Finally, IPE's policy is designed for sysadmins, not kernel developers. Instead
376 maintainers of IPE, being kernel developers can make the correct choice to determine
380 --------------------
389 evaluate to false, as they are all file-based and the operation is not
394   This also occurs with the ``kernel_load_data`` hook, when the kernel is
401 The per-policy securityfs tree is somewhat unique. For example, for
402 a standard securityfs policy tree::
405     |- active
406     |- delete
407     |- name
408     |- pkcs7
409     |- policy
410     |- update
411     |- version
413 The policy is stored in the ``->i_private`` data of the MyPolicy inode.
416 -----
418 IPE has KUnit Tests for the policy parser. Recommended kunitconfig::
445 `test suite <https://github.com/microsoft/ipe/tree/test-suite>`_ that