Re: [PATCH v18 20/21] Documentation: add ipe documentation

2024-05-14 Thread Paul Moore 
On Sat, May 4, 2024 at 4:13 PM Fan Wu  wrote:
> On 5/4/2024 1:04 AM, Bagas Sanjaya wrote:
> > On Fri, May 03, 2024 at 03:32:30PM -0700, Fan Wu wrote:
> >> +IPE does not mitigate threats arising from malicious but authorized
> >> +developers (with access to a signing certificate), or compromised
> >> +developer tools used by them (i.e. return-oriented programming attacks).
> >> +Additionally, IPE draws hard security boundary between userspace and
> >> +kernelspace. As a result, IPE does not provide any protections against a
> >> +kernel level exploit, and a kernel-level exploit can disable or tamper
> >> +with IPE's protections.
> >
> > So how to mitigate kernel-level exploits then?
>
> One possible way is to use hypervisor to protect the kernel integrity.
> https://github.com/heki-linux is one project on this direction. Perhaps
> I should also add this link to the doc.

I wouldn't spend a lot of time on kernel exploits in the IPE
documentation as it is out of scope for IPE.  In face, I would say
just that in the last sentence in the paragraph above:

"As a result, kernel-level exploits are considered outside the scope
of IPE and mitigation is left to other mechanisms."

(or something similar)

-- 
paul-moore.com

Re: [PATCH v18 20/21] Documentation: add ipe documentation

2024-05-04 Thread Bagas Sanjaya 
On Sat, May 04, 2024 at 01:13:16PM -0700, Fan Wu wrote:
> 
> 
> On 5/4/2024 1:04 AM, Bagas Sanjaya wrote:
> > On Fri, May 03, 2024 at 03:32:30PM -0700, Fan Wu wrote:
> > > +IPE does not mitigate threats arising from malicious but authorized
> > > +developers (with access to a signing certificate), or compromised
> > > +developer tools used by them (i.e. return-oriented programming attacks).
> > > +Additionally, IPE draws hard security boundary between userspace and
> > > +kernelspace. As a result, IPE does not provide any protections against a
> > > +kernel level exploit, and a kernel-level exploit can disable or tamper
> > > +with IPE's protections.
> > 
> > So how to mitigate kernel-level exploits then?
> > 
> One possible way is to use hypervisor to protect the kernel integrity.
> https://github.com/heki-linux is one project on this direction. Perhaps I
> should also add this link to the doc.

OK.

> 
> > > +Allow only initramfs
> > > +~
> > > ...
> > > +Allow any signed and validated dm-verity volume and the initramfs
> > > +
> > > ...
> > 
> > htmldocs build reports new warnings:
> > 
> > Documentation/admin-guide/LSM/ipe.rst:694: WARNING: Title underline too 
> > short.
> > 
> > Allow any signed and validated dm-verity volume and the initramfs
> > 
> > Documentation/admin-guide/LSM/ipe.rst:694: WARNING: Title underline too 
> > short.
> > 
> > Allow any signed and validated dm-verity volume and the initramfs
> > 
> > Documentation/arch/x86/resctrl.rst:577: WARNING: Title underline too short.
> > 
> > I have to match these sections underline length:
> > 
> >  >8 
> > diff --git a/Documentation/admin-guide/LSM/ipe.rst 
> > b/Documentation/admin-guide/LSM/ipe.rst
> > index 1a3bf1d8aa23f0..a47e14e024a90d 100644
> > --- a/Documentation/admin-guide/LSM/ipe.rst
> > +++ b/Documentation/admin-guide/LSM/ipe.rst
> > @@ -681,7 +681,7 @@ Allow all
> >  DEFAULT action=ALLOW
> >   Allow only initramfs
> > -~
> > +
> >   ::
> > @@ -691,7 +691,7 @@ Allow only initramfs
> >  op=EXECUTE boot_verified=TRUE action=ALLOW
> >   Allow any signed and validated dm-verity volume and the initramfs
> > -
> > +~
> >   ::
> > @@ -725,7 +725,7 @@ Allow only a specific dm-verity volume
> >  op=EXECUTE 
> > dmverity_roothash=sha256:401fcec5944823ae12f62726e8184407a5fa9599783f030dec146938
> >  action=ALLOW
> >   Allow any fs-verity file with a valid built-in signature
> > -
> > +
> >   ::
> > @@ -735,7 +735,7 @@ Allow any fs-verity file with a valid built-in signature
> >  op=EXECUTE fsverity_signature=TRUE action=ALLOW
> >   Allow execution of a specific fs-verity file
> > -~~~
> > +
> >   ::
> > 
> > > +Additional Information
> > > +--
> > > +
> > > +- `Github Repository `_
> > > +- Documentation/security/ipe.rst
> > 
> > Link title to both this admin-side and developer docs can be added for
> > disambiguation (to avoid confusion on readers):
> > 
> >  >8 
> > diff --git a/Documentation/admin-guide/LSM/ipe.rst 
> > b/Documentation/admin-guide/LSM/ipe.rst
> > index a47e14e024a90d..25b17e11559149 100644
> > --- a/Documentation/admin-guide/LSM/ipe.rst
> > +++ b/Documentation/admin-guide/LSM/ipe.rst
> > @@ -7,7 +7,8 @@ Integrity Policy Enforcement (IPE)
> >  This is the documentation for admins, system builders, or individuals
> >  attempting to use IPE. If you're looking for more developer-focused
> > -   documentation about IPE please see Documentation/security/ipe.rst
> > +   documentation about IPE please see :doc:`the design docs
> > +   `.
> >   Overview
> >   
> > @@ -748,7 +749,7 @@ Additional Information
> >   --
> >   - `Github Repository `_
> > -- Documentation/security/ipe.rst
> > +- :doc:`Developer and design docs for IPE `
> >   FAQ
> >   ---
> > diff --git a/Documentation/security/ipe.rst b/Documentation/security/ipe.rst
> > index 07e3632241285d..fd1b1a852d2165 100644
> > --- a/Documentation/security/ipe.rst
> > +++ b/Documentation/security/ipe.rst
> > @@ -7,7 +7,7 @@ Integrity Policy Enforcement (IPE) - Kernel Documentation
> >  This is documentation targeted at developers, instead of 
> > administrators.
> >  If you're looking for documentation on the usage of IPE, please see
> > -   Documentation/admin-guide/LSM/ipe.rst
> > +   `IPE admin guide `_.
> >   Historical Motivation
> >

Re: [PATCH v18 20/21] Documentation: add ipe documentation

2024-05-04 Thread Fan Wu 




On 5/4/2024 1:04 AM, Bagas Sanjaya wrote:

On Fri, May 03, 2024 at 03:32:30PM -0700, Fan Wu wrote:

+IPE does not mitigate threats arising from malicious but authorized
+developers (with access to a signing certificate), or compromised
+developer tools used by them (i.e. return-oriented programming attacks).
+Additionally, IPE draws hard security boundary between userspace and
+kernelspace. As a result, IPE does not provide any protections against a
+kernel level exploit, and a kernel-level exploit can disable or tamper
+with IPE's protections.


So how to mitigate kernel-level exploits then?

One possible way is to use hypervisor to protect the kernel integrity. 
https://github.com/heki-linux is one project on this direction. Perhaps 
I should also add this link to the doc.



+Allow only initramfs
+~
...
+Allow any signed and validated dm-verity volume and the initramfs
+
...


htmldocs build reports new warnings:

Documentation/admin-guide/LSM/ipe.rst:694: WARNING: Title underline too short.

Allow any signed and validated dm-verity volume and the initramfs

Documentation/admin-guide/LSM/ipe.rst:694: WARNING: Title underline too short.

Allow any signed and validated dm-verity volume and the initramfs

Documentation/arch/x86/resctrl.rst:577: WARNING: Title underline too short.

I have to match these sections underline length:

 >8 
diff --git a/Documentation/admin-guide/LSM/ipe.rst 
b/Documentation/admin-guide/LSM/ipe.rst
index 1a3bf1d8aa23f0..a47e14e024a90d 100644
--- a/Documentation/admin-guide/LSM/ipe.rst
+++ b/Documentation/admin-guide/LSM/ipe.rst
@@ -681,7 +681,7 @@ Allow all
 DEFAULT action=ALLOW
  
  Allow only initramfs

-~
+
  
  ::
  
@@ -691,7 +691,7 @@ Allow only initramfs

 op=EXECUTE boot_verified=TRUE action=ALLOW
  
  Allow any signed and validated dm-verity volume and the initramfs

-
+~
  
  ::
  
@@ -725,7 +725,7 @@ Allow only a specific dm-verity volume

 op=EXECUTE 
dmverity_roothash=sha256:401fcec5944823ae12f62726e8184407a5fa9599783f030dec146938
 action=ALLOW
  
  Allow any fs-verity file with a valid built-in signature

-
+
  
  ::
  
@@ -735,7 +735,7 @@ Allow any fs-verity file with a valid built-in signature

 op=EXECUTE fsverity_signature=TRUE action=ALLOW
  
  Allow execution of a specific fs-verity file

-~~~
+
  
  ::
  


+Additional Information
+--
+
+- `Github Repository `_
+- Documentation/security/ipe.rst


Link title to both this admin-side and developer docs can be added for
disambiguation (to avoid confusion on readers):

 >8 
diff --git a/Documentation/admin-guide/LSM/ipe.rst 
b/Documentation/admin-guide/LSM/ipe.rst
index a47e14e024a90d..25b17e11559149 100644
--- a/Documentation/admin-guide/LSM/ipe.rst
+++ b/Documentation/admin-guide/LSM/ipe.rst
@@ -7,7 +7,8 @@ Integrity Policy Enforcement (IPE)
  
 This is the documentation for admins, system builders, or individuals

 attempting to use IPE. If you're looking for more developer-focused
-   documentation about IPE please see Documentation/security/ipe.rst
+   documentation about IPE please see :doc:`the design docs
+   `.
  
  Overview

  
@@ -748,7 +749,7 @@ Additional Information
  --
  
  - `Github Repository `_

-- Documentation/security/ipe.rst
+- :doc:`Developer and design docs for IPE `
  
  FAQ

  ---
diff --git a/Documentation/security/ipe.rst b/Documentation/security/ipe.rst
index 07e3632241285d..fd1b1a852d2165 100644
--- a/Documentation/security/ipe.rst
+++ b/Documentation/security/ipe.rst
@@ -7,7 +7,7 @@ Integrity Policy Enforcement (IPE) - Kernel Documentation
  
 This is documentation targeted at developers, instead of administrators.

 If you're looking for documentation on the usage of IPE, please see
-   Documentation/admin-guide/LSM/ipe.rst
+   `IPE admin guide `_.
  
  Historical Motivation

  -

Thanks.



My apologies for these format issues and thanks for the suggestions. I 
will fix them.

-Fan

Re: [PATCH v18 20/21] Documentation: add ipe documentation

2024-05-04 Thread Bagas Sanjaya 
On Fri, May 03, 2024 at 03:32:30PM -0700, Fan Wu wrote:
> +IPE does not mitigate threats arising from malicious but authorized
> +developers (with access to a signing certificate), or compromised
> +developer tools used by them (i.e. return-oriented programming attacks).
> +Additionally, IPE draws hard security boundary between userspace and
> +kernelspace. As a result, IPE does not provide any protections against a
> +kernel level exploit, and a kernel-level exploit can disable or tamper
> +with IPE's protections.

So how to mitigate kernel-level exploits then?

> +Allow only initramfs
> +~
> ...
> +Allow any signed and validated dm-verity volume and the initramfs
> +
> ...

htmldocs build reports new warnings:

Documentation/admin-guide/LSM/ipe.rst:694: WARNING: Title underline too short.

Allow any signed and validated dm-verity volume and the initramfs

Documentation/admin-guide/LSM/ipe.rst:694: WARNING: Title underline too short.

Allow any signed and validated dm-verity volume and the initramfs

Documentation/arch/x86/resctrl.rst:577: WARNING: Title underline too short.

I have to match these sections underline length:

 >8 
diff --git a/Documentation/admin-guide/LSM/ipe.rst 
b/Documentation/admin-guide/LSM/ipe.rst
index 1a3bf1d8aa23f0..a47e14e024a90d 100644
--- a/Documentation/admin-guide/LSM/ipe.rst
+++ b/Documentation/admin-guide/LSM/ipe.rst
@@ -681,7 +681,7 @@ Allow all
DEFAULT action=ALLOW
 
 Allow only initramfs
-~
+
 
 ::
 
@@ -691,7 +691,7 @@ Allow only initramfs
op=EXECUTE boot_verified=TRUE action=ALLOW
 
 Allow any signed and validated dm-verity volume and the initramfs
-
+~
 
 ::
 
@@ -725,7 +725,7 @@ Allow only a specific dm-verity volume
op=EXECUTE 
dmverity_roothash=sha256:401fcec5944823ae12f62726e8184407a5fa9599783f030dec146938
 action=ALLOW
 
 Allow any fs-verity file with a valid built-in signature
-
+
 
 ::
 
@@ -735,7 +735,7 @@ Allow any fs-verity file with a valid built-in signature
op=EXECUTE fsverity_signature=TRUE action=ALLOW
 
 Allow execution of a specific fs-verity file
-~~~
+
 
 ::
 

> +Additional Information
> +--
> +
> +- `Github Repository `_
> +- Documentation/security/ipe.rst

Link title to both this admin-side and developer docs can be added for
disambiguation (to avoid confusion on readers):

 >8 
diff --git a/Documentation/admin-guide/LSM/ipe.rst 
b/Documentation/admin-guide/LSM/ipe.rst
index a47e14e024a90d..25b17e11559149 100644
--- a/Documentation/admin-guide/LSM/ipe.rst
+++ b/Documentation/admin-guide/LSM/ipe.rst
@@ -7,7 +7,8 @@ Integrity Policy Enforcement (IPE)
 
This is the documentation for admins, system builders, or individuals
attempting to use IPE. If you're looking for more developer-focused
-   documentation about IPE please see Documentation/security/ipe.rst
+   documentation about IPE please see :doc:`the design docs
+   `.
 
 Overview
 
@@ -748,7 +749,7 @@ Additional Information
 --
 
 - `Github Repository `_
-- Documentation/security/ipe.rst
+- :doc:`Developer and design docs for IPE `
 
 FAQ
 ---
diff --git a/Documentation/security/ipe.rst b/Documentation/security/ipe.rst
index 07e3632241285d..fd1b1a852d2165 100644
--- a/Documentation/security/ipe.rst
+++ b/Documentation/security/ipe.rst
@@ -7,7 +7,7 @@ Integrity Policy Enforcement (IPE) - Kernel Documentation
 
This is documentation targeted at developers, instead of administrators.
If you're looking for documentation on the usage of IPE, please see
-   Documentation/admin-guide/LSM/ipe.rst
+   `IPE admin guide `_.
 
 Historical Motivation
 -

Thanks.

-- 
An old man doll... just what I always wanted! - Clara


signature.asc
Description: PGP signature

[PATCH v18 20/21] Documentation: add ipe documentation

2024-05-03 Thread Fan Wu 
From: Deven Bowers 

Add IPE's admin and developer documentation to the kernel tree.

Co-developed-by: Fan Wu 
Signed-off-by: Deven Bowers 
Signed-off-by: Fan Wu 
---
v2:
  + No Changes

v3:
  + Add Acked-by
  + Fixup code block syntax
  + Fix a minor grammatical issue.

v4:
  + Update documentation with the results of other
code changes.

v5:
  + No changes

v6:
  + No changes

v7:
  + Add additional developer-level documentation
  + Update admin-guide docs to reflect changes.
  + Drop Acked-by due to significant changes
  + Added section about audit events in admin-guide

v8:
  + Correct terminology from "audit event" to "audit record"
  + Add associated documentation with the correct "audit event"
terminology.
  + Add some context to the historical motivation for IPE and design
philosophy.
  + Add some content about the securityfs layout in the policies
directory.
  + Various spelling and grammatical corrections.

v9:
  + Correct spelling of "pitfalls"
  + Update the docs w.r.t the new parser and new audit formats

v10:
  + Refine user docs per upstream suggestions
  + Update audit events part

v11:
  + No changes

v12:
  + Update audit formats
  + Update initramfs related docs
  + Add test suite link

v13:
  + No changes

v14:
  + No changes

v15:
  + Update boot_verified part
  + Fix format issues
  + Add IPE doc link to fsverity.rst

v16:
  + Explicitly mention fsverity builtin signature

v17:
  + Rewrite many parts of Documentation/admin-guide/LSM/ipe.rst
  + Fix incorrect path name of policyfs interfaces

v18:
  + Improve policy examples
  + Remove insecure hash algorithms and adapt the documentation
accordingly
  + Update the documentation regarding the new Kconfig switches
---
 Documentation/admin-guide/LSM/index.rst   |   1 +
 Documentation/admin-guide/LSM/ipe.rst | 792 ++
 .../admin-guide/kernel-parameters.txt |  12 +
 Documentation/filesystems/fsverity.rst|   5 +-
 Documentation/security/index.rst  |   1 +
 Documentation/security/ipe.rst| 446 ++
 6 files changed, 1256 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/admin-guide/LSM/ipe.rst
 create mode 100644 Documentation/security/ipe.rst

diff --git a/Documentation/admin-guide/LSM/index.rst 
b/Documentation/admin-guide/LSM/index.rst
index a6ba95fbaa9f..ce63be6d64ad 100644
--- a/Documentation/admin-guide/LSM/index.rst
+++ b/Documentation/admin-guide/LSM/index.rst
@@ -47,3 +47,4 @@ subdirectories.
tomoyo
Yama
SafeSetID
+   ipe
diff --git a/Documentation/admin-guide/LSM/ipe.rst 
b/Documentation/admin-guide/LSM/ipe.rst
new file mode 100644
index ..1a3bf1d8aa23
--- /dev/null
+++ b/Documentation/admin-guide/LSM/ipe.rst
@@ -0,0 +1,792 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Integrity Policy Enforcement (IPE)
+==
+
+.. NOTE::
+
+   This is the documentation for admins, system builders, or individuals
+   attempting to use IPE. If you're looking for more developer-focused
+   documentation about IPE please see Documentation/security/ipe.rst
+
+Overview
+
+
+Integrity Policy Enforcement (IPE) is a Linux Security Module that takes a
+complementary approach to access control. Unlike traditional access control
+mechanisms that rely on labels and paths for decision-making, IPE focuses
+on the immutable security properties inherent to system components. These
+properties are fundamental attributes or features of a system component
+that cannot be altered, ensuring a consistent and reliable basis for
+security decisions.
+
+To elaborate, in the context of IPE, system components primarily refer to
+files or the devices these files reside on. However, this is just a
+starting point. The concept of system components is flexible and can be
+extended to include new elements as the system evolves. The immutable
+properties include the origin of a file, which remains constant and
+unchangeable over time. For example, IPE policies can be crafted to trust
+files originating from the initramfs. Since initramfs is typically verified
+by the bootloader, its files are deemed trustworthy; "file is from
+initramfs" becomes an immutable property under IPE's consideration.
+
+The immutable property concept extends to the security features enabled on
+a file's origin, such as dm-verity or fs-verity, which provide a layer of
+integrity and trust. For example, IPE allows the definition of policies
+that trust files from a dm-verity protected device. dm-verity ensures the
+integrity of an entire device by providing a verifiable and immutable state
+of its contents. Similarly, fs-verity offers filesystem-level integrity
+checks, allowing IPE to enforce policies that trust files protected by
+fs-verity. These two features cannot be turned off once established, so
+they are considered immutable properties. These examples demonstrate how
+IPE leverages immutable properties, such as a file's origin and