[PATCH] man2: new page describing memfd_secret() system call

[PATCH] man2: new page describing memfd_secret() system call

[Mike Rapoport]

From: Mike Rapoport <rppt@linux.ibm.com>

Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
---
 man2/memfd_secret.2 | 176 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 176 insertions(+)
 create mode 100644 man2/memfd_secret.2

diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2
new file mode 100644
index 000000000..e4ecd3662
--- /dev/null
+++ b/man2/memfd_secret.2
@@ -0,0 +1,176 @@
+.\" Copyright (c) 2020, IBM Corporation.
+.\" Written by Mike Rapoport <rppt@linux.ibm.com>
+.\"
+.\" Based on memfd_create(2) man page
+.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
+.\" and Copyright (C) 2014 David Herrmann <dh.herrmann@gmail.com>
+.\"
+.\" %%%LICENSE_START(GPLv2+)
+.\"
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
+.\"
+.TH MEMFD_SECRET 2 2020-08-02 Linux "Linux Programmer's Manual"
+.SH NAME
+memfd_secret \- create an anonymous file to map secret memory regions
+.SH SYNOPSIS
+.nf
+.B #include <linux/secretmem.h>
+.PP
+.BI "int memfd_secret(unsigned long " flags ");"
+.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
+.SH DESCRIPTION
+.BR memfd_secret ()
+creates an anonymous file and returns a file descriptor that refers to it.
+The file can only be memory-mapped;
+the memory in such mapping
+will have stronger protection than usual memory mapped files,
+and so it can be used to store application secrets.
+Unlike a regular file, a file created with
+.BR memfd_secret ()
+lives in RAM and has a volatile backing storage.
+Once all references to the file are dropped, it is automatically released.
+The initial size of the file is set to 0.
+Following the call, the file size should be set using
+.BR ftruncate (2).
+.PP
+The memory areas obtained with
+.BR mmap (2)
+from the file descriptor are exclusive to the owning context.
+These areas are removed from the kernel page tables
+and only the page table of the process holding the file descriptor
+maps the corresponding physical memory.
+.PP
+The following values may be bitwise ORed in
+.IR flags
+to control the behavior of
+.BR memfd_secret (2):
+.TP
+.BR FD_CLOEXEC
+Set the close-on-exec flag on the new file descriptor.
+See the description of the
+.B O_CLOEXEC
+flag in
+.BR open (2)
+for reasons why this may be useful.
+.PP
+.TP
+.BR SECRETMEM_UNCACHED
+In addition to excluding memory areas from the kernel page tables,
+mark the memory mappings uncached in the page table of the owning process.
+Such mappings can be used to prevent speculative loads
+and cache-based side channels.
+This mode of
+.BR memfd_secret ()
+is not supported on all architectures.
+.PP
+See also NOTES below.
+.PP
+As its return value,
+.BR memfd_secret ()
+returns a new file descriptor that can be used to refer to an anonymous file.
+This file descriptor is opened for both reading and writing
+.RB ( O_RDWR )
+and
+.B O_LARGEFILE
+is set for the file descriptor.
+.PP
+With respect to
+.BR fork (2)
+and
+.BR execve (2),
+the usual semantics apply for the file descriptor created by
+.BR memfd_secret ().
+A copy of the file descriptor is inherited by the child produced by
+.BR fork (2)
+and refers to the same file.
+The file descriptor is preserved across
+.BR execve (2),
+unless the close-on-exec flag has been set.
+.PP
+The memory regions backed with
+.BR memfd_secret ()
+are locked in the same way as
+.BR mlock (2),
+however the implementation will not try to
+populate the whole range during the
+.BR mmap ()
+call.
+The amount of memory allowed for memory mappings
+of the file descriptor obeys the same rules as
+.BR mlock (2)
+and cannot exceed
+.B RLIMIT_MEMLOCK.
+.SH RETURN VALUE
+On success,
+.BR memfd_secret ()
+returns a new file descriptor.
+On error, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B ENOSYS
+.BR memfd_secret ()
+is not implemented on this architecture.
+.TP
+.B EINVAL
+.I flags
+included unknown bits.
+.TP
+.B EMFILE
+The per-process limit on the number of open file descriptors has been reached.
+.TP
+.B EMFILE
+The system-wide limit on the total number of open files has been reached.
+.TP
+.B ENOMEM
+There was insufficient memory to create a new anonymous file.
+.SH VERSIONS
+The
+.BR memfd_secret (2)
+system call first appeared in Linux 5.X;
+.SH CONFORMING TO
+The
+.BR memfd_secret (2)
+system call is Linux-specific.
+.SH NOTES
+The
+.BR memfd_secret (2)
+system call provides an ability to hide information
+from the operating system.
+Normally Linux userspace mappings are protected from other users,
+but they are visible to the privileged code.
+The mappings created using
+.BR memfd_secret ()
+are hidden from the kernel as well.
+.PP
+If an architecture supports
+.B SECRETMEM_UNCACHED,
+the mappings also have protection from speculative execution vulnerabilties,
+at the expense of increased memory access latency.
+Care should be taken when using
+.B
+SECRETMEM_UNCACHED
+to avoid degrading application performance.
+.SH SEE ALSO
+.BR fcntl (2),
+.BR ftruncate (2),
+.BR mlock (2),
+.BR mmap (2),
+.BR setrlimit (2),
-- 
2.25.4

Re: [PATCH] man2: new page describing memfd_secret() system call

[Alejandro Colomar]

* Mike Rapoport:
 > +.PP
 > +.IR Note :
 > +There is no glibc wrapper for this system call; see NOTES.

You added a reference to NOTES, but then in notes there is nothing about 
it.  I guess you wanted to add the following to NOTES (taken from 
membarrier.2):

.PP
Glibc does not provide a wrapper for this system call; call it using
.BR syscall (2).

Cheers,

Alex

Re: [PATCH] man2: new page describing memfd_secret() system call

[Alejandro Colomar]

Hi Mike and Michael,

Ping. :)

Thanks,

Alex

On 2020-09-24 16:55, Alejandro Colomar wrote:
> * Mike Rapoport:
>  > +.PP
>  > +.IR Note :
>  > +There is no glibc wrapper for this system call; see NOTES.
> 
> You added a reference to NOTES, but then in notes there is nothing about 
> it.  I guess you wanted to add the following to NOTES (taken from 
> membarrier.2):
> 
> .PP
> Glibc does not provide a wrapper for this system call; call it using
> .BR syscall (2).
> 
> Cheers,
> 
> Alex

Re: [PATCH] man2: new page describing memfd_secret() system call

[Mike Rapoport]

Hi Alex,

On Sat, Oct 03, 2020 at 11:32:43AM +0200, Alejandro Colomar wrote:
> Hi Mike and Michael,

I'll add the note to the man page, thanks!

> Ping. :)
> 
> Thanks,
> 
> Alex
> 
> On 2020-09-24 16:55, Alejandro Colomar wrote:
> > * Mike Rapoport:
> >  > +.PP
> >  > +.IR Note :
> >  > +There is no glibc wrapper for this system call; see NOTES.
> > 
> > You added a reference to NOTES, but then in notes there is nothing about
> > it.  I guess you wanted to add the following to NOTES (taken from
> > membarrier.2):
> > 
> > .PP
> > Glibc does not provide a wrapper for this system call; call it using
> > .BR syscall (2).
> > 
> > Cheers,
> > 
> > Alex

-- 
Sincerely yours,
Mike.

[PATCH v2] memfd_secret.2: New page describing memfd_secret() system call

[Alejandro Colomar]

From: Mike Rapoport <rppt@linux.ibm.com>

Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
Acked-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---

Hi Mike,

I added that note about not having a wrapper,
fixed a few minor formatting and wording issues,
and sorted ERRORS alphabetically.

Cheers,

Alex

 man2/memfd_secret.2 | 178 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 178 insertions(+)
 create mode 100644 man2/memfd_secret.2

diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2
new file mode 100644
index 000000000..4e617aa0e
--- /dev/null
+++ b/man2/memfd_secret.2
@@ -0,0 +1,178 @@
+.\" Copyright (c) 2020, IBM Corporation.
+.\" Written by Mike Rapoport <rppt@linux.ibm.com>
+.\"
+.\" Based on memfd_create(2) man page
+.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
+.\" and Copyright (C) 2014 David Herrmann <dh.herrmann@gmail.com>
+.\"
+.\" %%%LICENSE_START(GPLv2+)
+.\"
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
+.\"
+.TH MEMFD_SECRET 2 2020-08-02 Linux "Linux Programmer's Manual"
+.SH NAME
+memfd_secret \- create an anonymous file to map secret memory regions
+.SH SYNOPSIS
+.nf
+.B #include <linux/secretmem.h>
+.PP
+.BI "int memfd_secret(unsigned long " flags ");"
+.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
+.SH DESCRIPTION
+.BR memfd_secret ()
+creates an anonymous file and returns a file descriptor that refers to it.
+The file can only be memory-mapped;
+the memory in such mapping
+will have stronger protection than usual memory mapped files,
+and so it can be used to store application secrets.
+Unlike a regular file, a file created with
+.BR memfd_secret ()
+lives in RAM and has a volatile backing storage.
+Once all references to the file are dropped, it is automatically released.
+The initial size of the file is set to 0.
+Following the call, the file size should be set using
+.BR ftruncate (2).
+.PP
+The memory areas obtained with
+.BR mmap (2)
+from the file descriptor are exclusive to the owning context.
+These areas are removed from the kernel page tables
+and only the page table of the process holding the file descriptor
+maps the corresponding physical memory.
+.PP
+The following values may be bitwise ORed in
+.IR flags
+to control the behavior of
+.BR memfd_secret (2):
+.TP
+.BR FD_CLOEXEC
+Set the close-on-exec flag on the new file descriptor.
+See the description of the
+.B O_CLOEXEC
+flag in
+.BR open (2)
+for reasons why this may be useful.
+.PP
+.TP
+.BR SECRETMEM_UNCACHED
+In addition to excluding memory areas from the kernel page tables,
+mark the memory mappings uncached in the page table of the owning process.
+Such mappings can be used to prevent speculative loads
+and cache-based side channels.
+This mode of
+.BR memfd_secret ()
+is not supported on all architectures.
+.PP
+See also NOTES below.
+.PP
+As its return value,
+.BR memfd_secret ()
+returns a new file descriptor that can be used to refer to an anonymous file.
+This file descriptor is opened for both reading and writing
+.RB ( O_RDWR )
+and
+.B O_LARGEFILE
+is set for the file descriptor.
+.PP
+With respect to
+.BR fork (2)
+and
+.BR execve (2),
+the usual semantics apply for the file descriptor created by
+.BR memfd_secret ().
+A copy of the file descriptor is inherited by the child produced by
+.BR fork (2)
+and refers to the same file.
+The file descriptor is preserved across
+.BR execve (2),
+unless the close-on-exec flag has been set.
+.PP
+The memory regions backed with
+.BR memfd_secret ()
+are locked in the same way as
+.BR mlock (2),
+however the implementation will not try to
+populate the whole range during the
+.BR mmap ()
+call.
+The amount of memory allowed for memory mappings
+of the file descriptor obeys the same rules as
+.BR mlock (2)
+and cannot exceed
+.BR RLIMIT_MEMLOCK .
+.SH RETURN VALUE
+On success,
+.BR memfd_secret ()
+returns a new file descriptor.
+On error, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+.I flags
+included unknown bits.
+.TP
+.B EMFILE
+The per-process limit on the number of open file descriptors has been reached.
+.TP
+.B EMFILE
+The system-wide limit on the total number of open files has been reached.
+.TP
+.B ENOMEM
+There was insufficient memory to create a new anonymous file.
+.TP
+.B ENOSYS
+.BR memfd_secret ()
+is not implemented on this architecture.
+.SH VERSIONS
+The
+.BR memfd_secret (2)
+system call first appeared in Linux 5.X;
+.SH CONFORMING TO
+The
+.BR memfd_secret (2)
+system call is Linux-specific.
+.SH NOTES
+The
+.BR memfd_secret (2)
+system call provides an ability to hide information
+from the operating system.
+Normally Linux userspace mappings are protected from other users,
+but they are visible to privileged code.
+The mappings created using
+.BR memfd_secret ()
+are hidden from the kernel as well.
+.PP
+If an architecture supports
+.BR SECRETMEM_UNCACHED ,
+the mappings also have protection from speculative execution vulnerabilties,
+at the expense of increased memory access latency.
+Care should be taken when using
+.B SECRETMEM_UNCACHED
+to avoid degrading application performance.
+.PP
+Glibc does not provide a wrapper for this system call; call it using
+.BR syscall (2).
+.SH SEE ALSO
+.BR fcntl (2),
+.BR ftruncate (2),
+.BR mlock (2),
+.BR mmap (2),
+.BR setrlimit (2)
-- 
2.29.2

Re: [PATCH v2] memfd_secret.2: New page describing memfd_secret() system call

[Mike Rapoport]

On Mon, Nov 16, 2020 at 10:01:37PM +0100, Alejandro Colomar wrote:
> From: Mike Rapoport <rppt@linux.ibm.com>
> 
> Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
> Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
> Acked-by: Alejandro Colomar <alx.manpages@gmail.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
> 
> Hi Mike,
> 
> I added that note about not having a wrapper,
> fixed a few minor formatting and wording issues,
> and sorted ERRORS alphabetically.

Thanks, Alejandro!

> Cheers,
> 
> Alex
> 
>  man2/memfd_secret.2 | 178 ++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 178 insertions(+)
>  create mode 100644 man2/memfd_secret.2
> 
> diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2
> new file mode 100644
> index 000000000..4e617aa0e
> --- /dev/null
> +++ b/man2/memfd_secret.2
> @@ -0,0 +1,178 @@
> +.\" Copyright (c) 2020, IBM Corporation.
> +.\" Written by Mike Rapoport <rppt@linux.ibm.com>
> +.\"
> +.\" Based on memfd_create(2) man page
> +.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
> +.\" and Copyright (C) 2014 David Herrmann <dh.herrmann@gmail.com>
> +.\"
> +.\" %%%LICENSE_START(GPLv2+)
> +.\"
> +.\" This program is free software; you can redistribute it and/or modify
> +.\" it under the terms of the GNU General Public License as published by
> +.\" the Free Software Foundation; either version 2 of the License, or
> +.\" (at your option) any later version.
> +.\"
> +.\" This program is distributed in the hope that it will be useful,
> +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
> +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> +.\" GNU General Public License for more details.
> +.\"
> +.\" You should have received a copy of the GNU General Public
> +.\" License along with this manual; if not, see
> +.\" <http://www.gnu.org/licenses/>.
> +.\" %%%LICENSE_END
> +.\"
> +.TH MEMFD_SECRET 2 2020-08-02 Linux "Linux Programmer's Manual"
> +.SH NAME
> +memfd_secret \- create an anonymous file to map secret memory regions
> +.SH SYNOPSIS
> +.nf
> +.B #include <linux/secretmem.h>
> +.PP
> +.BI "int memfd_secret(unsigned long " flags ");"
> +.fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> +.SH DESCRIPTION
> +.BR memfd_secret ()
> +creates an anonymous file and returns a file descriptor that refers to it.
> +The file can only be memory-mapped;
> +the memory in such mapping
> +will have stronger protection than usual memory mapped files,
> +and so it can be used to store application secrets.
> +Unlike a regular file, a file created with
> +.BR memfd_secret ()
> +lives in RAM and has a volatile backing storage.
> +Once all references to the file are dropped, it is automatically released.
> +The initial size of the file is set to 0.
> +Following the call, the file size should be set using
> +.BR ftruncate (2).
> +.PP
> +The memory areas obtained with
> +.BR mmap (2)
> +from the file descriptor are exclusive to the owning context.
> +These areas are removed from the kernel page tables
> +and only the page table of the process holding the file descriptor
> +maps the corresponding physical memory.
> +.PP
> +The following values may be bitwise ORed in
> +.IR flags
> +to control the behavior of
> +.BR memfd_secret (2):
> +.TP
> +.BR FD_CLOEXEC
> +Set the close-on-exec flag on the new file descriptor.
> +See the description of the
> +.B O_CLOEXEC
> +flag in
> +.BR open (2)
> +for reasons why this may be useful.
> +.PP
> +.TP
> +.BR SECRETMEM_UNCACHED
> +In addition to excluding memory areas from the kernel page tables,
> +mark the memory mappings uncached in the page table of the owning process.
> +Such mappings can be used to prevent speculative loads
> +and cache-based side channels.
> +This mode of
> +.BR memfd_secret ()
> +is not supported on all architectures.
> +.PP
> +See also NOTES below.
> +.PP
> +As its return value,
> +.BR memfd_secret ()
> +returns a new file descriptor that can be used to refer to an anonymous file.
> +This file descriptor is opened for both reading and writing
> +.RB ( O_RDWR )
> +and
> +.B O_LARGEFILE
> +is set for the file descriptor.
> +.PP
> +With respect to
> +.BR fork (2)
> +and
> +.BR execve (2),
> +the usual semantics apply for the file descriptor created by
> +.BR memfd_secret ().
> +A copy of the file descriptor is inherited by the child produced by
> +.BR fork (2)
> +and refers to the same file.
> +The file descriptor is preserved across
> +.BR execve (2),
> +unless the close-on-exec flag has been set.
> +.PP
> +The memory regions backed with
> +.BR memfd_secret ()
> +are locked in the same way as
> +.BR mlock (2),
> +however the implementation will not try to
> +populate the whole range during the
> +.BR mmap ()
> +call.
> +The amount of memory allowed for memory mappings
> +of the file descriptor obeys the same rules as
> +.BR mlock (2)
> +and cannot exceed
> +.BR RLIMIT_MEMLOCK .
> +.SH RETURN VALUE
> +On success,
> +.BR memfd_secret ()
> +returns a new file descriptor.
> +On error, \-1 is returned and
> +.I errno
> +is set to indicate the error.
> +.SH ERRORS
> +.TP
> +.B EINVAL
> +.I flags
> +included unknown bits.
> +.TP
> +.B EMFILE
> +The per-process limit on the number of open file descriptors has been reached.
> +.TP
> +.B EMFILE
> +The system-wide limit on the total number of open files has been reached.
> +.TP
> +.B ENOMEM
> +There was insufficient memory to create a new anonymous file.
> +.TP
> +.B ENOSYS
> +.BR memfd_secret ()
> +is not implemented on this architecture.
> +.SH VERSIONS
> +The
> +.BR memfd_secret (2)
> +system call first appeared in Linux 5.X;
> +.SH CONFORMING TO
> +The
> +.BR memfd_secret (2)
> +system call is Linux-specific.
> +.SH NOTES
> +The
> +.BR memfd_secret (2)
> +system call provides an ability to hide information
> +from the operating system.
> +Normally Linux userspace mappings are protected from other users,
> +but they are visible to privileged code.
> +The mappings created using
> +.BR memfd_secret ()
> +are hidden from the kernel as well.
> +.PP
> +If an architecture supports
> +.BR SECRETMEM_UNCACHED ,
> +the mappings also have protection from speculative execution vulnerabilties,
> +at the expense of increased memory access latency.
> +Care should be taken when using
> +.B SECRETMEM_UNCACHED
> +to avoid degrading application performance.
> +.PP
> +Glibc does not provide a wrapper for this system call; call it using
> +.BR syscall (2).
> +.SH SEE ALSO
> +.BR fcntl (2),
> +.BR ftruncate (2),
> +.BR mlock (2),
> +.BR mmap (2),
> +.BR setrlimit (2)
> -- 
> 2.29.2
> 

-- 
Sincerely yours,
Mike.

Re: [PATCH v2] memfd_secret.2: New page describing memfd_secret() system call

[Alejandro Colomar (man-pages)]

[[ I'm having trouble with gmail and many CCs lately ]]

Hi Mike,

I was reviewing the patch, and have a few questions.
See below.

Thanks,

Alex

On 11/17/20 7:26 AM, Mike Rapoport wrote:
> On Mon, Nov 16, 2020 at 10:01:37PM +0100, Alejandro Colomar wrote:
>> From: Mike Rapoport <rppt@linux.ibm.com>
>>
>> Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
>> Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
>> Acked-by: Alejandro Colomar <alx.manpages@gmail.com>
>> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
>> ---
>>
>> Hi Mike,
>>
>> I added that note about not having a wrapper,
>> fixed a few minor formatting and wording issues,
>> and sorted ERRORS alphabetically.
>
> Thanks, Alejandro!
>
>> Cheers,
>>
>> Alex
>>
>>  man2/memfd_secret.2 | 178 ++++++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 178 insertions(+)
>>  create mode 100644 man2/memfd_secret.2
>>
>> diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2
>> new file mode 100644
>> index 000000000..4e617aa0e
>> --- /dev/null
>> +++ b/man2/memfd_secret.2
>> @@ -0,0 +1,178 @@
>> +.\" Copyright (c) 2020, IBM Corporation.
>> +.\" Written by Mike Rapoport <rppt@linux.ibm.com>
>> +.\"
>> +.\" Based on memfd_create(2) man page
>> +.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
>> +.\" and Copyright (C) 2014 David Herrmann <dh.herrmann@gmail.com>
>> +.\"
>> +.\" %%%LICENSE_START(GPLv2+)
>> +.\"
>> +.\" This program is free software; you can redistribute it and/or modify
>> +.\" it under the terms of the GNU General Public License as published by
>> +.\" the Free Software Foundation; either version 2 of the License, or
>> +.\" (at your option) any later version.
>> +.\"
>> +.\" This program is distributed in the hope that it will be useful,
>> +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
>> +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
>> +.\" GNU General Public License for more details.
>> +.\"
>> +.\" You should have received a copy of the GNU General Public
>> +.\" License along with this manual; if not, see
>> +.\" <http://www.gnu.org/licenses/>.
>> +.\" %%%LICENSE_END
>> +.\"
>> +.TH MEMFD_SECRET 2 2020-08-02 Linux "Linux Programmer's Manual"
>> +.SH NAME
>> +memfd_secret \- create an anonymous file to map secret memory regions
>> +.SH SYNOPSIS
>> +.nf
>> +.B #include <linux/secretmem.h>
>> +.PP
>> +.BI "int memfd_secret(unsigned long " flags ");"
>> +.fi
>> +.PP
>> +.IR Note :
>> +There is no glibc wrapper for this system call; see NOTES.
>> +.SH DESCRIPTION
>> +.BR memfd_secret ()
>> +creates an anonymous file and returns a file descriptor that refers
to it.
>> +The file can only be memory-mapped;
>> +the memory in such mapping
>> +will have stronger protection than usual memory mapped files,
>> +and so it can be used to store application secrets.
>> +Unlike a regular file, a file created with
>> +.BR memfd_secret ()
>> +lives in RAM and has a volatile backing storage.

By 'volatile' do you mean as in the keyword?
If so, maybe we should use [.I volatile].

>> +Once all references to the file are dropped, it is automatically
released.
>> +The initial size of the file is set to 0.
>> +Following the call, the file size should be set using
>> +.BR ftruncate (2).
>> +.PP
>> +The memory areas obtained with
>> +.BR mmap (2)
>> +from the file descriptor are exclusive to the owning context.
>> +These areas are removed from the kernel page tables
>> +and only the page table of the process holding the file descriptor
>> +maps the corresponding physical memory.
>> +.PP
>> +The following values may be bitwise ORed in
>> +.IR flags
>> +to control the behavior of
>> +.BR memfd_secret (2):
>> +.TP
>> +.BR FD_CLOEXEC
>> +Set the close-on-exec flag on the new file descriptor.
>> +See the description of the
>> +.B O_CLOEXEC
>> +flag in
>> +.BR open (2)
>> +for reasons why this may be useful.
>> +.PP
>> +.TP
>> +.BR SECRETMEM_UNCACHED
>> +In addition to excluding memory areas from the kernel page tables,
>> +mark the memory mappings uncached in the page table of the owning
process.
>> +Such mappings can be used to prevent speculative loads
>> +and cache-based side channels.
>> +This mode of
>> +.BR memfd_secret ()
>> +is not supported on all architectures.
>> +.PP
>> +See also NOTES below.

Is this paragraph correctly indented?
It seems like it's a continuation of SECRETMEM_UNCACHED,
in which case it should use: s/.PP/.IP/

>> +.PP
>> +As its return value,
>> +.BR memfd_secret ()
>> +returns a new file descriptor that can be used to refer to an
anonymous file.
>> +This file descriptor is opened for both reading and writing
>> +.RB ( O_RDWR )
>> +and
>> +.B O_LARGEFILE
>> +is set for the file descriptor.
>> +.PP
>> +With respect to
>> +.BR fork (2)
>> +and
>> +.BR execve (2),
>> +the usual semantics apply for the file descriptor created by
>> +.BR memfd_secret ().
>> +A copy of the file descriptor is inherited by the child produced by
>> +.BR fork (2)
>> +and refers to the same file.
>> +The file descriptor is preserved across
>> +.BR execve (2),
>> +unless the close-on-exec flag has been set.
>> +.PP
>> +The memory regions backed with
>> +.BR memfd_secret ()
>> +are locked in the same way as
>> +.BR mlock (2),
>> +however the implementation will not try to
>> +populate the whole range during the
>> +.BR mmap ()

s/mmap ()/mmap (2)/

>> +call.
>> +The amount of memory allowed for memory mappings
>> +of the file descriptor obeys the same rules as
>> +.BR mlock (2)
>> +and cannot exceed
>> +.BR RLIMIT_MEMLOCK .
>> +.SH RETURN VALUE
>> +On success,
>> +.BR memfd_secret ()
>> +returns a new file descriptor.
>> +On error, \-1 is returned and
>> +.I errno
>> +is set to indicate the error.
>> +.SH ERRORS
>> +.TP
>> +.B EINVAL
>> +.I flags
>> +included unknown bits.
>> +.TP
>> +.B EMFILE
>> +The per-process limit on the number of open file descriptors has
been reached.
>> +.TP
>> +.B EMFILE
>> +The system-wide limit on the total number of open files has been
reached.
>> +.TP
>> +.B ENOMEM
>> +There was insufficient memory to create a new anonymous file.
>> +.TP
>> +.B ENOSYS
>> +.BR memfd_secret ()
>> +is not implemented on this architecture.
>> +.SH VERSIONS
>> +The
>> +.BR memfd_secret (2)
>> +system call first appeared in Linux 5.X;

Was it added in Linux 5.10?
If so, could you add the commit number in a comment in the next line?

>> +.SH CONFORMING TO
>> +The
>> +.BR memfd_secret (2)
>> +system call is Linux-specific.
>> +.SH NOTES
>> +The
>> +.BR memfd_secret (2)
>> +system call provides an ability to hide information
>> +from the operating system.
>> +Normally Linux userspace mappings are protected from other users,
>> +but they are visible to privileged code.
>> +The mappings created using
>> +.BR memfd_secret ()
>> +are hidden from the kernel as well.
>> +.PP
>> +If an architecture supports
>> +.BR SECRETMEM_UNCACHED ,
>> +the mappings also have protection from speculative execution
vulnerabilties,
>> +at the expense of increased memory access latency.
>> +Care should be taken when using
>> +.B SECRETMEM_UNCACHED
>> +to avoid degrading application performance.
>> +.PP
>> +Glibc does not provide a wrapper for this system call; call it using
>> +.BR syscall (2).
>> +.SH SEE ALSO
>> +.BR fcntl (2),
>> +.BR ftruncate (2),
>> +.BR mlock (2),
>> +.BR mmap (2),
>> +.BR setrlimit (2)
>> --
>> 2.29.2
>>
>

Re: [PATCH v2] memfd_secret.2: New page describing memfd_secret() system call

[Mike Rapoport]

Hi Alejandro,

On Sat, Nov 21, 2020 at 10:46:46PM +0100, Alejandro Colomar (man-pages) wrote:
> [[ I'm having trouble with gmail and many CCs lately ]]
> 
> Hi Mike,
> 
> I was reviewing the patch, and have a few questions.
> See below.
> 
> Thanks,
> 
> Alex
> 
> On 11/17/20 7:26 AM, Mike Rapoport wrote:
> > On Mon, Nov 16, 2020 at 10:01:37PM +0100, Alejandro Colomar wrote:
> >> From: Mike Rapoport <rppt@linux.ibm.com>
> >>
> >> Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
> >> Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
> >> Acked-by: Alejandro Colomar <alx.manpages@gmail.com>
> >> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> >> ---
> >>
> >> Hi Mike,
> >>
> >> I added that note about not having a wrapper,
> >> fixed a few minor formatting and wording issues,
> >> and sorted ERRORS alphabetically.
> >
> > Thanks, Alejandro!
> >
> >> Cheers,
> >>
> >> Alex
> >>
> >>  man2/memfd_secret.2 | 178 ++++++++++++++++++++++++++++++++++++++++++++
> >>  1 file changed, 178 insertions(+)
> >>  create mode 100644 man2/memfd_secret.2
> >>
> >> diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2
> >> new file mode 100644
> >> index 000000000..4e617aa0e
> >> --- /dev/null
> >> +++ b/man2/memfd_secret.2
> >> @@ -0,0 +1,178 @@

...

> >> +.BR memfd_secret ()
> >> +creates an anonymous file and returns a file descriptor that refers
> to it.
> >> +The file can only be memory-mapped;
> >> +the memory in such mapping
> >> +will have stronger protection than usual memory mapped files,
> >> +and so it can be used to store application secrets.
> >> +Unlike a regular file, a file created with
> >> +.BR memfd_secret ()
> >> +lives in RAM and has a volatile backing storage.
> 
> By 'volatile' do you mean as in the keyword?
> If so, maybe we should use [.I volatile].

I don't think the keyword is actually related here. It's more like
volatile in NVRAM :)

> >> +Once all references to the file are dropped, it is automatically
> released.

...

> >> +.BR SECRETMEM_UNCACHED
> >> +In addition to excluding memory areas from the kernel page tables,
> >> +mark the memory mappings uncached in the page table of the owning
> process.
> >> +Such mappings can be used to prevent speculative loads
> >> +and cache-based side channels.
> >> +This mode of
> >> +.BR memfd_secret ()
> >> +is not supported on all architectures.
> >> +.PP
> >> +See also NOTES below.
> 
> Is this paragraph correctly indented?
> It seems like it's a continuation of SECRETMEM_UNCACHED,
> in which case it should use: s/.PP/.IP/

You are right, it should be idented as SECRETMEM_UNCACHED.

> >> +.PP
> >> +As its return value,
> >> +.BR memfd_secret ()
> >> +returns a new file descriptor that can be used to refer to an
> anonymous file.
> >> +This file descriptor is opened for both reading and writing
> >> +.RB ( O_RDWR )
> >> +and
> >> +.B O_LARGEFILE
> >> +is set for the file descriptor.
> >> +.PP
> >> +With respect to
> >> +.BR fork (2)
> >> +and
> >> +.BR execve (2),
> >> +the usual semantics apply for the file descriptor created by
> >> +.BR memfd_secret ().
> >> +A copy of the file descriptor is inherited by the child produced by
> >> +.BR fork (2)
> >> +and refers to the same file.
> >> +The file descriptor is preserved across
> >> +.BR execve (2),
> >> +unless the close-on-exec flag has been set.
> >> +.PP
> >> +The memory regions backed with
> >> +.BR memfd_secret ()
> >> +are locked in the same way as
> >> +.BR mlock (2),
> >> +however the implementation will not try to
> >> +populate the whole range during the
> >> +.BR mmap ()
> 
> s/mmap ()/mmap (2)/

Fixed

> >> +call.
> >> +The amount of memory allowed for memory mappings
> >> +of the file descriptor obeys the same rules as

...

> >> +.SH VERSIONS
> >> +The
> >> +.BR memfd_secret (2)
> >> +system call first appeared in Linux 5.X;
> 
> Was it added in Linux 5.10?
> If so, could you add the commit number in a comment in the next line?

It was not added to 5.10 and it is still only made it up to mmotm tree
but not the mainline.
I'm planning to do another respin of the man page once the code is
actually merged into the Linus tree.

-- 
Sincerely yours,
Mike.

Re: [PATCH] man2: new page describing memfd_secret() system call

[Alejandro Colomar (man-pages)]

Hi Mike,

On 7/27/21 2:41 PM, Mike Rapoport wrote:
> From: Mike Rapoport <rppt@linux.ibm.com>
> 
> Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
> ---
> 
> Hi,
> 
> There were a lot of changes to memfd_secret implementation since the
> previous posting of this man page, so its contents also changed
> significantly and there is not much sense to call it v2.

Please see some minor comments below.
Other than that, the page looks good to me.

Thanks,

Alex

> 
>   man2/memfd_secret.2 | 143 ++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 143 insertions(+)
>   create mode 100644 man2/memfd_secret.2
> 
> diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2
> new file mode 100644
> index 000000000..e6eee7018
> --- /dev/null
> +++ b/man2/memfd_secret.2
> @@ -0,0 +1,143 @@
> +.\" Copyright (c) 2021, IBM Corporation.
> +.\" Written by Mike Rapoport <rppt@linux.ibm.com>
> +.\"
> +.\" Based on memfd_create(2) man page
> +.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
> +.\" and Copyright (C) 2014 David Herrmann <dh.herrmann@gmail.com>
> +.\"
> +.\" %%%LICENSE_START(GPLv2+)
> +.\"
> +.\" This program is free software; you can redistribute it and/or modify
> +.\" it under the terms of the GNU General Public License as published by
> +.\" the Free Software Foundation; either version 2 of the License, or
> +.\" (at your option) any later version.
> +.\"
> +.\" This program is distributed in the hope that it will be useful,
> +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
> +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> +.\" GNU General Public License for more details.
> +.\"
> +.\" You should have received a copy of the GNU General Public
> +.\" License along with this manual; if not, see
> +.\" <http://www.gnu.org/licenses/>.
> +.\" %%%LICENSE_END
> +.\"
> +.TH MEMFD_SECRET 2 2020-08-02 Linux "Linux Programmer's Manual"
> +.SH NAME
> +memfd_secret \- create an anonymous file to access secret memory regions
> +.SH SYNOPSIS
> +.nf
> +.BI "int memfd_secret(unsigned int " flags ");"
> +.fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.

Please see the new syntax we're using for syscalls without a wrapper. 
You can check for example membarrier(2):
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man2/membarrier.2>

Also please make sure you provide a complete include list for normal 
usage of the syscall (that is, includes providing syscall(2), 
SYS_memfd_secret, and any other constants used by the syscall).

> +.SH DESCRIPTION
> +.BR memfd_secret ()
> +creates an anonymous file and returns a file descriptor that refers to it.
> +The file provides a way to create and access memory regions
> +with stronger protection than usual RAM-based files and
> +anonymous memory mappings.
> +Once all references to the file are dropped, it is automatically released.
> +The initial size of the file is set to 0.
> +Following the call, the file size should be set using
> +.BR ftruncate (2).
> +.PP
> +The memory areas backing the file created with
> +.BR memfd_create(2)
> +are visible only to the contexts that have access to the file descriptor.
> +These areas are removed from the kernel page tables
> +and only the page tables of the processes holding the file descriptor
> +map the corresponding physical memory.
> +.PP
> +The following values may be bitwise ORed in
> +.IR flags

s/.IR/.I/

> +to control the behavior of
> +.BR memfd_secret (2):
> +.TP
> +.BR FD_CLOEXEC

s/.BR/.B/

> +Set the close-on-exec flag on the new file descriptor.
> +See the description of the
> +.B O_CLOEXEC
> +flag in
> +.BR open (2)
> +for reasons why this may be useful.
> +.PP
> +As its return value,
> +.BR memfd_secret ()
> +returns a new file descriptor that can be used to refer to an anonymous file.
> +This file descriptor is opened for both reading and writing
> +.RB ( O_RDWR )
> +and
> +.B O_LARGEFILE
> +is set for the file descriptor.
> +.PP
> +With respect to
> +.BR fork (2)
> +and
> +.BR execve (2),
> +the usual semantics apply for the file descriptor created by
> +.BR memfd_secret ().
> +A copy of the file descriptor is inherited by the child produced by
> +.BR fork (2)
> +and refers to the same file.
> +The file descriptor is preserved across
> +.BR execve (2),
> +unless the close-on-exec flag has been set.
> +.PP
> +The memory regions backed with
> +.BR memfd_secret ()
> +are locked in the same way as
> +.BR mlock (2),
> +however the implementation will not try to
> +populate the whole range during the
> +.BR mmap (2)
> +call.
> +The amount of memory allowed for memory mappings
> +of the file descriptor obeys the same rules as
> +.BR mlock (2)
> +and cannot exceed
> +.BR RLIMIT_MEMLOCK .
> +.SH RETURN VALUE
> +On success,
> +.BR memfd_secret ()
> +returns a new file descriptor.
> +On error, \-1 is returned and
> +.I errno
> +is set to indicate the error.
> +.SH ERRORS
> +.TP
> +.B EINVAL
> +.I flags
> +included unknown bits.
> +.TP
> +.B EMFILE
> +The per-process limit on the number of open file descriptors has been reached.
> +.TP
> +.B EMFILE
> +The system-wide limit on the total number of open files has been reached.
> +.TP
> +.B ENOMEM
> +There was insufficient memory to create a new anonymous file.
> +.TP
> +.B ENOSYS
> +.BR memfd_secret ()
> +is not implemented on this architecture.
> +.SH VERSIONS
> +The
> +.BR memfd_secret (2)
> +system call first appeared in Linux 5.14.
> +.SH CONFORMING TO
> +The
> +.BR memfd_secret (2)
> +system call is Linux-specific.
> +.SH NOTES
> +.PP
> +Glibc does not provide a wrapper for this system call; call it using
> +.BR syscall (2).

We removed these notes when we changed the syntax in the synopsis.
See commit 39df5bd6bc66eccd25fdfac4e9c3381219c6686f (man-pages) as an 
example.

> +.SH SEE ALSO
> +.BR fcntl (2),
> +.BR ftruncate (2),
> +.BR mlock (2),
> +.BR mmap (2),
> +.BR setrlimit (2)
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

[PATCH] man2: new page describing memfd_secret() system call

[Mike Rapoport]

From: Mike Rapoport <rppt@linux.ibm.com>

Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
---

Hi,

There were a lot of changes to memfd_secret implementation since the
previous posting of this man page, so its contents also changed
significantly and there is not much sense to call it v2.

 man2/memfd_secret.2 | 143 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 143 insertions(+)
 create mode 100644 man2/memfd_secret.2

diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2
new file mode 100644
index 000000000..e6eee7018
--- /dev/null
+++ b/man2/memfd_secret.2
@@ -0,0 +1,143 @@
+.\" Copyright (c) 2021, IBM Corporation.
+.\" Written by Mike Rapoport <rppt@linux.ibm.com>
+.\"
+.\" Based on memfd_create(2) man page
+.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
+.\" and Copyright (C) 2014 David Herrmann <dh.herrmann@gmail.com>
+.\"
+.\" %%%LICENSE_START(GPLv2+)
+.\"
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
+.\"
+.TH MEMFD_SECRET 2 2020-08-02 Linux "Linux Programmer's Manual"
+.SH NAME
+memfd_secret \- create an anonymous file to access secret memory regions
+.SH SYNOPSIS
+.nf
+.BI "int memfd_secret(unsigned int " flags ");"
+.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
+.SH DESCRIPTION
+.BR memfd_secret ()
+creates an anonymous file and returns a file descriptor that refers to it.
+The file provides a way to create and access memory regions
+with stronger protection than usual RAM-based files and
+anonymous memory mappings.
+Once all references to the file are dropped, it is automatically released.
+The initial size of the file is set to 0.
+Following the call, the file size should be set using
+.BR ftruncate (2).
+.PP
+The memory areas backing the file created with
+.BR memfd_create(2)
+are visible only to the contexts that have access to the file descriptor.
+These areas are removed from the kernel page tables
+and only the page tables of the processes holding the file descriptor
+map the corresponding physical memory.
+.PP
+The following values may be bitwise ORed in
+.IR flags
+to control the behavior of
+.BR memfd_secret (2):
+.TP
+.BR FD_CLOEXEC
+Set the close-on-exec flag on the new file descriptor.
+See the description of the
+.B O_CLOEXEC
+flag in
+.BR open (2)
+for reasons why this may be useful.
+.PP
+As its return value,
+.BR memfd_secret ()
+returns a new file descriptor that can be used to refer to an anonymous file.
+This file descriptor is opened for both reading and writing
+.RB ( O_RDWR )
+and
+.B O_LARGEFILE
+is set for the file descriptor.
+.PP
+With respect to
+.BR fork (2)
+and
+.BR execve (2),
+the usual semantics apply for the file descriptor created by
+.BR memfd_secret ().
+A copy of the file descriptor is inherited by the child produced by
+.BR fork (2)
+and refers to the same file.
+The file descriptor is preserved across
+.BR execve (2),
+unless the close-on-exec flag has been set.
+.PP
+The memory regions backed with
+.BR memfd_secret ()
+are locked in the same way as
+.BR mlock (2),
+however the implementation will not try to
+populate the whole range during the
+.BR mmap (2)
+call.
+The amount of memory allowed for memory mappings
+of the file descriptor obeys the same rules as
+.BR mlock (2)
+and cannot exceed
+.BR RLIMIT_MEMLOCK .
+.SH RETURN VALUE
+On success,
+.BR memfd_secret ()
+returns a new file descriptor.
+On error, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+.I flags
+included unknown bits.
+.TP
+.B EMFILE
+The per-process limit on the number of open file descriptors has been reached.
+.TP
+.B EMFILE
+The system-wide limit on the total number of open files has been reached.
+.TP
+.B ENOMEM
+There was insufficient memory to create a new anonymous file.
+.TP
+.B ENOSYS
+.BR memfd_secret ()
+is not implemented on this architecture.
+.SH VERSIONS
+The
+.BR memfd_secret (2)
+system call first appeared in Linux 5.14.
+.SH CONFORMING TO
+The
+.BR memfd_secret (2)
+system call is Linux-specific.
+.SH NOTES
+.PP
+Glibc does not provide a wrapper for this system call; call it using
+.BR syscall (2).
+.SH SEE ALSO
+.BR fcntl (2),
+.BR ftruncate (2),
+.BR mlock (2),
+.BR mmap (2),
+.BR setrlimit (2)
-- 
2.31.1