1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 Integrity Policy Enforcement (IPE) 3 Integrity Policy Enforcement (IPE)
4 ================================== 4 ==================================
5 5
6 .. NOTE:: 6 .. NOTE::
7 7
8 This is the documentation for admins, syste 8 This is the documentation for admins, system builders, or individuals
9 attempting to use IPE. If you're looking fo 9 attempting to use IPE. If you're looking for more developer-focused
10 documentation about IPE please see :doc:`th 10 documentation about IPE please see :doc:`the design docs </security/ipe>`.
11 11
12 Overview 12 Overview
13 -------- 13 --------
14 14
15 Integrity Policy Enforcement (IPE) is a Linux 15 Integrity Policy Enforcement (IPE) is a Linux Security Module that takes a
16 complementary approach to access control. Unli 16 complementary approach to access control. Unlike traditional access control
17 mechanisms that rely on labels and paths for d 17 mechanisms that rely on labels and paths for decision-making, IPE focuses
18 on the immutable security properties inherent 18 on the immutable security properties inherent to system components. These
19 properties are fundamental attributes or featu 19 properties are fundamental attributes or features of a system component
20 that cannot be altered, ensuring a consistent 20 that cannot be altered, ensuring a consistent and reliable basis for
21 security decisions. 21 security decisions.
22 22
23 To elaborate, in the context of IPE, system co 23 To elaborate, in the context of IPE, system components primarily refer to
24 files or the devices these files reside on. Ho 24 files or the devices these files reside on. However, this is just a
25 starting point. The concept of system componen 25 starting point. The concept of system components is flexible and can be
26 extended to include new elements as the system 26 extended to include new elements as the system evolves. The immutable
27 properties include the origin of a file, which 27 properties include the origin of a file, which remains constant and
28 unchangeable over time. For example, IPE polic 28 unchangeable over time. For example, IPE policies can be crafted to trust
29 files originating from the initramfs. Since in 29 files originating from the initramfs. Since initramfs is typically verified
30 by the bootloader, its files are deemed trustw 30 by the bootloader, its files are deemed trustworthy; "file is from
31 initramfs" becomes an immutable property under 31 initramfs" becomes an immutable property under IPE's consideration.
32 32
33 The immutable property concept extends to the 33 The immutable property concept extends to the security features enabled on
34 a file's origin, such as dm-verity or fs-verit 34 a file's origin, such as dm-verity or fs-verity, which provide a layer of
35 integrity and trust. For example, IPE allows t 35 integrity and trust. For example, IPE allows the definition of policies
36 that trust files from a dm-verity protected de 36 that trust files from a dm-verity protected device. dm-verity ensures the
37 integrity of an entire device by providing a v 37 integrity of an entire device by providing a verifiable and immutable state
38 of its contents. Similarly, fs-verity offers f 38 of its contents. Similarly, fs-verity offers filesystem-level integrity
39 checks, allowing IPE to enforce policies that 39 checks, allowing IPE to enforce policies that trust files protected by
40 fs-verity. These two features cannot be turned 40 fs-verity. These two features cannot be turned off once established, so
41 they are considered immutable properties. Thes 41 they are considered immutable properties. These examples demonstrate how
42 IPE leverages immutable properties, such as a 42 IPE leverages immutable properties, such as a file's origin and its
43 integrity protection mechanisms, to make acces 43 integrity protection mechanisms, to make access control decisions.
44 44
45 For the IPE policy, specifically, it grants th 45 For the IPE policy, specifically, it grants the ability to enforce
46 stringent access controls by assessing securit 46 stringent access controls by assessing security properties against
47 reference values defined within the policy. Th 47 reference values defined within the policy. This assessment can be based on
48 the existence of a security property (e.g., ve 48 the existence of a security property (e.g., verifying if a file originates
49 from initramfs) or evaluating the internal sta 49 from initramfs) or evaluating the internal state of an immutable security
50 property. The latter includes checking the roo 50 property. The latter includes checking the roothash of a dm-verity
51 protected device, determining whether dm-verit 51 protected device, determining whether dm-verity possesses a valid
52 signature, assessing the digest of a fs-verity 52 signature, assessing the digest of a fs-verity protected file, or
53 determining whether fs-verity possesses a vali 53 determining whether fs-verity possesses a valid built-in signature. This
54 nuanced approach to policy enforcement enables 54 nuanced approach to policy enforcement enables a highly secure and
55 customizable system defense mechanism, tailore 55 customizable system defense mechanism, tailored to specific security
56 requirements and trust models. 56 requirements and trust models.
57 57
58 To enable IPE, ensure that ``CONFIG_SECURITY_I 58 To enable IPE, ensure that ``CONFIG_SECURITY_IPE`` (under
59 :menuselection:`Security -> Integrity Policy E 59 :menuselection:`Security -> Integrity Policy Enforcement (IPE)`) config
60 option is enabled. 60 option is enabled.
61 61
62 Use Cases 62 Use Cases
63 --------- 63 ---------
64 64
65 IPE works best in fixed-function devices: devi 65 IPE works best in fixed-function devices: devices in which their purpose
66 is clearly defined and not supposed to be chan 66 is clearly defined and not supposed to be changed (e.g. network firewall
67 device in a data center, an IoT device, etcete 67 device in a data center, an IoT device, etcetera), where all software and
68 configuration is built and provisioned by the 68 configuration is built and provisioned by the system owner.
69 69
70 IPE is a long-way off for use in general-purpo 70 IPE is a long-way off for use in general-purpose computing: the Linux
71 community as a whole tends to follow a decentr 71 community as a whole tends to follow a decentralized trust model (known as
72 the web of trust), which IPE has no support fo 72 the web of trust), which IPE has no support for it yet. Instead, IPE
73 supports PKI (public key infrastructure), whic 73 supports PKI (public key infrastructure), which generally designates a
74 set of trusted entities that provide a measure 74 set of trusted entities that provide a measure of absolute trust.
75 75
76 Additionally, while most packages are signed t 76 Additionally, while most packages are signed today, the files inside
77 the packages (for instance, the executables), 77 the packages (for instance, the executables), tend to be unsigned. This
78 makes it difficult to utilize IPE in systems w 78 makes it difficult to utilize IPE in systems where a package manager is
79 expected to be functional, without major chang 79 expected to be functional, without major changes to the package manager
80 and ecosystem behind it. 80 and ecosystem behind it.
81 81
82 The digest_cache LSM [#digest_cache_lsm]_ is a 82 The digest_cache LSM [#digest_cache_lsm]_ is a system that when combined with IPE,
83 could be used to enable and support general-pu 83 could be used to enable and support general-purpose computing use cases.
84 84
85 Known Limitations 85 Known Limitations
86 ----------------- 86 -----------------
87 87
88 IPE cannot verify the integrity of anonymous e 88 IPE cannot verify the integrity of anonymous executable memory, such as
89 the trampolines created by gcc closures and li 89 the trampolines created by gcc closures and libffi (<3.4.2), or JIT'd code.
90 Unfortunately, as this is dynamically generate 90 Unfortunately, as this is dynamically generated code, there is no way
91 for IPE to ensure the integrity of this code t 91 for IPE to ensure the integrity of this code to form a trust basis.
92 92
93 IPE cannot verify the integrity of programs wr 93 IPE cannot verify the integrity of programs written in interpreted
94 languages when these scripts are invoked by pa 94 languages when these scripts are invoked by passing these program files
95 to the interpreter. This is because the way in 95 to the interpreter. This is because the way interpreters execute these
96 files; the scripts themselves are not evaluate 96 files; the scripts themselves are not evaluated as executable code
97 through one of IPE's hooks, but they are merel 97 through one of IPE's hooks, but they are merely text files that are read
98 (as opposed to compiled executables) [#interpr 98 (as opposed to compiled executables) [#interpreters]_.
99 99
100 Threat Model 100 Threat Model
101 ------------ 101 ------------
102 102
103 IPE specifically targets the risk of tampering 103 IPE specifically targets the risk of tampering with user-space executable
104 code after the kernel has initially booted, in 104 code after the kernel has initially booted, including the kernel modules
105 loaded from userspace via ``modprobe`` or ``in 105 loaded from userspace via ``modprobe`` or ``insmod``.
106 106
107 To illustrate, consider a scenario where an un 107 To illustrate, consider a scenario where an untrusted binary, possibly
108 malicious, is downloaded along with all necess 108 malicious, is downloaded along with all necessary dependencies, including a
109 loader and libc. The primary function of IPE i 109 loader and libc. The primary function of IPE in this context is to prevent
110 the execution of such binaries and their depen 110 the execution of such binaries and their dependencies.
111 111
112 IPE achieves this by verifying the integrity a 112 IPE achieves this by verifying the integrity and authenticity of all
113 executable code before allowing them to run. I 113 executable code before allowing them to run. It conducts a thorough
114 check to ensure that the code's integrity is i 114 check to ensure that the code's integrity is intact and that they match an
115 authorized reference value (digest, signature, 115 authorized reference value (digest, signature, etc) as per the defined
116 policy. If a binary does not pass this verific 116 policy. If a binary does not pass this verification process, either
117 because its integrity has been compromised or 117 because its integrity has been compromised or it does not meet the
118 authorization criteria, IPE will deny its exec 118 authorization criteria, IPE will deny its execution. Additionally, IPE
119 generates audit logs which may be utilized to 119 generates audit logs which may be utilized to detect and analyze failures
120 resulting from policy violation. 120 resulting from policy violation.
121 121
122 Tampering threat scenarios include modificatio 122 Tampering threat scenarios include modification or replacement of
123 executable code by a range of actors including 123 executable code by a range of actors including:
124 124
125 - Actors with physical access to the hardware 125 - Actors with physical access to the hardware
126 - Actors with local network access to the sys 126 - Actors with local network access to the system
127 - Actors with access to the deployment system 127 - Actors with access to the deployment system
128 - Compromised internal systems under external 128 - Compromised internal systems under external control
129 - Malicious end users of the system 129 - Malicious end users of the system
130 - Compromised end users of the system 130 - Compromised end users of the system
131 - Remote (external) compromise of the system 131 - Remote (external) compromise of the system
132 132
133 IPE does not mitigate threats arising from mal 133 IPE does not mitigate threats arising from malicious but authorized
134 developers (with access to a signing certifica 134 developers (with access to a signing certificate), or compromised
135 developer tools used by them (i.e. return-orie 135 developer tools used by them (i.e. return-oriented programming attacks).
136 Additionally, IPE draws hard security boundary 136 Additionally, IPE draws hard security boundary between userspace and
137 kernelspace. As a result, kernel-level exploit 137 kernelspace. As a result, kernel-level exploits are considered outside
138 the scope of IPE and mitigation is left to oth 138 the scope of IPE and mitigation is left to other mechanisms.
139 139
140 Policy 140 Policy
141 ------ 141 ------
142 142
143 IPE policy is a plain-text [#devdoc]_ policy c 143 IPE policy is a plain-text [#devdoc]_ policy composed of multiple statements
144 over several lines. There is one required line 144 over several lines. There is one required line, at the top of the
145 policy, indicating the policy name, and the po 145 policy, indicating the policy name, and the policy version, for
146 instance:: 146 instance::
147 147
148 policy_name=Ex_Policy policy_version=0.0.0 148 policy_name=Ex_Policy policy_version=0.0.0
149 149
150 The policy name is a unique key identifying th 150 The policy name is a unique key identifying this policy in a human
151 readable name. This is used to create nodes un 151 readable name. This is used to create nodes under securityfs as well as
152 uniquely identify policies to deploy new polic 152 uniquely identify policies to deploy new policies vs update existing
153 policies. 153 policies.
154 154
155 The policy version indicates the current versi 155 The policy version indicates the current version of the policy (NOT the
156 policy syntax version). This is used to preven 156 policy syntax version). This is used to prevent rollback of policy to
157 potentially insecure previous versions of the 157 potentially insecure previous versions of the policy.
158 158
159 The next portion of IPE policy are rules. Rule 159 The next portion of IPE policy are rules. Rules are formed by key=value
160 pairs, known as properties. IPE rules require 160 pairs, known as properties. IPE rules require two properties: ``action``,
161 which determines what IPE does when it encount 161 which determines what IPE does when it encounters a match against the
162 rule, and ``op``, which determines when the ru 162 rule, and ``op``, which determines when the rule should be evaluated.
163 The ordering is significant, a rule must start 163 The ordering is significant, a rule must start with ``op``, and end with
164 ``action``. Thus, a minimal rule is:: 164 ``action``. Thus, a minimal rule is::
165 165
166 op=EXECUTE action=ALLOW 166 op=EXECUTE action=ALLOW
167 167
168 This example will allow any execution. Additio 168 This example will allow any execution. Additional properties are used to
169 assess immutable security properties about the 169 assess immutable security properties about the files being evaluated.
170 These properties are intended to be descriptio 170 These properties are intended to be descriptions of systems within the
171 kernel that can provide a measure of integrity 171 kernel that can provide a measure of integrity verification, such that IPE
172 can determine the trust of the resource based 172 can determine the trust of the resource based on the value of the property.
173 173
174 Rules are evaluated top-to-bottom. As a result 174 Rules are evaluated top-to-bottom. As a result, any revocation rules,
175 or denies should be placed early in the file t 175 or denies should be placed early in the file to ensure that these rules
176 are evaluated before a rule with ``action=ALLO 176 are evaluated before a rule with ``action=ALLOW``.
177 177
178 IPE policy supports comments. The character '# 178 IPE policy supports comments. The character '#' will function as a
179 comment, ignoring all characters to the right 179 comment, ignoring all characters to the right of '#' until the newline.
180 180
181 The default behavior of IPE evaluations can al 181 The default behavior of IPE evaluations can also be expressed in policy,
182 through the ``DEFAULT`` statement. This can be 182 through the ``DEFAULT`` statement. This can be done at a global level,
183 or a per-operation level:: 183 or a per-operation level::
184 184
185 # Global 185 # Global
186 DEFAULT action=ALLOW 186 DEFAULT action=ALLOW
187 187
188 # Operation Specific 188 # Operation Specific
189 DEFAULT op=EXECUTE action=ALLOW 189 DEFAULT op=EXECUTE action=ALLOW
190 190
191 A default must be set for all known operations 191 A default must be set for all known operations in IPE. If you want to
192 preserve older policies being compatible with 192 preserve older policies being compatible with newer kernels that can introduce
193 new operations, set a global default of ``ALLO 193 new operations, set a global default of ``ALLOW``, then override the
194 defaults on a per-operation basis (as above). 194 defaults on a per-operation basis (as above).
195 195
196 With configurable policy-based LSMs, there's s 196 With configurable policy-based LSMs, there's several issues with
197 enforcing the configurable policies at startup 197 enforcing the configurable policies at startup, around reading and
198 parsing the policy: 198 parsing the policy:
199 199
200 1. The kernel *should* not read files from use 200 1. The kernel *should* not read files from userspace, so directly reading
201 the policy file is prohibited. 201 the policy file is prohibited.
202 2. The kernel command line has a character lim 202 2. The kernel command line has a character limit, and one kernel module
203 should not reserve the entire character lim 203 should not reserve the entire character limit for its own
204 configuration. 204 configuration.
205 3. There are various boot loaders in the kerne 205 3. There are various boot loaders in the kernel ecosystem, so handing
206 off a memory block would be costly to maint 206 off a memory block would be costly to maintain.
207 207
208 As a result, IPE has addressed this problem th 208 As a result, IPE has addressed this problem through a concept of a "boot
209 policy". A boot policy is a minimal policy whi 209 policy". A boot policy is a minimal policy which is compiled into the
210 kernel. This policy is intended to get the sys 210 kernel. This policy is intended to get the system to a state where
211 userspace is set up and ready to receive comma 211 userspace is set up and ready to receive commands, at which point a more
212 complex policy can be deployed via securityfs. 212 complex policy can be deployed via securityfs. The boot policy can be
213 specified via ``SECURITY_IPE_BOOT_POLICY`` con 213 specified via ``SECURITY_IPE_BOOT_POLICY`` config option, which accepts
214 a path to a plain-text version of the IPE poli 214 a path to a plain-text version of the IPE policy to apply. This policy
215 will be compiled into the kernel. If not speci 215 will be compiled into the kernel. If not specified, IPE will be disabled
216 until a policy is deployed and activated throu 216 until a policy is deployed and activated through securityfs.
217 217
218 Deploying Policies 218 Deploying Policies
219 ~~~~~~~~~~~~~~~~~~ 219 ~~~~~~~~~~~~~~~~~~
220 220
221 Policies can be deployed from userspace throug 221 Policies can be deployed from userspace through securityfs. These policies
222 are signed through the PKCS#7 message format t 222 are signed through the PKCS#7 message format to enforce some level of
223 authorization of the policies (prohibiting an 223 authorization of the policies (prohibiting an attacker from gaining
224 unconstrained root, and deploying an "allow al 224 unconstrained root, and deploying an "allow all" policy). These
225 policies must be signed by a certificate that 225 policies must be signed by a certificate that chains to the
226 ``SYSTEM_TRUSTED_KEYRING``, or to the secondar 226 ``SYSTEM_TRUSTED_KEYRING``, or to the secondary and/or platform keyrings if
227 ``CONFIG_IPE_POLICY_SIG_SECONDARY_KEYRING`` an 227 ``CONFIG_IPE_POLICY_SIG_SECONDARY_KEYRING`` and/or
228 ``CONFIG_IPE_POLICY_SIG_PLATFORM_KEYRING`` are 228 ``CONFIG_IPE_POLICY_SIG_PLATFORM_KEYRING`` are enabled, respectively.
229 With openssl, the policy can be signed by:: 229 With openssl, the policy can be signed by::
230 230
231 openssl smime -sign \ 231 openssl smime -sign \
232 -in "$MY_POLICY" \ 232 -in "$MY_POLICY" \
233 -signer "$MY_CERTIFICATE" \ 233 -signer "$MY_CERTIFICATE" \
234 -inkey "$MY_PRIVATE_KEY" \ 234 -inkey "$MY_PRIVATE_KEY" \
235 -noattr \ 235 -noattr \
236 -nodetach \ 236 -nodetach \
237 -nosmimecap \ 237 -nosmimecap \
238 -outform der \ 238 -outform der \
239 -out "$MY_POLICY.p7b" 239 -out "$MY_POLICY.p7b"
240 240
241 Deploying the policies is done through securit 241 Deploying the policies is done through securityfs, through the
242 ``new_policy`` node. To deploy a policy, simpl 242 ``new_policy`` node. To deploy a policy, simply cat the file into the
243 securityfs node:: 243 securityfs node::
244 244
245 cat "$MY_POLICY.p7b" > /sys/kernel/security 245 cat "$MY_POLICY.p7b" > /sys/kernel/security/ipe/new_policy
246 246
247 Upon success, this will create one subdirector 247 Upon success, this will create one subdirectory under
248 ``/sys/kernel/security/ipe/policies/``. The su 248 ``/sys/kernel/security/ipe/policies/``. The subdirectory will be the
249 ``policy_name`` field of the policy deployed, 249 ``policy_name`` field of the policy deployed, so for the example above,
250 the directory will be ``/sys/kernel/security/i 250 the directory will be ``/sys/kernel/security/ipe/policies/Ex_Policy``.
251 Within this directory, there will be seven fil 251 Within this directory, there will be seven files: ``pkcs7``, ``policy``,
252 ``name``, ``version``, ``active``, ``update``, 252 ``name``, ``version``, ``active``, ``update``, and ``delete``.
253 253
254 The ``pkcs7`` file is read-only. Reading it re 254 The ``pkcs7`` file is read-only. Reading it returns the raw PKCS#7 data
255 that was provided to the kernel, representing 255 that was provided to the kernel, representing the policy. If the policy being
256 read is the boot policy, this will return ``EN 256 read is the boot policy, this will return ``ENOENT``, as it is not signed.
257 257
258 The ``policy`` file is read only. Reading it r 258 The ``policy`` file is read only. Reading it returns the PKCS#7 inner
259 content of the policy, which will be the plain 259 content of the policy, which will be the plain text policy.
260 260
261 The ``active`` file is used to set a policy as 261 The ``active`` file is used to set a policy as the currently active policy.
262 This file is rw, and accepts a value of ``"1"` 262 This file is rw, and accepts a value of ``"1"`` to set the policy as active.
263 Since only a single policy can be active at on 263 Since only a single policy can be active at one time, all other policies
264 will be marked inactive. The policy being mark 264 will be marked inactive. The policy being marked active must have a policy
265 version greater or equal to the currently-runn 265 version greater or equal to the currently-running version.
266 266
267 The ``update`` file is used to update a policy 267 The ``update`` file is used to update a policy that is already present
268 in the kernel. This file is write-only and acc 268 in the kernel. This file is write-only and accepts a PKCS#7 signed
269 policy. Two checks will always be performed on 269 policy. Two checks will always be performed on this policy: First, the
270 ``policy_names`` must match with the updated v 270 ``policy_names`` must match with the updated version and the existing
271 version. Second the updated policy must have a 271 version. Second the updated policy must have a policy version greater than
272 the currently-running version. This is to prev 272 the currently-running version. This is to prevent rollback attacks.
273 273
274 The ``delete`` file is used to remove a policy 274 The ``delete`` file is used to remove a policy that is no longer needed.
275 This file is write-only and accepts a value of 275 This file is write-only and accepts a value of ``1`` to delete the policy.
276 On deletion, the securityfs node representing 276 On deletion, the securityfs node representing the policy will be removed.
277 However, delete the current active policy is n 277 However, delete the current active policy is not allowed and will return
278 an operation not permitted error. 278 an operation not permitted error.
279 279
280 Similarly, writing to both ``update`` and ``ne 280 Similarly, writing to both ``update`` and ``new_policy`` could result in
281 bad message(policy syntax error) or file exist 281 bad message(policy syntax error) or file exists error. The latter error happens
282 when trying to deploy a policy with a ``policy 282 when trying to deploy a policy with a ``policy_name`` while the kernel already
283 has a deployed policy with the same ``policy_n 283 has a deployed policy with the same ``policy_name``.
284 284
285 Deploying a policy will *not* cause IPE to sta 285 Deploying a policy will *not* cause IPE to start enforcing the policy. IPE will
286 only enforce the policy marked active. Note th 286 only enforce the policy marked active. Note that only one policy can be active
287 at a time. 287 at a time.
288 288
289 Once deployment is successful, the policy can 289 Once deployment is successful, the policy can be activated, by writing file
290 ``/sys/kernel/security/ipe/policies/$policy_na 290 ``/sys/kernel/security/ipe/policies/$policy_name/active``.
291 For example, the ``Ex_Policy`` can be activate 291 For example, the ``Ex_Policy`` can be activated by::
292 292
293 echo 1 > "/sys/kernel/security/ipe/policies 293 echo 1 > "/sys/kernel/security/ipe/policies/Ex_Policy/active"
294 294
295 From above point on, ``Ex_Policy`` is now the 295 From above point on, ``Ex_Policy`` is now the enforced policy on the
296 system. 296 system.
297 297
298 IPE also provides a way to delete policies. Th 298 IPE also provides a way to delete policies. This can be done via the
299 ``delete`` securityfs node, 299 ``delete`` securityfs node,
300 ``/sys/kernel/security/ipe/policies/$policy_na 300 ``/sys/kernel/security/ipe/policies/$policy_name/delete``.
301 Writing ``1`` to that file deletes the policy: 301 Writing ``1`` to that file deletes the policy::
302 302
303 echo 1 > "/sys/kernel/security/ipe/policies 303 echo 1 > "/sys/kernel/security/ipe/policies/$policy_name/delete"
304 304
305 There is only one requirement to delete a poli 305 There is only one requirement to delete a policy: the policy being deleted
306 must be inactive. 306 must be inactive.
307 307
308 .. NOTE:: 308 .. NOTE::
309 309
310 If a traditional MAC system is enabled (SEL 310 If a traditional MAC system is enabled (SELinux, apparmor, smack), all
311 writes to ipe's securityfs nodes require `` 311 writes to ipe's securityfs nodes require ``CAP_MAC_ADMIN``.
312 312
313 Modes 313 Modes
314 ~~~~~ 314 ~~~~~
315 315
316 IPE supports two modes of operation: permissiv 316 IPE supports two modes of operation: permissive (similar to SELinux's
317 permissive mode) and enforced. In permissive m 317 permissive mode) and enforced. In permissive mode, all events are
318 checked and policy violations are logged, but 318 checked and policy violations are logged, but the policy is not really
319 enforced. This allows users to test policies b 319 enforced. This allows users to test policies before enforcing them.
320 320
321 The default mode is enforce, and can be change 321 The default mode is enforce, and can be changed via the kernel command
322 line parameter ``ipe.enforce=(0|1)``, or the s 322 line parameter ``ipe.enforce=(0|1)``, or the securityfs node
323 ``/sys/kernel/security/ipe/enforce``. 323 ``/sys/kernel/security/ipe/enforce``.
324 324
325 .. NOTE:: 325 .. NOTE::
326 326
327 If a traditional MAC system is enabled (SEL 327 If a traditional MAC system is enabled (SELinux, apparmor, smack, etcetera),
328 all writes to ipe's securityfs nodes requir 328 all writes to ipe's securityfs nodes require ``CAP_MAC_ADMIN``.
329 329
330 Audit Events 330 Audit Events
331 ~~~~~~~~~~~~ 331 ~~~~~~~~~~~~
332 332
333 1420 AUDIT_IPE_ACCESS 333 1420 AUDIT_IPE_ACCESS
334 ^^^^^^^^^^^^^^^^^^^^^ 334 ^^^^^^^^^^^^^^^^^^^^^
335 Event Examples:: 335 Event Examples::
336 336
337 type=1420 audit(1653364370.067:61): ipe_op= 337 type=1420 audit(1653364370.067:61): ipe_op=EXECUTE ipe_hook=MMAP enforcing=1 pid=2241 comm="ld-linux.so" path="/deny/lib/libc.so.6" dev="sda2" ino=14549020 rule="DEFAULT action=DENY"
338 type=1300 audit(1653364370.067:61): SYSCALL 338 type=1300 audit(1653364370.067:61): SYSCALL arch=c000003e syscall=9 success=no exit=-13 a0=7f1105a28000 a1=195000 a2=5 a3=812 items=0 ppid=2219 pid=2241 auid=0 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=pts0 ses=2 comm="ld-linux.so" exe="/tmp/ipe-test/lib/ld-linux.so" subj=unconfined key=(null)
339 type=1327 audit(1653364370.067:61): 7079746 339 type=1327 audit(1653364370.067:61): 707974686F6E3300746573742F6D61696E2E7079002D6E00
340 340
341 type=1420 audit(1653364735.161:64): ipe_op= 341 type=1420 audit(1653364735.161:64): ipe_op=EXECUTE ipe_hook=MMAP enforcing=1 pid=2472 comm="mmap_test" path=? dev=? ino=? rule="DEFAULT action=DENY"
342 type=1300 audit(1653364735.161:64): SYSCALL 342 type=1300 audit(1653364735.161:64): SYSCALL arch=c000003e syscall=9 success=no exit=-13 a0=0 a1=1000 a2=4 a3=21 items=0 ppid=2219 pid=2472 auid=0 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=pts0 ses=2 comm="mmap_test" exe="/root/overlake_test/upstream_test/vol_fsverity/bin/mmap_test" subj=unconfined key=(null)
343 type=1327 audit(1653364735.161:64): 7079746 343 type=1327 audit(1653364735.161:64): 707974686F6E3300746573742F6D61696E2E7079002D6E00
344 344
345 This event indicates that IPE made an access c 345 This event indicates that IPE made an access control decision; the IPE
346 specific record (1420) is always emitted in co 346 specific record (1420) is always emitted in conjunction with a
347 ``AUDITSYSCALL`` record. 347 ``AUDITSYSCALL`` record.
348 348
349 Determining whether IPE is in permissive or en 349 Determining whether IPE is in permissive or enforced mode can be derived
350 from ``success`` property and exit code of the 350 from ``success`` property and exit code of the ``AUDITSYSCALL`` record.
351 351
352 352
353 Field descriptions: 353 Field descriptions:
354 354
355 +-----------+------------+-----------+-------- 355 +-----------+------------+-----------+---------------------------------------------------------------------------------+
356 | Field | Value Type | Optional? | Descrip 356 | Field | Value Type | Optional? | Description of Value |
357 +===========+============+===========+======== 357 +===========+============+===========+=================================================================================+
358 | ipe_op | string | No | The IPE 358 | ipe_op | string | No | The IPE operation name associated with the log |
359 +-----------+------------+-----------+-------- 359 +-----------+------------+-----------+---------------------------------------------------------------------------------+
360 | ipe_hook | string | No | The nam 360 | ipe_hook | string | No | The name of the LSM hook that triggered the IPE event |
361 +-----------+------------+-----------+-------- 361 +-----------+------------+-----------+---------------------------------------------------------------------------------+
362 | enforcing | integer | No | The cur 362 | enforcing | integer | No | The current IPE enforcing state 1 is in enforcing mode, 0 is in permissive mode |
363 +-----------+------------+-----------+-------- 363 +-----------+------------+-----------+---------------------------------------------------------------------------------+
364 | pid | integer | No | The pid 364 | pid | integer | No | The pid of the process that triggered the IPE event. |
365 +-----------+------------+-----------+-------- 365 +-----------+------------+-----------+---------------------------------------------------------------------------------+
366 | comm | string | No | The com 366 | comm | string | No | The command line program name of the process that triggered the IPE event |
367 +-----------+------------+-----------+-------- 367 +-----------+------------+-----------+---------------------------------------------------------------------------------+
368 | path | string | Yes | The abs 368 | path | string | Yes | The absolute path to the evaluated file |
369 +-----------+------------+-----------+-------- 369 +-----------+------------+-----------+---------------------------------------------------------------------------------+
370 | ino | integer | Yes | The ino 370 | ino | integer | Yes | The inode number of the evaluated file |
371 +-----------+------------+-----------+-------- 371 +-----------+------------+-----------+---------------------------------------------------------------------------------+
372 | dev | string | Yes | The dev 372 | dev | string | Yes | The device name of the evaluated file, e.g. vda |
373 +-----------+------------+-----------+-------- 373 +-----------+------------+-----------+---------------------------------------------------------------------------------+
374 | rule | string | No | The mat 374 | rule | string | No | The matched policy rule |
375 +-----------+------------+-----------+-------- 375 +-----------+------------+-----------+---------------------------------------------------------------------------------+
376 376
377 1421 AUDIT_IPE_CONFIG_CHANGE 377 1421 AUDIT_IPE_CONFIG_CHANGE
378 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 378 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
379 379
380 Event Example:: 380 Event Example::
381 381
382 type=1421 audit(1653425583.136:54): old_act 382 type=1421 audit(1653425583.136:54): old_active_pol_name="Allow_All" old_active_pol_version=0.0.0 old_policy_digest=sha256:E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855 new_active_pol_name="boot_verified" new_active_pol_version=0.0.0 new_policy_digest=sha256:820EEA5B40CA42B51F68962354BA083122A20BB846F26765076DD8EED7B8F4DB auid=4294967295 ses=4294967295 lsm=ipe res=1
383 type=1300 audit(1653425583.136:54): SYSCALL 383 type=1300 audit(1653425583.136:54): SYSCALL arch=c000003e syscall=1 success=yes exit=2 a0=3 a1=5596fcae1fb0 a2=2 a3=2 items=0 ppid=184 pid=229 auid=4294967295 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=pts0 ses=4294967295 comm="python3" exe="/usr/bin/python3.10" key=(null)
384 type=1327 audit(1653425583.136:54): PROCTIT 384 type=1327 audit(1653425583.136:54): PROCTITLE proctitle=707974686F6E3300746573742F6D61696E2E7079002D66002E2
385 385
386 This event indicates that IPE switched the act 386 This event indicates that IPE switched the active poliy from one to another
387 along with the version and the hash digest of 387 along with the version and the hash digest of the two policies.
388 Note IPE can only have one policy active at a 388 Note IPE can only have one policy active at a time, all access decision
389 evaluation is based on the current active poli 389 evaluation is based on the current active policy.
390 The normal procedure to deploy a new policy is 390 The normal procedure to deploy a new policy is loading the policy to deploy
391 into the kernel first, then switch the active 391 into the kernel first, then switch the active policy to it.
392 392
393 This record will always be emitted in conjunct 393 This record will always be emitted in conjunction with a ``AUDITSYSCALL`` record for the ``write`` syscall.
394 394
395 Field descriptions: 395 Field descriptions:
396 396
397 +------------------------+------------+------- 397 +------------------------+------------+-----------+---------------------------------------------------+
398 | Field | Value Type | Option 398 | Field | Value Type | Optional? | Description of Value |
399 +========================+============+======= 399 +========================+============+===========+===================================================+
400 | old_active_pol_name | string | Yes 400 | old_active_pol_name | string | Yes | The name of previous active policy |
401 +------------------------+------------+------- 401 +------------------------+------------+-----------+---------------------------------------------------+
402 | old_active_pol_version | string | Yes 402 | old_active_pol_version | string | Yes | The version of previous active policy |
403 +------------------------+------------+------- 403 +------------------------+------------+-----------+---------------------------------------------------+
404 | old_policy_digest | string | Yes 404 | old_policy_digest | string | Yes | The hash of previous active policy |
405 +------------------------+------------+------- 405 +------------------------+------------+-----------+---------------------------------------------------+
406 | new_active_pol_name | string | No 406 | new_active_pol_name | string | No | The name of current active policy |
407 +------------------------+------------+------- 407 +------------------------+------------+-----------+---------------------------------------------------+
408 | new_active_pol_version | string | No 408 | new_active_pol_version | string | No | The version of current active policy |
409 +------------------------+------------+------- 409 +------------------------+------------+-----------+---------------------------------------------------+
410 | new_policy_digest | string | No 410 | new_policy_digest | string | No | The hash of current active policy |
411 +------------------------+------------+------- 411 +------------------------+------------+-----------+---------------------------------------------------+
412 | auid | integer | No 412 | auid | integer | No | The login user ID |
413 +------------------------+------------+------- 413 +------------------------+------------+-----------+---------------------------------------------------+
414 | ses | integer | No 414 | ses | integer | No | The login session ID |
415 +------------------------+------------+------- 415 +------------------------+------------+-----------+---------------------------------------------------+
416 | lsm | string | No 416 | lsm | string | No | The lsm name associated with the event |
417 +------------------------+------------+------- 417 +------------------------+------------+-----------+---------------------------------------------------+
418 | res | integer | No 418 | res | integer | No | The result of the audited operation(success/fail) |
419 +------------------------+------------+------- 419 +------------------------+------------+-----------+---------------------------------------------------+
420 420
421 1422 AUDIT_IPE_POLICY_LOAD 421 1422 AUDIT_IPE_POLICY_LOAD
422 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 422 ^^^^^^^^^^^^^^^^^^^^^^^^^^
423 423
424 Event Example:: 424 Event Example::
425 425
426 type=1422 audit(1653425529.927:53): policy_ 426 type=1422 audit(1653425529.927:53): policy_name="boot_verified" policy_version=0.0.0 policy_digest=sha256:820EEA5B40CA42B51F68962354BA083122A20BB846F26765076DD8EED7B8F4DB auid=4294967295 ses=4294967295 lsm=ipe res=1
427 type=1300 audit(1653425529.927:53): arch=c0 427 type=1300 audit(1653425529.927:53): arch=c000003e syscall=1 success=yes exit=2567 a0=3 a1=5596fcae1fb0 a2=a07 a3=2 items=0 ppid=184 pid=229 auid=4294967295 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=pts0 ses=4294967295 comm="python3" exe="/usr/bin/python3.10" key=(null)
428 type=1327 audit(1653425529.927:53): PROCTIT 428 type=1327 audit(1653425529.927:53): PROCTITLE proctitle=707974686F6E3300746573742F6D61696E2E7079002D66002E2E
429 429
430 This record indicates a new policy has been lo 430 This record indicates a new policy has been loaded into the kernel with the policy name, policy version and policy hash.
431 431
432 This record will always be emitted in conjunct 432 This record will always be emitted in conjunction with a ``AUDITSYSCALL`` record for the ``write`` syscall.
433 433
434 Field descriptions: 434 Field descriptions:
435 435
436 +----------------+------------+-----------+--- 436 +----------------+------------+-----------+---------------------------------------------------+
437 | Field | Value Type | Optional? | De 437 | Field | Value Type | Optional? | Description of Value |
438 +================+============+===========+=== 438 +================+============+===========+===================================================+
439 | policy_name | string | No | Th 439 | policy_name | string | No | The policy_name |
440 +----------------+------------+-----------+--- 440 +----------------+------------+-----------+---------------------------------------------------+
441 | policy_version | string | No | Th 441 | policy_version | string | No | The policy_version |
442 +----------------+------------+-----------+--- 442 +----------------+------------+-----------+---------------------------------------------------+
443 | policy_digest | string | No | Th 443 | policy_digest | string | No | The policy hash |
444 +----------------+------------+-----------+--- 444 +----------------+------------+-----------+---------------------------------------------------+
445 | auid | integer | No | Th 445 | auid | integer | No | The login user ID |
446 +----------------+------------+-----------+--- 446 +----------------+------------+-----------+---------------------------------------------------+
447 | ses | integer | No | Th 447 | ses | integer | No | The login session ID |
448 +----------------+------------+-----------+--- 448 +----------------+------------+-----------+---------------------------------------------------+
449 | lsm | string | No | Th 449 | lsm | string | No | The lsm name associated with the event |
450 +----------------+------------+-----------+--- 450 +----------------+------------+-----------+---------------------------------------------------+
451 | res | integer | No | Th 451 | res | integer | No | The result of the audited operation(success/fail) |
452 +----------------+------------+-----------+--- 452 +----------------+------------+-----------+---------------------------------------------------+
453 453
454 454
455 1404 AUDIT_MAC_STATUS 455 1404 AUDIT_MAC_STATUS
456 ^^^^^^^^^^^^^^^^^^^^^ 456 ^^^^^^^^^^^^^^^^^^^^^
457 457
458 Event Examples:: 458 Event Examples::
459 459
460 type=1404 audit(1653425689.008:55): enforci 460 type=1404 audit(1653425689.008:55): enforcing=0 old_enforcing=1 auid=4294967295 ses=4294967295 enabled=1 old-enabled=1 lsm=ipe res=1
461 type=1300 audit(1653425689.008:55): arch=c0 461 type=1300 audit(1653425689.008:55): arch=c000003e syscall=1 success=yes exit=2 a0=1 a1=55c1065e5c60 a2=2 a3=0 items=0 ppid=405 pid=441 auid=0 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=)
462 type=1327 audit(1653425689.008:55): proctit 462 type=1327 audit(1653425689.008:55): proctitle="-bash"
463 463
464 type=1404 audit(1653425689.008:55): enforci 464 type=1404 audit(1653425689.008:55): enforcing=1 old_enforcing=0 auid=4294967295 ses=4294967295 enabled=1 old-enabled=1 lsm=ipe res=1
465 type=1300 audit(1653425689.008:55): arch=c0 465 type=1300 audit(1653425689.008:55): arch=c000003e syscall=1 success=yes exit=2 a0=1 a1=55c1065e5c60 a2=2 a3=0 items=0 ppid=405 pid=441 auid=0 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=)
466 type=1327 audit(1653425689.008:55): proctit 466 type=1327 audit(1653425689.008:55): proctitle="-bash"
467 467
468 This record will always be emitted in conjunct 468 This record will always be emitted in conjunction with a ``AUDITSYSCALL`` record for the ``write`` syscall.
469 469
470 Field descriptions: 470 Field descriptions:
471 471
472 +---------------+------------+-----------+---- 472 +---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
473 | Field | Value Type | Optional? | Des 473 | Field | Value Type | Optional? | Description of Value |
474 +===============+============+===========+==== 474 +===============+============+===========+=================================================================================================+
475 | enforcing | integer | No | The 475 | enforcing | integer | No | The enforcing state IPE is being switched to, 1 is in enforcing mode, 0 is in permissive mode |
476 +---------------+------------+-----------+---- 476 +---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
477 | old_enforcing | integer | No | The 477 | old_enforcing | integer | No | The enforcing state IPE is being switched from, 1 is in enforcing mode, 0 is in permissive mode |
478 +---------------+------------+-----------+---- 478 +---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
479 | auid | integer | No | The 479 | auid | integer | No | The login user ID |
480 +---------------+------------+-----------+---- 480 +---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
481 | ses | integer | No | The 481 | ses | integer | No | The login session ID |
482 +---------------+------------+-----------+---- 482 +---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
483 | enabled | integer | No | The 483 | enabled | integer | No | The new TTY audit enabled setting |
484 +---------------+------------+-----------+---- 484 +---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
485 | old-enabled | integer | No | The 485 | old-enabled | integer | No | The old TTY audit enabled setting |
486 +---------------+------------+-----------+---- 486 +---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
487 | lsm | string | No | The 487 | lsm | string | No | The lsm name associated with the event |
488 +---------------+------------+-----------+---- 488 +---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
489 | res | integer | No | The 489 | res | integer | No | The result of the audited operation(success/fail) |
490 +---------------+------------+-----------+---- 490 +---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
491 491
492 492
493 Success Auditing 493 Success Auditing
494 ^^^^^^^^^^^^^^^^ 494 ^^^^^^^^^^^^^^^^
495 495
496 IPE supports success auditing. When enabled, a 496 IPE supports success auditing. When enabled, all events that pass IPE
497 policy and are not blocked will emit an audit 497 policy and are not blocked will emit an audit event. This is disabled by
498 default, and can be enabled via the kernel com 498 default, and can be enabled via the kernel command line
499 ``ipe.success_audit=(0|1)`` or 499 ``ipe.success_audit=(0|1)`` or
500 ``/sys/kernel/security/ipe/success_audit`` sec 500 ``/sys/kernel/security/ipe/success_audit`` securityfs file.
501 501
502 This is *very* noisy, as IPE will check every 502 This is *very* noisy, as IPE will check every userspace binary on the
503 system, but is useful for debugging policies. 503 system, but is useful for debugging policies.
504 504
505 .. NOTE:: 505 .. NOTE::
506 506
507 If a traditional MAC system is enabled (SEL 507 If a traditional MAC system is enabled (SELinux, apparmor, smack, etcetera),
508 all writes to ipe's securityfs nodes requir 508 all writes to ipe's securityfs nodes require ``CAP_MAC_ADMIN``.
509 509
510 Properties 510 Properties
511 ---------- 511 ----------
512 512
513 As explained above, IPE properties are ``key=v 513 As explained above, IPE properties are ``key=value`` pairs expressed in IPE
514 policy. Two properties are built-into the poli 514 policy. Two properties are built-into the policy parser: 'op' and 'action'.
515 The other properties are used to restrict immu 515 The other properties are used to restrict immutable security properties
516 about the files being evaluated. Currently tho 516 about the files being evaluated. Currently those properties are:
517 '``boot_verified``', '``dmverity_signature``', 517 '``boot_verified``', '``dmverity_signature``', '``dmverity_roothash``',
518 '``fsverity_signature``', '``fsverity_digest`` 518 '``fsverity_signature``', '``fsverity_digest``'. A description of all
519 properties supported by IPE are listed below: 519 properties supported by IPE are listed below:
520 520
521 op 521 op
522 ~~ 522 ~~
523 523
524 Indicates the operation for a rule to apply to 524 Indicates the operation for a rule to apply to. Must be in every rule,
525 as the first token. IPE supports the following 525 as the first token. IPE supports the following operations:
526 526
527 ``EXECUTE`` 527 ``EXECUTE``
528 528
529 Pertains to any file attempting to be ex 529 Pertains to any file attempting to be executed, or loaded as an
530 executable. 530 executable.
531 531
532 ``FIRMWARE``: 532 ``FIRMWARE``:
533 533
534 Pertains to firmware being loaded via th 534 Pertains to firmware being loaded via the firmware_class interface.
535 This covers both the preallocated buffer 535 This covers both the preallocated buffer and the firmware file
536 itself. 536 itself.
537 537
538 ``KMODULE``: 538 ``KMODULE``:
539 539
540 Pertains to loading kernel modules via ` 540 Pertains to loading kernel modules via ``modprobe`` or ``insmod``.
541 541
542 ``KEXEC_IMAGE``: 542 ``KEXEC_IMAGE``:
543 543
544 Pertains to kernel images loading via `` 544 Pertains to kernel images loading via ``kexec``.
545 545
546 ``KEXEC_INITRAMFS`` 546 ``KEXEC_INITRAMFS``
547 547
548 Pertains to initrd images loading via `` 548 Pertains to initrd images loading via ``kexec --initrd``.
549 549
550 ``POLICY``: 550 ``POLICY``:
551 551
552 Controls loading policies via reading a 552 Controls loading policies via reading a kernel-space initiated read.
553 553
554 An example of such is loading IMA polici 554 An example of such is loading IMA policies by writing the path
555 to the policy file to ``$securityfs/ima/ 555 to the policy file to ``$securityfs/ima/policy``
556 556
557 ``X509_CERT``: 557 ``X509_CERT``:
558 558
559 Controls loading IMA certificates throug 559 Controls loading IMA certificates through the Kconfigs,
560 ``CONFIG_IMA_X509_PATH`` and ``CONFIG_EV 560 ``CONFIG_IMA_X509_PATH`` and ``CONFIG_EVM_X509_PATH``.
561 561
562 action 562 action
563 ~~~~~~ 563 ~~~~~~
564 564
565 Determines what IPE should do when a rule m 565 Determines what IPE should do when a rule matches. Must be in every
566 rule, as the final clause. Can be one of: 566 rule, as the final clause. Can be one of:
567 567
568 ``ALLOW``: 568 ``ALLOW``:
569 569
570 If the rule matches, explicitly allow ac 570 If the rule matches, explicitly allow access to the resource to proceed
571 without executing any more rules. 571 without executing any more rules.
572 572
573 ``DENY``: 573 ``DENY``:
574 574
575 If the rule matches, explicitly prohibit 575 If the rule matches, explicitly prohibit access to the resource to
576 proceed without executing any more rules 576 proceed without executing any more rules.
577 577
578 boot_verified 578 boot_verified
579 ~~~~~~~~~~~~~ 579 ~~~~~~~~~~~~~
580 580
581 This property can be utilized for authoriza 581 This property can be utilized for authorization of files from initramfs.
582 The format of this property is:: 582 The format of this property is::
583 583
584 boot_verified=(TRUE|FALSE) 584 boot_verified=(TRUE|FALSE)
585 585
586 586
587 .. WARNING:: 587 .. WARNING::
588 588
589 This property will trust files from init 589 This property will trust files from initramfs(rootfs). It should
590 only be used during early booting stage. 590 only be used during early booting stage. Before mounting the real
591 rootfs on top of the initramfs, initramf 591 rootfs on top of the initramfs, initramfs script will recursively
592 remove all files and directories on the 592 remove all files and directories on the initramfs. This is typically
593 implemented by using switch_root(8) [#sw 593 implemented by using switch_root(8) [#switch_root]_. Therefore the
594 initramfs will be empty and not accessib 594 initramfs will be empty and not accessible after the real
595 rootfs takes over. It is advised to swit 595 rootfs takes over. It is advised to switch to a different policy
596 that doesn't rely on the property after 596 that doesn't rely on the property after this point.
597 This ensures that the trust policies rem 597 This ensures that the trust policies remain relevant and effective
598 throughout the system's operation. 598 throughout the system's operation.
599 599
600 dmverity_roothash 600 dmverity_roothash
601 ~~~~~~~~~~~~~~~~~ 601 ~~~~~~~~~~~~~~~~~
602 602
603 This property can be utilized for authoriza 603 This property can be utilized for authorization or revocation of
604 specific dm-verity volumes, identified via 604 specific dm-verity volumes, identified via their root hashes. It has a
605 dependency on the DM_VERITY module. This pr 605 dependency on the DM_VERITY module. This property is controlled by
606 the ``IPE_PROP_DM_VERITY`` config option, i 606 the ``IPE_PROP_DM_VERITY`` config option, it will be automatically
607 selected when ``SECURITY_IPE`` and ``DM_VER 607 selected when ``SECURITY_IPE`` and ``DM_VERITY`` are all enabled.
608 The format of this property is:: 608 The format of this property is::
609 609
610 dmverity_roothash=DigestName:Hexadecimal 610 dmverity_roothash=DigestName:HexadecimalString
611 611
612 The supported DigestNames for dmverity_root 612 The supported DigestNames for dmverity_roothash are [#dmveritydigests]_
613 613
614 + blake2b-512 614 + blake2b-512
615 + blake2s-256 615 + blake2s-256
616 + sha256 616 + sha256
617 + sha384 617 + sha384
618 + sha512 618 + sha512
619 + sha3-224 619 + sha3-224
620 + sha3-256 620 + sha3-256
621 + sha3-384 621 + sha3-384
622 + sha3-512 622 + sha3-512
623 + sm3 623 + sm3
624 + rmd160 624 + rmd160
625 625
626 dmverity_signature 626 dmverity_signature
627 ~~~~~~~~~~~~~~~~~~ 627 ~~~~~~~~~~~~~~~~~~
628 628
629 This property can be utilized for authoriza 629 This property can be utilized for authorization of all dm-verity
630 volumes that have a signed roothash that va 630 volumes that have a signed roothash that validated by a keyring
631 specified by dm-verity's configuration, eit 631 specified by dm-verity's configuration, either the system trusted
632 keyring, or the secondary keyring. It depen 632 keyring, or the secondary keyring. It depends on
633 ``DM_VERITY_VERIFY_ROOTHASH_SIG`` config op 633 ``DM_VERITY_VERIFY_ROOTHASH_SIG`` config option and is controlled by
634 the ``IPE_PROP_DM_VERITY_SIGNATURE`` config 634 the ``IPE_PROP_DM_VERITY_SIGNATURE`` config option, it will be automatically
635 selected when ``SECURITY_IPE``, ``DM_VERITY 635 selected when ``SECURITY_IPE``, ``DM_VERITY`` and
636 ``DM_VERITY_VERIFY_ROOTHASH_SIG`` are all e 636 ``DM_VERITY_VERIFY_ROOTHASH_SIG`` are all enabled.
637 The format of this property is:: 637 The format of this property is::
638 638
639 dmverity_signature=(TRUE|FALSE) 639 dmverity_signature=(TRUE|FALSE)
640 640
641 fsverity_digest 641 fsverity_digest
642 ~~~~~~~~~~~~~~~ 642 ~~~~~~~~~~~~~~~
643 643
644 This property can be utilized for authoriza 644 This property can be utilized for authorization of specific fsverity
645 enabled files, identified via their fsverit 645 enabled files, identified via their fsverity digests.
646 It depends on ``FS_VERITY`` config option a 646 It depends on ``FS_VERITY`` config option and is controlled by
647 the ``IPE_PROP_FS_VERITY`` config option, i 647 the ``IPE_PROP_FS_VERITY`` config option, it will be automatically
648 selected when ``SECURITY_IPE`` and ``FS_VER 648 selected when ``SECURITY_IPE`` and ``FS_VERITY`` are all enabled.
649 The format of this property is:: 649 The format of this property is::
650 650
651 fsverity_digest=DigestName:HexadecimalSt 651 fsverity_digest=DigestName:HexadecimalString
652 652
653 The supported DigestNames for fsverity_dige 653 The supported DigestNames for fsverity_digest are [#fsveritydigest]_
654 654
655 + sha256 655 + sha256
656 + sha512 656 + sha512
657 657
658 fsverity_signature 658 fsverity_signature
659 ~~~~~~~~~~~~~~~~~~ 659 ~~~~~~~~~~~~~~~~~~
660 660
661 This property is used to authorize all fs-v 661 This property is used to authorize all fs-verity enabled files that have
662 been verified by fs-verity's built-in signa 662 been verified by fs-verity's built-in signature mechanism. The signature
663 verification relies on a key stored within 663 verification relies on a key stored within the ".fs-verity" keyring. It
664 depends on ``FS_VERITY_BUILTIN_SIGNATURES`` 664 depends on ``FS_VERITY_BUILTIN_SIGNATURES`` config option and
665 it is controlled by the ``IPE_PROP_FS_VERIT 665 it is controlled by the ``IPE_PROP_FS_VERITY`` config option,
666 it will be automatically selected when ``SE 666 it will be automatically selected when ``SECURITY_IPE``, ``FS_VERITY``
667 and ``FS_VERITY_BUILTIN_SIGNATURES`` are al 667 and ``FS_VERITY_BUILTIN_SIGNATURES`` are all enabled.
668 The format of this property is:: 668 The format of this property is::
669 669
670 fsverity_signature=(TRUE|FALSE) 670 fsverity_signature=(TRUE|FALSE)
671 671
672 Policy Examples 672 Policy Examples
673 --------------- 673 ---------------
674 674
675 Allow all 675 Allow all
676 ~~~~~~~~~ 676 ~~~~~~~~~
677 677
678 :: 678 ::
679 679
680 policy_name=Allow_All policy_version=0.0.0 680 policy_name=Allow_All policy_version=0.0.0
681 DEFAULT action=ALLOW 681 DEFAULT action=ALLOW
682 682
683 Allow only initramfs 683 Allow only initramfs
684 ~~~~~~~~~~~~~~~~~~~~ 684 ~~~~~~~~~~~~~~~~~~~~
685 685
686 :: 686 ::
687 687
688 policy_name=Allow_Initramfs policy_version= 688 policy_name=Allow_Initramfs policy_version=0.0.0
689 DEFAULT action=DENY 689 DEFAULT action=DENY
690 690
691 op=EXECUTE boot_verified=TRUE action=ALLOW 691 op=EXECUTE boot_verified=TRUE action=ALLOW
692 692
693 Allow any signed and validated dm-verity volum 693 Allow any signed and validated dm-verity volume and the initramfs
694 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 694 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
695 695
696 :: 696 ::
697 697
698 policy_name=Allow_Signed_DMV_And_Initramfs 698 policy_name=Allow_Signed_DMV_And_Initramfs policy_version=0.0.0
699 DEFAULT action=DENY 699 DEFAULT action=DENY
700 700
701 op=EXECUTE boot_verified=TRUE action=ALLOW 701 op=EXECUTE boot_verified=TRUE action=ALLOW
702 op=EXECUTE dmverity_signature=TRUE action=A 702 op=EXECUTE dmverity_signature=TRUE action=ALLOW
703 703
704 Prohibit execution from a specific dm-verity v 704 Prohibit execution from a specific dm-verity volume
705 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 705 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
706 706
707 :: 707 ::
708 708
709 policy_name=Deny_DMV_By_Roothash policy_ver 709 policy_name=Deny_DMV_By_Roothash policy_version=0.0.0
710 DEFAULT action=DENY 710 DEFAULT action=DENY
711 711
712 op=EXECUTE dmverity_roothash=sha256:cd2c5ba 712 op=EXECUTE dmverity_roothash=sha256:cd2c5bae7c6c579edaae4353049d58eb5f2e8be0244bf05345bc8e5ed257baff action=DENY
713 713
714 op=EXECUTE boot_verified=TRUE action=ALLOW 714 op=EXECUTE boot_verified=TRUE action=ALLOW
715 op=EXECUTE dmverity_signature=TRUE action=A 715 op=EXECUTE dmverity_signature=TRUE action=ALLOW
716 716
717 Allow only a specific dm-verity volume 717 Allow only a specific dm-verity volume
718 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 718 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
719 719
720 :: 720 ::
721 721
722 policy_name=Allow_DMV_By_Roothash policy_ve 722 policy_name=Allow_DMV_By_Roothash policy_version=0.0.0
723 DEFAULT action=DENY 723 DEFAULT action=DENY
724 724
725 op=EXECUTE dmverity_roothash=sha256:401fcec 725 op=EXECUTE dmverity_roothash=sha256:401fcec5944823ae12f62726e8184407a5fa9599783f030dec146938 action=ALLOW
726 726
727 Allow any fs-verity file with a valid built-in 727 Allow any fs-verity file with a valid built-in signature
728 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 728 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
729 729
730 :: 730 ::
731 731
732 policy_name=Allow_Signed_And_Validated_FSVe 732 policy_name=Allow_Signed_And_Validated_FSVerity policy_version=0.0.0
733 DEFAULT action=DENY 733 DEFAULT action=DENY
734 734
735 op=EXECUTE fsverity_signature=TRUE action=A 735 op=EXECUTE fsverity_signature=TRUE action=ALLOW
736 736
737 Allow execution of a specific fs-verity file 737 Allow execution of a specific fs-verity file
738 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 738 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
739 739
740 :: 740 ::
741 741
742 policy_name=ALLOW_FSV_By_Digest policy_vers 742 policy_name=ALLOW_FSV_By_Digest policy_version=0.0.0
743 DEFAULT action=DENY 743 DEFAULT action=DENY
744 744
745 op=EXECUTE fsverity_digest=sha256:fd88f2b88 745 op=EXECUTE fsverity_digest=sha256:fd88f2b8824e197f850bf4c5109bea5cf0ee38104f710843bb72da796ba5af9e action=ALLOW
746 746
747 Additional Information 747 Additional Information
748 ---------------------- 748 ----------------------
749 749
750 - `Github Repository <https://github.com/micro 750 - `Github Repository <https://github.com/microsoft/ipe>`_
751 - :doc:`Developer and design docs for IPE </se 751 - :doc:`Developer and design docs for IPE </security/ipe>`
752 752
753 FAQ 753 FAQ
754 --- 754 ---
755 755
756 Q: 756 Q:
757 What's the difference between other LSMs wh 757 What's the difference between other LSMs which provide a measure of
758 trust-based access control? 758 trust-based access control?
759 759
760 A: 760 A:
761 761
762 In general, there's two other LSMs that can 762 In general, there's two other LSMs that can provide similar functionality:
763 IMA, and Loadpin. 763 IMA, and Loadpin.
764 764
765 IMA and IPE are functionally very similar. 765 IMA and IPE are functionally very similar. The significant difference between
766 the two is the policy. [#devdoc]_ 766 the two is the policy. [#devdoc]_
767 767
768 Loadpin and IPE differ fairly dramatically, 768 Loadpin and IPE differ fairly dramatically, as Loadpin only covers the IPE's
769 kernel read operations, whereas IPE is capa 769 kernel read operations, whereas IPE is capable of controlling execution
770 on top of kernel read. The trust model is a 770 on top of kernel read. The trust model is also different; Loadpin roots its
771 trust in the initial super-block, whereas t 771 trust in the initial super-block, whereas trust in IPE is stemmed from kernel
772 itself (via ``SYSTEM_TRUSTED_KEYS``). 772 itself (via ``SYSTEM_TRUSTED_KEYS``).
773 773
774 ----------- 774 -----------
775 775
776 .. [#digest_cache_lsm] https://lore.kernel.org 776 .. [#digest_cache_lsm] https://lore.kernel.org/lkml/20240415142436.2545003-1-roberto.sassu@huaweicloud.com/
777 777
778 .. [#interpreters] There is `some interest in < 778 .. [#interpreters] There is `some interest in solving this issue <https://lore.kernel.org/lkml/20220321161557.495388-1-mic@digikod.net/">https://lore.kernel.org/lkml/20220321161557.495388-1-mic@digikod.net/>`_.
779 779
780 .. [#devdoc] Please see :doc:`the design docs 780 .. [#devdoc] Please see :doc:`the design docs </security/ipe>` for more on
781 this topic. 781 this topic.
782 782
783 .. [#switch_root] https://man7.org/linux/man-p 783 .. [#switch_root] https://man7.org/linux/man-pages/man8/switch_root.8.html
784 784
785 .. [#dmveritydigests] These hash algorithms ar 785 .. [#dmveritydigests] These hash algorithms are based on values accepted by
786 the Linux crypto API; IP 786 the Linux crypto API; IPE does not impose any
787 restrictions on the dige 787 restrictions on the digest algorithm itself;
788 thus, this list may be o 788 thus, this list may be out of date.
789 789
790 .. [#fsveritydigest] These hash algorithms are 790 .. [#fsveritydigest] These hash algorithms are based on values accepted by the
791 kernel's fsverity support 791 kernel's fsverity support; IPE does not impose any
792 restrictions on the diges 792 restrictions on the digest algorithm itself;
793 thus, this list may be ou 793 thus, this list may be out of date.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.