[v6,7/7] mseal, system mappings: update mseal.rst

Commit Message

Jeff Xu Feb. 24, 2025, 5:45 p.m. UTC

From: Jeff Xu <[e-mail]>

Update memory sealing documentation to include details about system
mappings.

Signed-off-by: Jeff Xu <[e-mail]>
---
 Documentation/userspace-api/mseal.rst | 7 +++++++
 1 file changed, 7 insertions(+)

Comments

Kees Cook Feb. 24, 2025, 7:04 p.m. UTC | #1

On Mon, Feb 24, 2025 at 05:45:13PM +0000, [e-mail] wrote:
> From: Jeff Xu <[e-mail]>
> 
> Update memory sealing documentation to include details about system
> mappings.
> 
> Signed-off-by: Jeff Xu <[e-mail]>

Thanks, I think the list of programs is good.

Reviewed-by: Kees Cook <[e-mail]>

Liam R. Howlett Feb. 24, 2025, 8:26 p.m. UTC | #2

* [e-mail] <[e-mail]> [250224 12:45]:
> From: Jeff Xu <[e-mail]>
> 
> Update memory sealing documentation to include details about system
> mappings.
> 
> Signed-off-by: Jeff Xu <[e-mail]>
> ---
>  Documentation/userspace-api/mseal.rst | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/Documentation/userspace-api/mseal.rst b/Documentation/userspace-api/mseal.rst
> index 41102f74c5e2..10147281bf2d 100644
> --- a/Documentation/userspace-api/mseal.rst
> +++ b/Documentation/userspace-api/mseal.rst
> @@ -130,6 +130,13 @@ Use cases
>  
>  - Chrome browser: protect some security sensitive data structures.

Did you mean to drop this line?

>  
> +- System mappings:
> +  If supported by an architecture (via CONFIG_ARCH_HAS_MSEAL_SYSTEM_MAPPINGS),
> +  the CONFIG_MSEAL_SYSTEM_MAPPINGS seals system mappings, e.g. vdso, vvar,
> +  uprobes, sigpage, vectors, etc. CHECKPOINT_RESTORE, UML, gVisor, rr are
> +  known to relocate or unmap system mapping, therefore this config can't be
> +  enabled universally.
> +
>  When not to use mseal
>  =====================
>  Applications can apply sealing to any virtual memory region from userspace,
> -- 
> 2.48.1.601.g30ceb7b040-goog
>

Jeff Xu Feb. 24, 2025, 9:06 p.m. UTC | #3

On Mon, Feb 24, 2025 at 12:26 PM Liam R. Howlett
<[e-mail]> wrote:
>
> * [e-mail] <[e-mail]> [250224 12:45]:
> > From: Jeff Xu <[e-mail]>
> >
> > Update memory sealing documentation to include details about system
> > mappings.
> >
> > Signed-off-by: Jeff Xu <[e-mail]>
> > ---
> >  Documentation/userspace-api/mseal.rst | 7 +++++++
> >  1 file changed, 7 insertions(+)
> >
> > diff --git a/Documentation/userspace-api/mseal.rst b/Documentation/userspace-api/mseal.rst
> > index 41102f74c5e2..10147281bf2d 100644
> > --- a/Documentation/userspace-api/mseal.rst
> > +++ b/Documentation/userspace-api/mseal.rst
> > @@ -130,6 +130,13 @@ Use cases
> >
> >  - Chrome browser: protect some security sensitive data structures.
>
> Did you mean to drop this line?
>
Ah, thank you for catching that.

-Jeff


> >
> > +- System mappings:
> > +  If supported by an architecture (via CONFIG_ARCH_HAS_MSEAL_SYSTEM_MAPPINGS),
> > +  the CONFIG_MSEAL_SYSTEM_MAPPINGS seals system mappings, e.g. vdso, vvar,
> > +  uprobes, sigpage, vectors, etc. CHECKPOINT_RESTORE, UML, gVisor, rr are
> > +  known to relocate or unmap system mapping, therefore this config can't be
> > +  enabled universally.
> > +
> >  When not to use mseal
> >  =====================
> >  Applications can apply sealing to any virtual memory region from userspace,
> > --
> > 2.48.1.601.g30ceb7b040-goog
> >

Jeff Xu Feb. 24, 2025, 9:54 p.m. UTC | #4

On Mon, Feb 24, 2025 at 1:06 PM Jeff Xu <[e-mail]> wrote:
>
> On Mon, Feb 24, 2025 at 12:26 PM Liam R. Howlett
> <[e-mail]> wrote:
> >
> > * [e-mail] <[e-mail]> [250224 12:45]:
> > > From: Jeff Xu <[e-mail]>
> > >
> > > Update memory sealing documentation to include details about system
> > > mappings.
> > >
> > > Signed-off-by: Jeff Xu <[e-mail]>
> > > ---
> > >  Documentation/userspace-api/mseal.rst | 7 +++++++
> > >  1 file changed, 7 insertions(+)
> > >
> > > diff --git a/Documentation/userspace-api/mseal.rst b/Documentation/userspace-api/mseal.rst
> > > index 41102f74c5e2..10147281bf2d 100644
> > > --- a/Documentation/userspace-api/mseal.rst
> > > +++ b/Documentation/userspace-api/mseal.rst
> > > @@ -130,6 +130,13 @@ Use cases
> > >
> > >  - Chrome browser: protect some security sensitive data structures.
> >
> > Did you mean to drop this line?
> >
> Ah, thank you for catching that.
>
Actually, this isn't a problem here.
The "-" here is part of the text, for list, so that line is not dropped).

-Jeff


> -Jeff
>
>
> > >
> > > +- System mappings:
> > > +  If supported by an architecture (via CONFIG_ARCH_HAS_MSEAL_SYSTEM_MAPPINGS),
> > > +  the CONFIG_MSEAL_SYSTEM_MAPPINGS seals system mappings, e.g. vdso, vvar,
> > > +  uprobes, sigpage, vectors, etc. CHECKPOINT_RESTORE, UML, gVisor, rr are
> > > +  known to relocate or unmap system mapping, therefore this config can't be
> > > +  enabled universally.
> > > +
> > >  When not to use mseal
> > >  =====================
> > >  Applications can apply sealing to any virtual memory region from userspace,
> > > --
> > > 2.48.1.601.g30ceb7b040-goog
> > >

Lorenzo Stoakes Feb. 25, 2025, 6:07 a.m. UTC | #5

On Mon, Feb 24, 2025 at 05:45:13PM +0000, [e-mail] wrote:
> From: Jeff Xu <[e-mail]>
>
> Update memory sealing documentation to include details about system
> mappings.
>
> Signed-off-by: Jeff Xu <[e-mail]>
> ---
>  Documentation/userspace-api/mseal.rst | 7 +++++++
>  1 file changed, 7 insertions(+)
>
> diff --git a/Documentation/userspace-api/mseal.rst b/Documentation/userspace-api/mseal.rst
> index 41102f74c5e2..10147281bf2d 100644
> --- a/Documentation/userspace-api/mseal.rst
> +++ b/Documentation/userspace-api/mseal.rst
> @@ -130,6 +130,13 @@ Use cases
>
>  - Chrome browser: protect some security sensitive data structures.
>
> +- System mappings:
> +  If supported by an architecture (via CONFIG_ARCH_HAS_MSEAL_SYSTEM_MAPPINGS),
> +  the CONFIG_MSEAL_SYSTEM_MAPPINGS seals system mappings, e.g. vdso, vvar,
> +  uprobes, sigpage, vectors, etc. CHECKPOINT_RESTORE, UML, gVisor, rr are
> +  known to relocate or unmap system mapping, therefore this config can't be
> +  enabled universally.

Thanks for adding this.

Similar comments to the Kconfig update - you are listing features that do not
exist yet, please just list what you're doing, specifically, and avoid the vague
'etc.', we don't need to be vague.

As per the Kconfig comment - you need to be a lot more clear, I think you're
duplicating the text from there to here, so again I suggest something like:

WARNING: This feature breaks programs which rely on relocating or
         unmapping system mappings.

         Known broken software at the time of writing includes
         CHECKPOINT_RESTORE, UML, gVisor and rr.

You also seem to be writing very little here, it's a documentation page, you can
be as verbose as you like :)

You really need to add some more detail here in general - you aren't explaining
why people would want to enable this, what you're mitigating, etc. from that you
explain _why_ it doesn't work for some things.

You're also not mentioning architectural limitations here, for instance that you
can only do this on arches that don't require VDSO relocation and listing
known-good arches.

This is a documentation file, you can go wild :) the more information here the
better.

WARNING
=======

> +
>  When not to use mseal
>  =====================
>  Applications can apply sealing to any virtual memory region from userspace,
> --
> 2.48.1.601.g30ceb7b040-goog
>

Jeff Xu Feb. 25, 2025, 10:31 p.m. UTC | #6

On Mon, Feb 24, 2025 at 10:07 PM Lorenzo Stoakes
<[e-mail]> wrote:
>
> On Mon, Feb 24, 2025 at 05:45:13PM +0000, [e-mail] wrote:
> > From: Jeff Xu <[e-mail]>
> >
> > Update memory sealing documentation to include details about system
> > mappings.
> >
> > Signed-off-by: Jeff Xu <[e-mail]>
> > ---
> >  Documentation/userspace-api/mseal.rst | 7 +++++++
> >  1 file changed, 7 insertions(+)
> >
> > diff --git a/Documentation/userspace-api/mseal.rst b/Documentation/userspace-api/mseal.rst
> > index 41102f74c5e2..10147281bf2d 100644
> > --- a/Documentation/userspace-api/mseal.rst
> > +++ b/Documentation/userspace-api/mseal.rst
> > @@ -130,6 +130,13 @@ Use cases
> >
> >  - Chrome browser: protect some security sensitive data structures.
> >
> > +- System mappings:
> > +  If supported by an architecture (via CONFIG_ARCH_HAS_MSEAL_SYSTEM_MAPPINGS),
> > +  the CONFIG_MSEAL_SYSTEM_MAPPINGS seals system mappings, e.g. vdso, vvar,
> > +  uprobes, sigpage, vectors, etc. CHECKPOINT_RESTORE, UML, gVisor, rr are
> > +  known to relocate or unmap system mapping, therefore this config can't be
> > +  enabled universally.
>
> Thanks for adding this.
>
> Similar comments to the Kconfig update - you are listing features that do not
> exist yet, please just list what you're doing, specifically, and avoid the vague
> 'etc.', we don't need to be vague.
>
OK, I will remove etc and list the known mappings here.

> As per the Kconfig comment - you need to be a lot more clear, I think you're
> duplicating the text from there to here, so again I suggest something like:
>
> WARNING: This feature breaks programs which rely on relocating or
>          unmapping system mappings.
>
>          Known broken software at the time of writing includes
>          CHECKPOINT_RESTORE, UML, gVisor and rr.
>
Sure.

> You also seem to be writing very little here, it's a documentation page, you can
> be as verbose as you like :)
>
> You really need to add some more detail here in general - you aren't explaining
> why people would want to enable this, what you're mitigating, etc. from that you
> explain _why_ it doesn't work for some things.
>
The mseal.rst already includes below regarding the protection/mitigation.





> You're also not mentioning architectural limitations here, for instance that you
> can only do this on arches that don't require VDSO relocation and listing
> known-good arches.
>
> This is a documentation file, you can go wild :) the more information here the
> better.
>
> WARNING
> =======
>
> > +
> >  When not to use mseal
> >  =====================
> >  Applications can apply sealing to any virtual memory region from userspace,
> > --
> > 2.48.1.601.g30ceb7b040-goog
> >

Jeff Xu Feb. 25, 2025, 10:36 p.m. UTC | #7

On Tue, Feb 25, 2025 at 2:31 PM Jeff Xu <[e-mail]> wrote:
>
> On Mon, Feb 24, 2025 at 10:07 PM Lorenzo Stoakes
> <[e-mail]> wrote:
> >
> > On Mon, Feb 24, 2025 at 05:45:13PM +0000, [e-mail] wrote:
> > > From: Jeff Xu <[e-mail]>
> > >
> > > Update memory sealing documentation to include details about system
> > > mappings.
> > >
> > > Signed-off-by: Jeff Xu <[e-mail]>
> > > ---
> > >  Documentation/userspace-api/mseal.rst | 7 +++++++
> > >  1 file changed, 7 insertions(+)
> > >
> > > diff --git a/Documentation/userspace-api/mseal.rst b/Documentation/userspace-api/mseal.rst
> > > index 41102f74c5e2..10147281bf2d 100644
> > > --- a/Documentation/userspace-api/mseal.rst
> > > +++ b/Documentation/userspace-api/mseal.rst
> > > @@ -130,6 +130,13 @@ Use cases
> > >
> > >  - Chrome browser: protect some security sensitive data structures.
> > >
> > > +- System mappings:
> > > +  If supported by an architecture (via CONFIG_ARCH_HAS_MSEAL_SYSTEM_MAPPINGS),
> > > +  the CONFIG_MSEAL_SYSTEM_MAPPINGS seals system mappings, e.g. vdso, vvar,
> > > +  uprobes, sigpage, vectors, etc. CHECKPOINT_RESTORE, UML, gVisor, rr are
> > > +  known to relocate or unmap system mapping, therefore this config can't be
> > > +  enabled universally.
> >
> > Thanks for adding this.
> >
> > Similar comments to the Kconfig update - you are listing features that do not
> > exist yet, please just list what you're doing, specifically, and avoid the vague
> > 'etc.', we don't need to be vague.
> >
> OK, I will remove etc and list the known mappings here.
>
> > As per the Kconfig comment - you need to be a lot more clear, I think you're
> > duplicating the text from there to here, so again I suggest something like:
> >
> > WARNING: This feature breaks programs which rely on relocating or
> >          unmapping system mappings.
> >
> >          Known broken software at the time of writing includes
> >          CHECKPOINT_RESTORE, UML, gVisor and rr.
> >
> Sure.
>
> > You also seem to be writing very little here, it's a documentation page, you can
> > be as verbose as you like :)
> >
> > You really need to add some more detail here in general - you aren't explaining
> > why people would want to enable this, what you're mitigating, etc. from that you
> > explain _why_ it doesn't work for some things.
> >

The mseal.rst already includes below regarding the protection/mitigation.

Memory sealing additionally protects the mapping itself against
modifications. This is useful to mitigate memory corruption issues where a
corrupted pointer is passed to a memory management system. For example,
such an attacker primitive can break control-flow integrity guarantees
since read-only memory that is supposed to be trusted can become writable
or .text pages can get remapped. Memory sealing can automatically be
applied by the runtime loader to seal .text and .rodata pages and
applications can additionally seal security critical data at runtime.

I could copy  some sections from cover-letter to here, specifically
for special mappings.

>
>
>
>
>
> > You're also not mentioning architectural limitations here, for instance that you
> > can only do this on arches that don't require VDSO relocation and listing
> > known-good arches.
> >
Sure, I will mention the architecture that has this enabled
(x86,arm,uml) -- I don't think there is an architecture limitation
though. mseal is a software feature. The reason why other
architectures don't have it is due to the fact that I don't have the
HW for testing



> > This is a documentation file, you can go wild :) the more information here the
> > better.
> >
> > WARNING
> > =======
> >
> > > +
> > >  When not to use mseal
> > >  =====================
> > >  Applications can apply sealing to any virtual memory region from userspace,
> > > --
> > > 2.48.1.601.g30ceb7b040-goog
> > >

Lorenzo Stoakes Feb. 26, 2025, 5:27 a.m. UTC | #8

On Tue, Feb 25, 2025 at 02:31:15PM -0800, Jeff Xu wrote:
> On Mon, Feb 24, 2025 at 10:07 PM Lorenzo Stoakes
> <[e-mail]> wrote:
> >
> > On Mon, Feb 24, 2025 at 05:45:13PM +0000, [e-mail] wrote:
> > > From: Jeff Xu <[e-mail]>
> > >
> > > Update memory sealing documentation to include details about system
> > > mappings.
> > >
> > > Signed-off-by: Jeff Xu <[e-mail]>
> > > ---
> > >  Documentation/userspace-api/mseal.rst | 7 +++++++
> > >  1 file changed, 7 insertions(+)
> > >
> > > diff --git a/Documentation/userspace-api/mseal.rst b/Documentation/userspace-api/mseal.rst
> > > index 41102f74c5e2..10147281bf2d 100644
> > > --- a/Documentation/userspace-api/mseal.rst
> > > +++ b/Documentation/userspace-api/mseal.rst
> > > @@ -130,6 +130,13 @@ Use cases
> > >
> > >  - Chrome browser: protect some security sensitive data structures.
> > >
> > > +- System mappings:
> > > +  If supported by an architecture (via CONFIG_ARCH_HAS_MSEAL_SYSTEM_MAPPINGS),
> > > +  the CONFIG_MSEAL_SYSTEM_MAPPINGS seals system mappings, e.g. vdso, vvar,
> > > +  uprobes, sigpage, vectors, etc. CHECKPOINT_RESTORE, UML, gVisor, rr are
> > > +  known to relocate or unmap system mapping, therefore this config can't be
> > > +  enabled universally.
> >
> > Thanks for adding this.
> >
> > Similar comments to the Kconfig update - you are listing features that do not
> > exist yet, please just list what you're doing, specifically, and avoid the vague
> > 'etc.', we don't need to be vague.
> >
> OK, I will remove etc and list the known mappings here.
>
> > As per the Kconfig comment - you need to be a lot more clear, I think you're
> > duplicating the text from there to here, so again I suggest something like:
> >
> > WARNING: This feature breaks programs which rely on relocating or
> >          unmapping system mappings.
> >
> >          Known broken software at the time of writing includes
> >          CHECKPOINT_RESTORE, UML, gVisor and rr.
> >
> Sure.
>
> > You also seem to be writing very little here, it's a documentation page, you can
> > be as verbose as you like :)
> >
> > You really need to add some more detail here in general - you aren't explaining
> > why people would want to enable this, what you're mitigating, etc. from that you
> > explain _why_ it doesn't work for some things.
> >
> The mseal.rst already includes below regarding the protection/mitigation.

Not for system sealing. Please add it even if you think it'd be
duplicative. Thanks.

>
>
>
>
>
> > You're also not mentioning architectural limitations here, for instance that you
> > can only do this on arches that don't require VDSO relocation and listing
> > known-good arches.
> >
> > This is a documentation file, you can go wild :) the more information here the
> > better.
> >
> > WARNING
> > =======
> >
> > > +
> > >  When not to use mseal
> > >  =====================
> > >  Applications can apply sealing to any virtual memory region from userspace,
> > > --
> > > 2.48.1.601.g30ceb7b040-goog
> > >

Lorenzo Stoakes Feb. 26, 2025, 6:08 a.m. UTC | #9

On Tue, Feb 25, 2025 at 02:36:52PM -0800, Jeff Xu wrote:
> On Tue, Feb 25, 2025 at 2:31 PM Jeff Xu <[e-mail]> wrote:
> >
> > On Mon, Feb 24, 2025 at 10:07 PM Lorenzo Stoakes
> > <[e-mail]> wrote:
> > >
> > > On Mon, Feb 24, 2025 at 05:45:13PM +0000, [e-mail] wrote:
> > > > From: Jeff Xu <[e-mail]>
> > > >
> > > > Update memory sealing documentation to include details about system
> > > > mappings.
> > > >
> > > > Signed-off-by: Jeff Xu <[e-mail]>
> > > > ---
> > > >  Documentation/userspace-api/mseal.rst | 7 +++++++
> > > >  1 file changed, 7 insertions(+)
> > > >
> > > > diff --git a/Documentation/userspace-api/mseal.rst b/Documentation/userspace-api/mseal.rst
> > > > index 41102f74c5e2..10147281bf2d 100644
> > > > --- a/Documentation/userspace-api/mseal.rst
> > > > +++ b/Documentation/userspace-api/mseal.rst
> > > > @@ -130,6 +130,13 @@ Use cases
> > > >
> > > >  - Chrome browser: protect some security sensitive data structures.
> > > >
> > > > +- System mappings:
> > > > +  If supported by an architecture (via CONFIG_ARCH_HAS_MSEAL_SYSTEM_MAPPINGS),
> > > > +  the CONFIG_MSEAL_SYSTEM_MAPPINGS seals system mappings, e.g. vdso, vvar,
> > > > +  uprobes, sigpage, vectors, etc. CHECKPOINT_RESTORE, UML, gVisor, rr are
> > > > +  known to relocate or unmap system mapping, therefore this config can't be
> > > > +  enabled universally.
> > >
> > > Thanks for adding this.
> > >
> > > Similar comments to the Kconfig update - you are listing features that do not
> > > exist yet, please just list what you're doing, specifically, and avoid the vague
> > > 'etc.', we don't need to be vague.
> > >
> > OK, I will remove etc and list the known mappings here.
> >
> > > As per the Kconfig comment - you need to be a lot more clear, I think you're
> > > duplicating the text from there to here, so again I suggest something like:
> > >
> > > WARNING: This feature breaks programs which rely on relocating or
> > >          unmapping system mappings.
> > >
> > >          Known broken software at the time of writing includes
> > >          CHECKPOINT_RESTORE, UML, gVisor and rr.
> > >
> > Sure.
> >
> > > You also seem to be writing very little here, it's a documentation page, you can
> > > be as verbose as you like :)
> > >
> > > You really need to add some more detail here in general - you aren't explaining
> > > why people would want to enable this, what you're mitigating, etc. from that you
> > > explain _why_ it doesn't work for some things.
> > >
>
> The mseal.rst already includes below regarding the protection/mitigation.

But not specifically why you'd want to do that for system mappings.

I guess you mean it's _implied_ that it would be sensible to do this for
system mappings and I suppose again I'm asking for emphasis on this

>
> Memory sealing additionally protects the mapping itself against
> modifications. This is useful to mitigate memory corruption issues where a
> corrupted pointer is passed to a memory management system. For example,
> such an attacker primitive can break control-flow integrity guarantees
> since read-only memory that is supposed to be trusted can become writable
> or .text pages can get remapped. Memory sealing can automatically be
> applied by the runtime loader to seal .text and .rodata pages and
> applications can additionally seal security critical data at runtime.

Right, this is exactly the kind of thing you need but obviously adjusted to
mention system mappings, and why they are especially problematic (again -at
risk of sounding like a security idiot here :) - I'm guessing sand box
breakout, rop, syscall, find a way to write, and un-sandboxed code now does
unexpected stuff).

>
> I could copy  some sections from cover-letter to here, specifically
> for special mappings.

yeah that'd be good, while the cover letter will be copied in automatically
by Andrew to the series, it's really nice to have it at a glance in docs
for users who go to docs.kernel.org etc.

>
> >
> >
> >
> >
> >
> > > You're also not mentioning architectural limitations here, for instance that you
> > > can only do this on arches that don't require VDSO relocation and listing
> > > known-good arches.
> > >
> Sure, I will mention the architecture that has this enabled
> (x86,arm,uml) -- I don't think there is an architecture limitation
> though. mseal is a software feature. The reason why other
> architectures don't have it is due to the fact that I don't have the
> HW for testing

Yeah I mean just list the arches that you've tested, more or less.

Thanks!

>
>
>
> > > This is a documentation file, you can go wild :) the more information here the
> > > better.
> > >
> > > WARNING
> > > =======
> > >
> > > > +
> > > >  When not to use mseal
> > > >  =====================
> > > >  Applications can apply sealing to any virtual memory region from userspace,
> > > > --
> > > > 2.48.1.601.g30ceb7b040-goog
> > > >

Patch

diff --git a/Documentation/userspace-api/mseal.rst b/Documentation/userspace-api/mseal.rst
index 41102f74c5e2..10147281bf2d 100644
--- a/Documentation/userspace-api/mseal.rst
+++ b/Documentation/userspace-api/mseal.rst
@@ -130,6 +130,13 @@  Use cases
 
 - Chrome browser: protect some security sensitive data structures.
 
+- System mappings:
+  If supported by an architecture (via CONFIG_ARCH_HAS_MSEAL_SYSTEM_MAPPINGS),
+  the CONFIG_MSEAL_SYSTEM_MAPPINGS seals system mappings, e.g. vdso, vvar,
+  uprobes, sigpage, vectors, etc. CHECKPOINT_RESTORE, UML, gVisor, rr are
+  known to relocate or unmap system mapping, therefore this config can't be
+  enabled universally.
+
 When not to use mseal
 =====================
 Applications can apply sealing to any virtual memory region from userspace,