[[ 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@xxxxxxxxxxxxx> >> >> Signed-off-by: Mike Rapoport <rppt@xxxxxxxxxxxxx> >> Cowritten-by: Alejandro Colomar <alx.manpages@xxxxxxxxx> >> Acked-by: Alejandro Colomar <alx.manpages@xxxxxxxxx> >> Signed-off-by: Alejandro Colomar <alx.manpages@xxxxxxxxx> >> --- >> >> 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@xxxxxxxxxxxxx> >> +.\" >> +.\" Based on memfd_create(2) man page >> +.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@xxxxxxxxx> >> +.\" and Copyright (C) 2014 David Herrmann <dh.herrmann@xxxxxxxxx> >> +.\" >> +.\" %%%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 >> >
