Linux-man Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH] man2: new page describing memfd_secret() system call
       [not found] <20200924132904.1391-1-rppt@kernel.org>
@ 2020-09-24 13:35 ` Mike Rapoport
  2020-09-24 14:55   ` Alejandro Colomar
  0 siblings, 1 reply; 4+ messages in thread
From: Mike Rapoport @ 2020-09-24 13:35 UTC (permalink / raw)
  To: Michael Kerrisk
  Cc: Andrew Morton, Alexander Viro, Andy Lutomirski, Arnd Bergmann,
	Borislav Petkov, Catalin Marinas, Christopher Lameter,
	Dan Williams, Dave Hansen, David Hildenbrand, Elena Reshetova,
	H. Peter Anvin, Idan Yaniv, Ingo Molnar, James Bottomley,
	Kirill A. Shutemov, Matthew Wilcox, Mark Rutland, Mike Rapoport,
	Mike Rapoport, Palmer Dabbelt, Paul Walmsley, Peter Zijlstra,
	Thomas Gleixner, Shuah Khan, Tycho Andersen, Will Deacon,
	linux-api, linux-arch, linux-arm-kernel, linux-fsdevel,
	linux-man, linux-mm, linux-kernel, linux-kselftest, linux-nvdimm,
	linux-riscv, x86

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


^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH] man2: new page describing memfd_secret() system call
  2020-09-24 13:35 ` [PATCH] man2: new page describing memfd_secret() system call Mike Rapoport
@ 2020-09-24 14:55   ` Alejandro Colomar
  2020-10-03  9:32     ` Alejandro Colomar
  0 siblings, 1 reply; 4+ messages in thread
From: Alejandro Colomar @ 2020-09-24 14:55 UTC (permalink / raw)
  To: rppt
  Cc: akpm, arnd, bp, catalin.marinas, cl, dan.j.williams, dave.hansen,
	david, elena.reshetova, hpa, idan.yaniv, jejb, kirill, linux-api,
	linux-arch, linux-arm-kernel, linux-fsdevel, linux-kernel,
	linux-kselftest, linux-man, linux-mm, linux-nvdimm, linux-riscv,
	luto, mark.rutland, mingo, mtk.manpages, palmer, paul.walmsley,
	peterz, rppt, shuah, tglx, tycho, viro, will, willy, x86

* 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

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH] man2: new page describing memfd_secret() system call
  2020-09-24 14:55   ` Alejandro Colomar
@ 2020-10-03  9:32     ` Alejandro Colomar
  2020-10-05  7:32       ` Mike Rapoport
  0 siblings, 1 reply; 4+ messages in thread
From: Alejandro Colomar @ 2020-10-03  9:32 UTC (permalink / raw)
  To: rppt, mtk.manpages
  Cc: akpm, arnd, bp, catalin.marinas, cl, dan.j.williams, dave.hansen,
	david, elena.reshetova, hpa, idan.yaniv, jejb, kirill, linux-api,
	linux-arch, linux-arm-kernel, linux-fsdevel, linux-kernel,
	linux-kselftest, linux-man, linux-mm, linux-nvdimm, linux-riscv,
	luto, mark.rutland, mingo, palmer, paul.walmsley, peterz, rppt,
	shuah, tglx, tycho, viro, will, willy, x86

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

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH] man2: new page describing memfd_secret() system call
  2020-10-03  9:32     ` Alejandro Colomar
@ 2020-10-05  7:32       ` Mike Rapoport
  0 siblings, 0 replies; 4+ messages in thread
From: Mike Rapoport @ 2020-10-05  7:32 UTC (permalink / raw)
  To: Alejandro Colomar
  Cc: mtk.manpages, akpm, arnd, bp, catalin.marinas, cl,
	dan.j.williams, dave.hansen, david, elena.reshetova, hpa,
	idan.yaniv, jejb, kirill, linux-api, linux-arch,
	linux-arm-kernel, linux-fsdevel, linux-kernel, linux-kselftest,
	linux-man, linux-mm, linux-nvdimm, linux-riscv, luto,
	mark.rutland, mingo, palmer, paul.walmsley, peterz, rppt, shuah,
	tglx, tycho, viro, will, willy, x86

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.

^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, back to index

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
     [not found] <20200924132904.1391-1-rppt@kernel.org>
2020-09-24 13:35 ` [PATCH] man2: new page describing memfd_secret() system call Mike Rapoport
2020-09-24 14:55   ` Alejandro Colomar
2020-10-03  9:32     ` Alejandro Colomar
2020-10-05  7:32       ` Mike Rapoport

Linux-man Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-man/0 linux-man/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-man linux-man/ https://lore.kernel.org/linux-man \
		linux-man@vger.kernel.org
	public-inbox-index linux-man

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-man


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git