2021-08-15 06:46:48 +00:00
|
|
|
.\" 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 ()
|
2021-08-16 06:33:52 +00:00
|
|
|
creates an anonymous RAM-based file and returns a file descriptor
|
|
|
|
that refers to it.
|
2021-08-15 06:46:48 +00:00
|
|
|
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 open references to the file are closed,
|
|
|
|
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
|
2021-08-16 06:35:59 +00:00
|
|
|
.BR memfd_secret (2)
|
2021-08-15 06:46:48 +00:00
|
|
|
are visible only to the processes that have access to the file descriptor.
|
|
|
|
The memory region is removed from the kernel page tables
|
|
|
|
and only the page tables of the processes holding the file descriptor
|
|
|
|
map the corresponding physical memory.
|
|
|
|
(Thus, the pages in the region can't be accessed by the kernel itself,
|
|
|
|
so that, for example, pointers to the region can't be passed to
|
|
|
|
system calls.)
|
|
|
|
.PP
|
|
|
|
The following values may be bitwise ORed in
|
|
|
|
.I flags
|
|
|
|
to control the behavior of
|
2021-08-16 06:35:59 +00:00
|
|
|
.BR memfd_secret ():
|
2021-08-15 06:46:48 +00:00
|
|
|
.TP
|
|
|
|
.B FD_CLOEXEC
|
|
|
|
Set the close-on-exec flag on the new file descriptor,
|
|
|
|
which causes the region to be removed from the process on
|
|
|
|
.BR execve (2).
|
|
|
|
See the description of the
|
|
|
|
.B O_CLOEXEC
|
|
|
|
flag in
|
|
|
|
.BR open (2)
|
|
|
|
.PP
|
|
|
|
As its return value,
|
|
|
|
.BR memfd_secret ()
|
|
|
|
returns a new file descriptor that refers 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 region is locked into memory in the same way as with
|
|
|
|
.BR mlock (2),
|
|
|
|
so that it will never be written into swap.
|
|
|
|
However the implementation of
|
2021-08-16 06:35:59 +00:00
|
|
|
.BR memfd_secret ()
|
2021-08-15 06:46:48 +00:00
|
|
|
will not try to populate the whole range during the
|
|
|
|
.BR mmap (2)
|
|
|
|
call that attaches the region into the process's address space;
|
|
|
|
instead, the pages are only actually allocated
|
|
|
|
as they are faulted in.
|
|
|
|
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,
|
2021-08-16 06:35:59 +00:00
|
|
|
.BR memfd_secret ()
|
2021-08-15 06:46:48 +00:00
|
|
|
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
|
2021-08-16 06:35:59 +00:00
|
|
|
.BR memfd_secret ()
|
2021-08-15 06:46:48 +00:00
|
|
|
system call first appeared in Linux 5.14.
|
|
|
|
.SH CONFORMING TO
|
|
|
|
The
|
2021-08-16 06:35:59 +00:00
|
|
|
.BR memfd_secret ()
|
2021-08-15 06:46:48 +00:00
|
|
|
system call is Linux-specific.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.BR fcntl (2),
|
|
|
|
.BR ftruncate (2),
|
|
|
|
.BR mlock (2),
|
2021-08-16 06:47:23 +00:00
|
|
|
.BR memfd_create (2),
|
2021-08-15 06:46:48 +00:00
|
|
|
.BR mmap (2),
|
|
|
|
.BR setrlimit (2)
|