Debian Codegraph @

upstream/debian-unstable/man2/memfd_secret.2

raw
1 .\" Copyright 2014, Michael Kerrisk <[email protected]>
2 .\" Copyright 2014, David Herrmann <[email protected]>
3 .\" Copyright 2021, International Business Machines Corp.
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: GPL-2.0-or-later
7 .\"
8 .TH memfd_secret 2 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 memfd_secret \- create an anonymous RAM-based file
11 to access secret memory regions
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ,\~ \-lc )
15 .SH SYNOPSIS
16 .nf
17 .P
18 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
19 .B #include <unistd.h>
20 .P
21 .BI "int syscall(SYS_memfd_secret, unsigned int " flags );
22 .fi
23 .P
24 .IR Note :
25 glibc provides no wrapper for
26 .BR memfd_secret (),
27 necessitating the use of
28 .BR syscall (2).
29 .SH DESCRIPTION
30 .BR memfd_secret ()
31 creates an anonymous RAM-based file and returns a file descriptor
32 that refers to it.
33 The file provides a way to create and access memory regions
34 with stronger protection than usual RAM-based files and
35 anonymous memory mappings.
36 Once all open references to the file are closed,
37 it is automatically released.
38 The initial size of the file is set to 0.
39 Following the call, the file size should be set using
40 .BR ftruncate (2).
41 .P
42 The memory areas backing the file created with
43 .BR memfd_secret (2)
44 are visible only to the processes that have access to the file descriptor.
45 The memory region is removed from the kernel page tables
46 and only the page tables of the processes holding the file descriptor
47 map the corresponding physical memory.
48 (Thus, the pages in the region can't be accessed by the kernel itself,
49 so that, for example, pointers to the region can't be passed to
50 system calls.)
51 .P
52 The following values may be bitwise ORed in
53 .I flags
54 to control the behavior of
55 .BR memfd_secret ():
56 .TP
57 .B FD_CLOEXEC
58 Set the close-on-exec flag on the new file descriptor,
59 which causes the region to be removed from the process on
60 .BR execve (2).
61 See the description of the
62 .B O_CLOEXEC
63 flag in
64 .BR open (2)
65 .P
66 As its return value,
67 .BR memfd_secret ()
68 returns a new file descriptor that refers to an anonymous file.
69 This file descriptor is opened for both reading and writing
70 .RB ( O_RDWR )
71 and
72 .B O_LARGEFILE
73 is set for the file descriptor.
74 .P
75 With respect to
76 .BR fork (2)
77 and
78 .BR execve (2),
79 the usual semantics apply for the file descriptor created by
80 .BR memfd_secret ().
81 A copy of the file descriptor is inherited by the child produced by
82 .BR fork (2)
83 and refers to the same file.
84 The file descriptor is preserved across
85 .BR execve (2),
86 unless the close-on-exec flag has been set.
87 .P
88 The memory region is locked into memory in the same way as with
89 .BR mlock (2),
90 so that it will never be written into swap,
91 and hibernation is inhibited for as long as any
92 .BR memfd_secret ()
93 descriptions exist.
94 However the implementation of
95 .BR memfd_secret ()
96 will not try to populate the whole range during the
97 .BR mmap (2)
98 call that attaches the region into the process's address space;
99 instead, the pages are only actually allocated
100 as they are faulted in.
101 The amount of memory allowed for memory mappings
102 of the file descriptor obeys the same rules as
103 .BR mlock (2)
104 and cannot exceed
105 .BR RLIMIT_MEMLOCK .
106 .SH RETURN VALUE
107 On success,
108 .BR memfd_secret ()
109 returns a new file descriptor.
110 On error, \-1 is returned and
111 .I errno
112 is set to indicate the error.
113 .SH ERRORS
114 .TP
115 .B EINVAL
116 .I flags
117 included unknown bits.
118 .TP
119 .B EMFILE
120 The per-process limit on the number of open file descriptors has been reached.
121 .TP
122 .B EMFILE
123 The system-wide limit on the total number of open files has been reached.
124 .TP
125 .B ENOMEM
126 There was insufficient memory to create a new anonymous file.
127 .TP
128 .B ENOSYS
129 .BR memfd_secret ()
130 is not implemented on this architecture,
131 or has not been enabled on the kernel command-line with
132 .BR secretmem_enable =1.
133 .SH STANDARDS
134 Linux.
135 .SH HISTORY
136 Linux 5.14.
137 .P
138 Before Linux 6.5,
139 .\" commit b758fe6df50daf68fef089d8f3c1cd49fc794ed2
140 .BR memfd_secret ()
141 was disabled by default and only available
142 if the system administrator turned it on using
143 "secretmem.enable=y" kernel parameter.
144 .SH NOTES
145 The
146 .BR memfd_secret ()
147 system call is designed to allow a user-space process
148 to create a range of memory that is inaccessible to anybody else -
149 kernel included.
150 There is no 100% guarantee that kernel won't be able to access
151 memory ranges backed by
152 .BR memfd_secret ()
153 in any circumstances, but nevertheless,
154 it is much harder to exfiltrate data from these regions.
155 .P
156 .BR memfd_secret ()
157 provides the following protections:
158 .IP \[bu] 3
159 Enhanced protection
160 (in conjunction with all the other in-kernel attack prevention systems)
161 against ROP attacks.
162 Absence of any in-kernel primitive for accessing memory backed by
163 .BR memfd_secret ()
164 means that one-gadget ROP attack
165 can't work to perform data exfiltration.
166 The attacker would need to find enough ROP gadgets
167 to reconstruct the missing page table entries,
168 which significantly increases difficulty of the attack,
169 especially when other protections like the kernel stack size limit
170 and address space layout randomization are in place.
171 .IP \[bu]
172 Prevent cross-process user-space memory exposures.
173 Once a region for a
174 .BR memfd_secret ()
175 memory mapping is allocated,
176 the user can't accidentally pass it into the kernel
177 to be transmitted somewhere.
178 The memory pages in this region cannot be accessed via the direct map
179 and they are disallowed in get_user_pages.
180 .IP \[bu]
181 Harden against exploited kernel flaws.
182 In order to access memory areas backed by
183 .BR memfd_secret (),
184 a kernel-side attack would need to
185 either walk the page tables and create new ones,
186 or spawn a new privileged user-space process to perform
187 secrets exfiltration using
188 .BR ptrace (2).
189 .P
190 To prevent potential data leaks of memory regions backed by
191 .BR memfd_secret ()
192 from a hybernation image,
193 hybernation is prevented when there are active
194 .BR memfd_secret ()
195 users.
196 .SH SEE ALSO
197 .BR fcntl (2),
198 .BR ftruncate (2),
199 .BR mlock (2),
200 .BR memfd_create (2),
201 .BR mmap (2),
202 .BR setrlimit (2)