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

[Mike Rapoport <rppt@linux.ibm.com>]

On Mon, Aug 16, 2021 at 02:29:33AM +0200, Michael Kerrisk (man-pages) wrote:
> Hi Mike,
> 
> Thanks for this update!
> 
> On 8/15/21 8:46 AM, Mike Rapoport wrote:
> > From: Mike Rapoport <rppt@linux.ibm.com>
> > 
> > Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
> > ---
> > v3:
> > * Incorporate Michael's feedback except the extensive NOTES section. 
> 
> Hmmmm :-|
> 
> > v2: https://lore.kernel.org/linux-api/20210729082900.1581359-1-rppt@kernel.org
> > Address Alex's comments:
> > * update synopsis to match new style for syscalls without a wrapper
> > * drop note about absence of glibc wrapper
> > * update formatting
> > 
> > v1: https://lore.kernel.org/linux-api/20210727124140.1487079-1-rppt@kernel.org
> > 
> > 
> > 
> >  man2/memfd_secret.2 | 154 ++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 154 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..188c547bf
> > --- /dev/null
> > +++ b/man2/memfd_secret.2
> > @@ -0,0 +1,154 @@
> > +.\" 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 RAM-based file
> > +to access secret memory regions
> > +.SH SYNOPSIS
> > +.nf
> > +.PP
> > +.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
> > +.B #include <unistd.h>
> > +.PP
> > +.BI "int syscall(SYS_memfd_secret, unsigned int " flags );
> > +.fi
> > +.PP
> > +.IR Note :
> > +glibc provides no wrapper for
> > +.BR memfd_secret (),
> > +necessitating the use of
> > +.BR syscall (2).
> > +.SH DESCRIPTION
> > +.BR memfd_secret ()
> > +creates an anonymous file and returns a file descriptor that refers to it.
> 
> I suggested:
> s/anonymous/anonymous/ RAM-based/
> 
> was there a reason not to do that?
 
It seems I've just missed this one.
Would you like me to send v4 or you can update while applying?

> > +The file provides a way to create and access memory regions
> > +with stronger protection than usual RAM-based files and
> > +anonymous memory mappings.

...

> > +.SH SEE ALSO
> > +.BR fcntl (2),
> > +.BR ftruncate (2),
> > +.BR mlock (2),
> > +.BR mmap (2),
> > +.BR setrlimit (2)
> Thanks! The page looks much better, but sill, that NOTES section
> that I proposed [1] would be really useful, I think. What are
> the chances that you could put that together?

I will, hopefully I'll be able to find the time for this in the next few
weeks.
 
> Cheers,
> 
> Michael
> 
> [1] From my earlier mail:
> I feel like this page could benefit from a NOTES section
> that explains the rationale for the system call. This could
> note that the fact that the region is not accessible from the
> kernel removes a whole class of security attacks.

-- 
Sincerely yours,
Mike.