1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 .. Copyright © 2017-2020 Mickaël Salaün <mic 2 .. Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net>
3 .. Copyright © 2019-2020 ANSSI 3 .. Copyright © 2019-2020 ANSSI
4 .. Copyright © 2021-2022 Microsoft Corporatio 4 .. Copyright © 2021-2022 Microsoft Corporation
5 5
6 ===================================== 6 =====================================
7 Landlock: unprivileged access control 7 Landlock: unprivileged access control
8 ===================================== 8 =====================================
9 9
10 :Author: Mickaël Salaün 10 :Author: Mickaël Salaün
11 :Date: September 2024 !! 11 :Date: October 2022
12 12
13 The goal of Landlock is to enable to restrict 13 The goal of Landlock is to enable to restrict ambient rights (e.g. global
14 filesystem or network access) for a set of pro !! 14 filesystem access) for a set of processes. Because Landlock is a stackable
15 is a stackable LSM, it makes possible to creat !! 15 LSM, it makes possible to create safe security sandboxes as new security layers
16 security layers in addition to the existing sy !! 16 in addition to the existing system-wide access-controls. This kind of sandbox
17 kind of sandbox is expected to help mitigate t !! 17 is expected to help mitigate the security impact of bugs or
18 unexpected/malicious behaviors in user space a 18 unexpected/malicious behaviors in user space applications. Landlock empowers
19 any process, including unprivileged ones, to s 19 any process, including unprivileged ones, to securely restrict themselves.
20 20
21 We can quickly make sure that Landlock is enab 21 We can quickly make sure that Landlock is enabled in the running system by
22 looking for "landlock: Up and running" in kern !! 22 looking for "landlock: Up and running" in kernel logs (as root): ``dmesg | grep
23 ``dmesg | grep landlock || journalctl -kb -g l !! 23 landlock || journalctl -kg landlock`` . Developers can also easily check for
24 Developers can also easily check for Landlock !! 24 Landlock support with a :ref:`related system call <landlock_abi_versions>`. If
25 :ref:`related system call <landlock_abi_versio !! 25 Landlock is not currently supported, we need to :ref:`configure the kernel
26 If Landlock is not currently supported, we nee !! 26 appropriately <kernel_support>`.
27 :ref:`configure the kernel appropriately <kern <<
28 27
29 Landlock rules 28 Landlock rules
30 ============== 29 ==============
31 30
32 A Landlock rule describes an action on an obje !! 31 A Landlock rule describes an action on an object. An object is currently a
33 perform. A set of rules is aggregated in a ru !! 32 file hierarchy, and the related filesystem actions are defined with `access
>> 33 rights`_. A set of rules is aggregated in a ruleset, which can then restrict
34 the thread enforcing it, and its future childr 34 the thread enforcing it, and its future children.
35 35
36 The two existing types of rules are: <<
37 <<
38 Filesystem rules <<
39 For these rules, the object is a file hier <<
40 and the related filesystem actions are def <<
41 `filesystem access rights`. <<
42 <<
43 Network rules (since ABI v4) <<
44 For these rules, the object is a TCP port, <<
45 and the related actions are defined with ` <<
46 <<
47 Defining and enforcing a security policy 36 Defining and enforcing a security policy
48 ---------------------------------------- 37 ----------------------------------------
49 38
50 We first need to define the ruleset that will !! 39 We first need to define the ruleset that will contain our rules. For this
51 !! 40 example, the ruleset will contain rules that only allow read actions, but write
52 For this example, the ruleset will contain rul !! 41 actions will be denied. The ruleset then needs to handle both of these kind of
53 read actions and establish a specific TCP conn !! 42 actions. This is required for backward and forward compatibility (i.e. the
54 actions and other TCP actions will be denied. !! 43 kernel and user space may not know each other's supported restrictions), hence
55 !! 44 the need to be explicit about the denied-by-default access rights.
56 The ruleset then needs to handle both these ki <<
57 required for backward and forward compatibilit <<
58 space may not know each other's supported rest <<
59 to be explicit about the denied-by-default acc <<
60 45
61 .. code-block:: c 46 .. code-block:: c
62 47
63 struct landlock_ruleset_attr ruleset_attr 48 struct landlock_ruleset_attr ruleset_attr = {
64 .handled_access_fs = 49 .handled_access_fs =
65 LANDLOCK_ACCESS_FS_EXECUTE | 50 LANDLOCK_ACCESS_FS_EXECUTE |
66 LANDLOCK_ACCESS_FS_WRITE_FILE | 51 LANDLOCK_ACCESS_FS_WRITE_FILE |
67 LANDLOCK_ACCESS_FS_READ_FILE | 52 LANDLOCK_ACCESS_FS_READ_FILE |
68 LANDLOCK_ACCESS_FS_READ_DIR | 53 LANDLOCK_ACCESS_FS_READ_DIR |
69 LANDLOCK_ACCESS_FS_REMOVE_DIR | 54 LANDLOCK_ACCESS_FS_REMOVE_DIR |
70 LANDLOCK_ACCESS_FS_REMOVE_FILE | 55 LANDLOCK_ACCESS_FS_REMOVE_FILE |
71 LANDLOCK_ACCESS_FS_MAKE_CHAR | 56 LANDLOCK_ACCESS_FS_MAKE_CHAR |
72 LANDLOCK_ACCESS_FS_MAKE_DIR | 57 LANDLOCK_ACCESS_FS_MAKE_DIR |
73 LANDLOCK_ACCESS_FS_MAKE_REG | 58 LANDLOCK_ACCESS_FS_MAKE_REG |
74 LANDLOCK_ACCESS_FS_MAKE_SOCK | 59 LANDLOCK_ACCESS_FS_MAKE_SOCK |
75 LANDLOCK_ACCESS_FS_MAKE_FIFO | 60 LANDLOCK_ACCESS_FS_MAKE_FIFO |
76 LANDLOCK_ACCESS_FS_MAKE_BLOCK | 61 LANDLOCK_ACCESS_FS_MAKE_BLOCK |
77 LANDLOCK_ACCESS_FS_MAKE_SYM | 62 LANDLOCK_ACCESS_FS_MAKE_SYM |
78 LANDLOCK_ACCESS_FS_REFER | 63 LANDLOCK_ACCESS_FS_REFER |
79 LANDLOCK_ACCESS_FS_TRUNCATE | !! 64 LANDLOCK_ACCESS_FS_TRUNCATE,
80 LANDLOCK_ACCESS_FS_IOCTL_DEV, <<
81 .handled_access_net = <<
82 LANDLOCK_ACCESS_NET_BIND_TCP | <<
83 LANDLOCK_ACCESS_NET_CONNECT_TCP, <<
84 .scoped = <<
85 LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKE <<
86 LANDLOCK_SCOPE_SIGNAL, <<
87 }; 65 };
88 66
89 Because we may not know on which kernel versio 67 Because we may not know on which kernel version an application will be
90 executed, it is safer to follow a best-effort 68 executed, it is safer to follow a best-effort security approach. Indeed, we
91 should try to protect users as much as possibl 69 should try to protect users as much as possible whatever the kernel they are
92 using. !! 70 using. To avoid binary enforcement (i.e. either all security features or
93 !! 71 none), we can leverage a dedicated Landlock command to get the current version
94 To be compatible with older Linux versions, we !! 72 of the Landlock ABI and adapt the handled accesses. Let's check if we should
95 version, and only use the available subset of !! 73 remove the ``LANDLOCK_ACCESS_FS_REFER`` or ``LANDLOCK_ACCESS_FS_TRUNCATE``
>> 74 access rights, which are only supported starting with the second and third
>> 75 version of the ABI.
96 76
97 .. code-block:: c 77 .. code-block:: c
98 78
99 int abi; 79 int abi;
100 80
101 abi = landlock_create_ruleset(NULL, 0, LAN 81 abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION);
102 if (abi < 0) { 82 if (abi < 0) {
103 /* Degrades gracefully if Landlock is 83 /* Degrades gracefully if Landlock is not handled. */
104 perror("The running kernel does not en 84 perror("The running kernel does not enable to use Landlock");
105 return 0; 85 return 0;
106 } 86 }
107 switch (abi) { 87 switch (abi) {
108 case 1: 88 case 1:
109 /* Removes LANDLOCK_ACCESS_FS_REFER fo 89 /* Removes LANDLOCK_ACCESS_FS_REFER for ABI < 2 */
110 ruleset_attr.handled_access_fs &= ~LAN 90 ruleset_attr.handled_access_fs &= ~LANDLOCK_ACCESS_FS_REFER;
111 __attribute__((fallthrough)); 91 __attribute__((fallthrough));
112 case 2: 92 case 2:
113 /* Removes LANDLOCK_ACCESS_FS_TRUNCATE 93 /* Removes LANDLOCK_ACCESS_FS_TRUNCATE for ABI < 3 */
114 ruleset_attr.handled_access_fs &= ~LAN 94 ruleset_attr.handled_access_fs &= ~LANDLOCK_ACCESS_FS_TRUNCATE;
115 __attribute__((fallthrough)); <<
116 case 3: <<
117 /* Removes network support for ABI < 4 <<
118 ruleset_attr.handled_access_net &= <<
119 ~(LANDLOCK_ACCESS_NET_BIND_TCP | <<
120 LANDLOCK_ACCESS_NET_CONNECT_TCP) <<
121 __attribute__((fallthrough)); <<
122 case 4: <<
123 /* Removes LANDLOCK_ACCESS_FS_IOCTL_DE <<
124 ruleset_attr.handled_access_fs &= ~LAN <<
125 __attribute__((fallthrough)); <<
126 case 5: <<
127 /* Removes LANDLOCK_SCOPE_* for ABI < <<
128 ruleset_attr.scoped &= ~(LANDLOCK_SCOP <<
129 LANDLOCK_SCOP <<
130 } 95 }
131 96
132 This enables to create an inclusive ruleset th 97 This enables to create an inclusive ruleset that will contain our rules.
133 98
134 .. code-block:: c 99 .. code-block:: c
135 100
136 int ruleset_fd; 101 int ruleset_fd;
137 102
138 ruleset_fd = landlock_create_ruleset(&rule 103 ruleset_fd = landlock_create_ruleset(&ruleset_attr, sizeof(ruleset_attr), 0);
139 if (ruleset_fd < 0) { 104 if (ruleset_fd < 0) {
140 perror("Failed to create a ruleset"); 105 perror("Failed to create a ruleset");
141 return 1; 106 return 1;
142 } 107 }
143 108
144 We can now add a new rule to this ruleset than 109 We can now add a new rule to this ruleset thanks to the returned file
145 descriptor referring to this ruleset. The rul 110 descriptor referring to this ruleset. The rule will only allow reading the
146 file hierarchy ``/usr``. Without another rule 111 file hierarchy ``/usr``. Without another rule, write actions would then be
147 denied by the ruleset. To add ``/usr`` to the 112 denied by the ruleset. To add ``/usr`` to the ruleset, we open it with the
148 ``O_PATH`` flag and fill the &struct landlock_ 113 ``O_PATH`` flag and fill the &struct landlock_path_beneath_attr with this file
149 descriptor. 114 descriptor.
150 115
151 .. code-block:: c 116 .. code-block:: c
152 117
153 int err; 118 int err;
154 struct landlock_path_beneath_attr path_ben 119 struct landlock_path_beneath_attr path_beneath = {
155 .allowed_access = 120 .allowed_access =
156 LANDLOCK_ACCESS_FS_EXECUTE | 121 LANDLOCK_ACCESS_FS_EXECUTE |
157 LANDLOCK_ACCESS_FS_READ_FILE | 122 LANDLOCK_ACCESS_FS_READ_FILE |
158 LANDLOCK_ACCESS_FS_READ_DIR, 123 LANDLOCK_ACCESS_FS_READ_DIR,
159 }; 124 };
160 125
161 path_beneath.parent_fd = open("/usr", O_PA 126 path_beneath.parent_fd = open("/usr", O_PATH | O_CLOEXEC);
162 if (path_beneath.parent_fd < 0) { 127 if (path_beneath.parent_fd < 0) {
163 perror("Failed to open file"); 128 perror("Failed to open file");
164 close(ruleset_fd); 129 close(ruleset_fd);
165 return 1; 130 return 1;
166 } 131 }
167 err = landlock_add_rule(ruleset_fd, LANDLO 132 err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_PATH_BENEATH,
168 &path_beneath, 0); 133 &path_beneath, 0);
169 close(path_beneath.parent_fd); 134 close(path_beneath.parent_fd);
170 if (err) { 135 if (err) {
171 perror("Failed to update ruleset"); 136 perror("Failed to update ruleset");
172 close(ruleset_fd); 137 close(ruleset_fd);
173 return 1; 138 return 1;
174 } 139 }
175 140
176 It may also be required to create rules follow 141 It may also be required to create rules following the same logic as explained
177 for the ruleset creation, by filtering access 142 for the ruleset creation, by filtering access rights according to the Landlock
178 ABI version. In this example, this is not req 143 ABI version. In this example, this is not required because all of the requested
179 ``allowed_access`` rights are already availabl 144 ``allowed_access`` rights are already available in ABI 1.
180 145
181 For network access-control, we can add a set o !! 146 We now have a ruleset with one rule allowing read access to ``/usr`` while
182 number for a specific action: HTTPS connection !! 147 denying all other handled accesses for the filesystem. The next step is to
183 !! 148 restrict the current thread from gaining more privileges (e.g. thanks to a SUID
184 .. code-block:: c !! 149 binary).
185 <<
186 struct landlock_net_port_attr net_port = { <<
187 .allowed_access = LANDLOCK_ACCESS_NET_ <<
188 .port = 443, <<
189 }; <<
190 <<
191 err = landlock_add_rule(ruleset_fd, LANDLO <<
192 &net_port, 0); <<
193 <<
194 The next step is to restrict the current threa <<
195 (e.g. through a SUID binary). We now have a r <<
196 allowing read access to ``/usr`` while denying <<
197 the filesystem, and a second rule allowing HTT <<
198 150
199 .. code-block:: c 151 .. code-block:: c
200 152
201 if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) 153 if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) {
202 perror("Failed to restrict privileges" 154 perror("Failed to restrict privileges");
203 close(ruleset_fd); 155 close(ruleset_fd);
204 return 1; 156 return 1;
205 } 157 }
206 158
207 The current thread is now ready to sandbox its 159 The current thread is now ready to sandbox itself with the ruleset.
208 160
209 .. code-block:: c 161 .. code-block:: c
210 162
211 if (landlock_restrict_self(ruleset_fd, 0)) 163 if (landlock_restrict_self(ruleset_fd, 0)) {
212 perror("Failed to enforce ruleset"); 164 perror("Failed to enforce ruleset");
213 close(ruleset_fd); 165 close(ruleset_fd);
214 return 1; 166 return 1;
215 } 167 }
216 close(ruleset_fd); 168 close(ruleset_fd);
217 169
218 If the ``landlock_restrict_self`` system call 170 If the ``landlock_restrict_self`` system call succeeds, the current thread is
219 now restricted and this policy will be enforce 171 now restricted and this policy will be enforced on all its subsequently created
220 children as well. Once a thread is landlocked 172 children as well. Once a thread is landlocked, there is no way to remove its
221 security policy; only adding more restrictions 173 security policy; only adding more restrictions is allowed. These threads are
222 now in a new Landlock domain, merge of their p 174 now in a new Landlock domain, merge of their parent one (if any) with the new
223 ruleset. 175 ruleset.
224 176
225 Full working code can be found in `samples/lan 177 Full working code can be found in `samples/landlock/sandboxer.c`_.
226 178
227 Good practices 179 Good practices
228 -------------- 180 --------------
229 181
230 It is recommended setting access rights to fil 182 It is recommended setting access rights to file hierarchy leaves as much as
231 possible. For instance, it is better to be ab 183 possible. For instance, it is better to be able to have ``~/doc/`` as a
232 read-only hierarchy and ``~/tmp/`` as a read-w 184 read-only hierarchy and ``~/tmp/`` as a read-write hierarchy, compared to
233 ``~/`` as a read-only hierarchy and ``~/tmp/`` 185 ``~/`` as a read-only hierarchy and ``~/tmp/`` as a read-write hierarchy.
234 Following this good practice leads to self-suf 186 Following this good practice leads to self-sufficient hierarchies that do not
235 depend on their location (i.e. parent director 187 depend on their location (i.e. parent directories). This is particularly
236 relevant when we want to allow linking or rena 188 relevant when we want to allow linking or renaming. Indeed, having consistent
237 access rights per directory enables to change 189 access rights per directory enables to change the location of such directory
238 without relying on the destination directory a 190 without relying on the destination directory access rights (except those that
239 are required for this operation, see ``LANDLOC 191 are required for this operation, see ``LANDLOCK_ACCESS_FS_REFER``
240 documentation). 192 documentation).
241 <<
242 Having self-sufficient hierarchies also helps 193 Having self-sufficient hierarchies also helps to tighten the required access
243 rights to the minimal set of data. This also 194 rights to the minimal set of data. This also helps avoid sinkhole directories,
244 i.e. directories where data can be linked to 195 i.e. directories where data can be linked to but not linked from. However,
245 this depends on data organization, which might 196 this depends on data organization, which might not be controlled by developers.
246 In this case, granting read-write access to `` 197 In this case, granting read-write access to ``~/tmp/``, instead of write-only
247 access, would potentially allow to move ``~/tm 198 access, would potentially allow to move ``~/tmp/`` to a non-readable directory
248 and still keep the ability to list the content 199 and still keep the ability to list the content of ``~/tmp/``.
249 200
250 Layers of file path access rights 201 Layers of file path access rights
251 --------------------------------- 202 ---------------------------------
252 203
253 Each time a thread enforces a ruleset on itsel 204 Each time a thread enforces a ruleset on itself, it updates its Landlock domain
254 with a new layer of policy. Indeed, this comp 205 with a new layer of policy. Indeed, this complementary policy is stacked with
255 the potentially other rulesets already restric 206 the potentially other rulesets already restricting this thread. A sandboxed
256 thread can then safely add more constraints to 207 thread can then safely add more constraints to itself with a new enforced
257 ruleset. 208 ruleset.
258 209
259 One policy layer grants access to a file path 210 One policy layer grants access to a file path if at least one of its rules
260 encountered on the path grants the access. A 211 encountered on the path grants the access. A sandboxed thread can only access
261 a file path if all its enforced policy layers 212 a file path if all its enforced policy layers grant the access as well as all
262 the other system access controls (e.g. filesys 213 the other system access controls (e.g. filesystem DAC, other LSM policies,
263 etc.). 214 etc.).
264 215
265 Bind mounts and OverlayFS 216 Bind mounts and OverlayFS
266 ------------------------- 217 -------------------------
267 218
268 Landlock enables to restrict access to file hi 219 Landlock enables to restrict access to file hierarchies, which means that these
269 access rights can be propagated with bind moun 220 access rights can be propagated with bind mounts (cf.
270 Documentation/filesystems/sharedsubtree.rst) b 221 Documentation/filesystems/sharedsubtree.rst) but not with
271 Documentation/filesystems/overlayfs.rst. 222 Documentation/filesystems/overlayfs.rst.
272 223
273 A bind mount mirrors a source file hierarchy t 224 A bind mount mirrors a source file hierarchy to a destination. The destination
274 hierarchy is then composed of the exact same f 225 hierarchy is then composed of the exact same files, on which Landlock rules can
275 be tied, either via the source or the destinat 226 be tied, either via the source or the destination path. These rules restrict
276 access when they are encountered on a path, wh 227 access when they are encountered on a path, which means that they can restrict
277 access to multiple file hierarchies at the sam 228 access to multiple file hierarchies at the same time, whether these hierarchies
278 are the result of bind mounts or not. 229 are the result of bind mounts or not.
279 230
280 An OverlayFS mount point consists of upper and 231 An OverlayFS mount point consists of upper and lower layers. These layers are
281 combined in a merge directory, result of the m 232 combined in a merge directory, result of the mount point. This merge hierarchy
282 may include files from the upper and lower lay 233 may include files from the upper and lower layers, but modifications performed
283 on the merge hierarchy only reflects on the up 234 on the merge hierarchy only reflects on the upper layer. From a Landlock
284 policy point of view, each OverlayFS layers an 235 policy point of view, each OverlayFS layers and merge hierarchies are
285 standalone and contains their own set of files 236 standalone and contains their own set of files and directories, which is
286 different from bind mounts. A policy restrict 237 different from bind mounts. A policy restricting an OverlayFS layer will not
287 restrict the resulted merged hierarchy, and vi 238 restrict the resulted merged hierarchy, and vice versa. Landlock users should
288 then only think about file hierarchies they wa 239 then only think about file hierarchies they want to allow access to, regardless
289 of the underlying filesystem. 240 of the underlying filesystem.
290 241
291 Inheritance 242 Inheritance
292 ----------- 243 -----------
293 244
294 Every new thread resulting from a :manpage:`cl 245 Every new thread resulting from a :manpage:`clone(2)` inherits Landlock domain
295 restrictions from its parent. This is similar 246 restrictions from its parent. This is similar to the seccomp inheritance (cf.
296 Documentation/userspace-api/seccomp_filter.rst 247 Documentation/userspace-api/seccomp_filter.rst) or any other LSM dealing with
297 task's :manpage:`credentials(7)`. For instanc 248 task's :manpage:`credentials(7)`. For instance, one process's thread may apply
298 Landlock rules to itself, but they will not be 249 Landlock rules to itself, but they will not be automatically applied to other
299 sibling threads (unlike POSIX thread credentia 250 sibling threads (unlike POSIX thread credential changes, cf.
300 :manpage:`nptl(7)`). 251 :manpage:`nptl(7)`).
301 252
302 When a thread sandboxes itself, we have the gu 253 When a thread sandboxes itself, we have the guarantee that the related security
303 policy will stay enforced on all this thread's 254 policy will stay enforced on all this thread's descendants. This allows
304 creating standalone and modular security polic 255 creating standalone and modular security policies per application, which will
305 automatically be composed between themselves a 256 automatically be composed between themselves according to their runtime parent
306 policies. 257 policies.
307 258
308 Ptrace restrictions 259 Ptrace restrictions
309 ------------------- 260 -------------------
310 261
311 A sandboxed process has less privileges than a 262 A sandboxed process has less privileges than a non-sandboxed process and must
312 then be subject to additional restrictions whe 263 then be subject to additional restrictions when manipulating another process.
313 To be allowed to use :manpage:`ptrace(2)` and 264 To be allowed to use :manpage:`ptrace(2)` and related syscalls on a target
314 process, a sandboxed process should have a sub 265 process, a sandboxed process should have a subset of the target process rules,
315 which means the tracee must be in a sub-domain 266 which means the tracee must be in a sub-domain of the tracer.
316 267
317 IPC scoping <<
318 ----------- <<
319 <<
320 Similar to the implicit `Ptrace restrictions`_ <<
321 interactions between sandboxes. Each Landlock <<
322 for a set of actions by specifying it on a rul <<
323 sandboxed process should not be able to :manpa <<
324 non-sandboxed process through abstract :manpag <<
325 specify such restriction with ``LANDLOCK_SCOPE <<
326 Moreover, if a sandboxed process should not be <<
327 non-sandboxed process, we can specify this res <<
328 ``LANDLOCK_SCOPE_SIGNAL``. <<
329 <<
330 A sandboxed process can connect to a non-sandb <<
331 not scoped. If a process's domain is scoped, i <<
332 created by processes in the same scope. <<
333 Moreover, If a process is scoped to send signa <<
334 only send signals to processes in the same sco <<
335 <<
336 A connected datagram socket behaves like a str <<
337 scoped, meaning if the domain is scoped after <<
338 still :manpage:`send(2)` data just like a stre <<
339 scenario, a non-connected datagram socket cann <<
340 :manpage:`sendto(2)`) outside its scope. <<
341 <<
342 A process with a scoped domain can inherit a s <<
343 process. The process cannot connect to this so <<
344 domain. <<
345 <<
346 IPC scoping does not support exceptions, so if <<
347 be added to allow access to resources or proce <<
348 <<
349 Truncating files 268 Truncating files
350 ---------------- 269 ----------------
351 270
352 The operations covered by ``LANDLOCK_ACCESS_FS 271 The operations covered by ``LANDLOCK_ACCESS_FS_WRITE_FILE`` and
353 ``LANDLOCK_ACCESS_FS_TRUNCATE`` both change th 272 ``LANDLOCK_ACCESS_FS_TRUNCATE`` both change the contents of a file and sometimes
354 overlap in non-intuitive ways. It is recommen 273 overlap in non-intuitive ways. It is recommended to always specify both of
355 these together. 274 these together.
356 275
357 A particularly surprising example is :manpage: 276 A particularly surprising example is :manpage:`creat(2)`. The name suggests
358 that this system call requires the rights to c 277 that this system call requires the rights to create and write files. However,
359 it also requires the truncate right if an exis 278 it also requires the truncate right if an existing file under the same name is
360 already present. 279 already present.
361 280
362 It should also be noted that truncating files 281 It should also be noted that truncating files does not require the
363 ``LANDLOCK_ACCESS_FS_WRITE_FILE`` right. Apar 282 ``LANDLOCK_ACCESS_FS_WRITE_FILE`` right. Apart from the :manpage:`truncate(2)`
364 system call, this can also be done through :ma 283 system call, this can also be done through :manpage:`open(2)` with the flags
365 ``O_RDONLY | O_TRUNC``. 284 ``O_RDONLY | O_TRUNC``.
366 285
367 The truncate right is associated with the open !! 286 When opening a file, the availability of the ``LANDLOCK_ACCESS_FS_TRUNCATE``
368 !! 287 right is associated with the newly created file descriptor and will be used for
369 Rights associated with file descriptors !! 288 subsequent truncation attempts using :manpage:`ftruncate(2)`. The behavior is
370 --------------------------------------- !! 289 similar to opening a file for reading or writing, where permissions are checked
371 !! 290 during :manpage:`open(2)`, but not during the subsequent :manpage:`read(2)` and
372 When opening a file, the availability of the ` <<
373 ``LANDLOCK_ACCESS_FS_IOCTL_DEV`` rights is ass <<
374 file descriptor and will be used for subsequen <<
375 using :manpage:`ftruncate(2)` and :manpage:`io <<
376 to opening a file for reading or writing, wher <<
377 :manpage:`open(2)`, but not during the subsequ <<
378 :manpage:`write(2)` calls. 291 :manpage:`write(2)` calls.
379 292
380 As a consequence, it is possible that a proces !! 293 As a consequence, it is possible to have multiple open file descriptors for the
381 descriptors referring to the same file, but La !! 294 same file, where one grants the right to truncate the file and the other does
382 when operating with these file descriptors. T !! 295 not. It is also possible to pass such file descriptors between processes,
383 ruleset gets enforced and the process keeps fi !! 296 keeping their Landlock properties, even when these processes do not have an
384 both before and after the enforcement. It is !! 297 enforced Landlock ruleset.
385 descriptors between processes, keeping their L <<
386 of the involved processes do not have an enfor <<
387 298
388 Compatibility 299 Compatibility
389 ============= 300 =============
390 301
391 Backward and forward compatibility 302 Backward and forward compatibility
392 ---------------------------------- 303 ----------------------------------
393 304
394 Landlock is designed to be compatible with pas 305 Landlock is designed to be compatible with past and future versions of the
395 kernel. This is achieved thanks to the system 306 kernel. This is achieved thanks to the system call attributes and the
396 associated bitflags, particularly the ruleset' 307 associated bitflags, particularly the ruleset's ``handled_access_fs``. Making
397 handled access right explicit enables the kern 308 handled access right explicit enables the kernel and user space to have a clear
398 contract with each other. This is required to 309 contract with each other. This is required to make sure sandboxing will not
399 get stricter with a system update, which could 310 get stricter with a system update, which could break applications.
400 311
401 Developers can subscribe to the `Landlock mail 312 Developers can subscribe to the `Landlock mailing list
402 <https://subspace.kernel.org/lists.linux.dev.h 313 <https://subspace.kernel.org/lists.linux.dev.html>`_ to knowingly update and
403 test their applications with the latest availa 314 test their applications with the latest available features. In the interest of
404 users, and because they may use different kern 315 users, and because they may use different kernel versions, it is strongly
405 encouraged to follow a best-effort security ap 316 encouraged to follow a best-effort security approach by checking the Landlock
406 ABI version at runtime and only enforcing the 317 ABI version at runtime and only enforcing the supported features.
407 318
408 .. _landlock_abi_versions: 319 .. _landlock_abi_versions:
409 320
410 Landlock ABI versions 321 Landlock ABI versions
411 --------------------- 322 ---------------------
412 323
413 The Landlock ABI version can be read with the 324 The Landlock ABI version can be read with the sys_landlock_create_ruleset()
414 system call: 325 system call:
415 326
416 .. code-block:: c 327 .. code-block:: c
417 328
418 int abi; 329 int abi;
419 330
420 abi = landlock_create_ruleset(NULL, 0, LAN 331 abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION);
421 if (abi < 0) { 332 if (abi < 0) {
422 switch (errno) { 333 switch (errno) {
423 case ENOSYS: 334 case ENOSYS:
424 printf("Landlock is not supported 335 printf("Landlock is not supported by the current kernel.\n");
425 break; 336 break;
426 case EOPNOTSUPP: 337 case EOPNOTSUPP:
427 printf("Landlock is currently disa 338 printf("Landlock is currently disabled.\n");
428 break; 339 break;
429 } 340 }
430 return 0; 341 return 0;
431 } 342 }
432 if (abi >= 2) { 343 if (abi >= 2) {
433 printf("Landlock supports LANDLOCK_ACC 344 printf("Landlock supports LANDLOCK_ACCESS_FS_REFER.\n");
434 } 345 }
435 346
436 The following kernel interfaces are implicitly 347 The following kernel interfaces are implicitly supported by the first ABI
437 version. Features only supported from a speci 348 version. Features only supported from a specific version are explicitly marked
438 as such. 349 as such.
439 350
440 Kernel interface 351 Kernel interface
441 ================ 352 ================
442 353
443 Access rights 354 Access rights
444 ------------- 355 -------------
445 356
446 .. kernel-doc:: include/uapi/linux/landlock.h 357 .. kernel-doc:: include/uapi/linux/landlock.h
447 :identifiers: fs_access net_access scope !! 358 :identifiers: fs_access
448 359
449 Creating a new ruleset 360 Creating a new ruleset
450 ---------------------- 361 ----------------------
451 362
452 .. kernel-doc:: security/landlock/syscalls.c 363 .. kernel-doc:: security/landlock/syscalls.c
453 :identifiers: sys_landlock_create_ruleset 364 :identifiers: sys_landlock_create_ruleset
454 365
455 .. kernel-doc:: include/uapi/linux/landlock.h 366 .. kernel-doc:: include/uapi/linux/landlock.h
456 :identifiers: landlock_ruleset_attr 367 :identifiers: landlock_ruleset_attr
457 368
458 Extending a ruleset 369 Extending a ruleset
459 ------------------- 370 -------------------
460 371
461 .. kernel-doc:: security/landlock/syscalls.c 372 .. kernel-doc:: security/landlock/syscalls.c
462 :identifiers: sys_landlock_add_rule 373 :identifiers: sys_landlock_add_rule
463 374
464 .. kernel-doc:: include/uapi/linux/landlock.h 375 .. kernel-doc:: include/uapi/linux/landlock.h
465 :identifiers: landlock_rule_type landlock_ 376 :identifiers: landlock_rule_type landlock_path_beneath_attr
466 landlock_net_port_attr <<
467 377
468 Enforcing a ruleset 378 Enforcing a ruleset
469 ------------------- 379 -------------------
470 380
471 .. kernel-doc:: security/landlock/syscalls.c 381 .. kernel-doc:: security/landlock/syscalls.c
472 :identifiers: sys_landlock_restrict_self 382 :identifiers: sys_landlock_restrict_self
473 383
474 Current limitations 384 Current limitations
475 =================== 385 ===================
476 386
477 Filesystem topology modification 387 Filesystem topology modification
478 -------------------------------- 388 --------------------------------
479 389
480 Threads sandboxed with filesystem restrictions !! 390 As for file renaming and linking, a sandboxed thread cannot modify its
481 topology, whether via :manpage:`mount(2)` or : !! 391 filesystem topology, whether via :manpage:`mount(2)` or
482 However, :manpage:`chroot(2)` calls are not de !! 392 :manpage:`pivot_root(2)`. However, :manpage:`chroot(2)` calls are not denied.
483 393
484 Special filesystems 394 Special filesystems
485 ------------------- 395 -------------------
486 396
487 Access to regular files and directories can be 397 Access to regular files and directories can be restricted by Landlock,
488 according to the handled accesses of a ruleset 398 according to the handled accesses of a ruleset. However, files that do not
489 come from a user-visible filesystem (e.g. pipe 399 come from a user-visible filesystem (e.g. pipe, socket), but can still be
490 accessed through ``/proc/<pid>/fd/*``, cannot 400 accessed through ``/proc/<pid>/fd/*``, cannot currently be explicitly
491 restricted. Likewise, some special kernel fil 401 restricted. Likewise, some special kernel filesystems such as nsfs, which can
492 be accessed through ``/proc/<pid>/ns/*``, cann 402 be accessed through ``/proc/<pid>/ns/*``, cannot currently be explicitly
493 restricted. However, thanks to the `ptrace re 403 restricted. However, thanks to the `ptrace restrictions`_, access to such
494 sensitive ``/proc`` files are automatically re 404 sensitive ``/proc`` files are automatically restricted according to domain
495 hierarchies. Future Landlock evolutions could 405 hierarchies. Future Landlock evolutions could still enable to explicitly
496 restrict such paths with dedicated ruleset fla 406 restrict such paths with dedicated ruleset flags.
497 407
498 Ruleset layers 408 Ruleset layers
499 -------------- 409 --------------
500 410
501 There is a limit of 16 layers of stacked rules 411 There is a limit of 16 layers of stacked rulesets. This can be an issue for a
502 task willing to enforce a new ruleset in compl 412 task willing to enforce a new ruleset in complement to its 16 inherited
503 rulesets. Once this limit is reached, sys_lan 413 rulesets. Once this limit is reached, sys_landlock_restrict_self() returns
504 E2BIG. It is then strongly suggested to caref 414 E2BIG. It is then strongly suggested to carefully build rulesets once in the
505 life of a thread, especially for applications 415 life of a thread, especially for applications able to launch other applications
506 that may also want to sandbox themselves (e.g. 416 that may also want to sandbox themselves (e.g. shells, container managers,
507 etc.). 417 etc.).
508 418
509 Memory usage 419 Memory usage
510 ------------ 420 ------------
511 421
512 Kernel memory allocated to create rulesets is 422 Kernel memory allocated to create rulesets is accounted and can be restricted
513 by the Documentation/admin-guide/cgroup-v1/mem 423 by the Documentation/admin-guide/cgroup-v1/memory.rst.
514 424
515 IOCTL support <<
516 ------------- <<
517 <<
518 The ``LANDLOCK_ACCESS_FS_IOCTL_DEV`` right res <<
519 :manpage:`ioctl(2)`, but it only applies to *n <<
520 means specifically that pre-existing file desc <<
521 stderr are unaffected. <<
522 <<
523 Users should be aware that TTY devices have tr <<
524 other processes on the same TTY through the `` <<
525 commands. Both of these require ``CAP_SYS_ADM <<
526 the behavior is configurable for ``TIOCSTI``. <<
527 <<
528 On older systems, it is therefore recommended <<
529 descriptors, or to reopen them from ``/proc/se <<
530 ``LANDLOCK_ACCESS_FS_IOCTL_DEV`` right, if pos <<
531 <<
532 Landlock's IOCTL support is coarse-grained at <<
533 fine-grained in the future. Until then, users <<
534 guarantees that they need through the file hie <<
535 ``LANDLOCK_ACCESS_FS_IOCTL_DEV`` right on file <<
536 <<
537 Previous limitations 425 Previous limitations
538 ==================== 426 ====================
539 427
540 File renaming and linking (ABI < 2) 428 File renaming and linking (ABI < 2)
541 ----------------------------------- 429 -----------------------------------
542 430
543 Because Landlock targets unprivileged access c 431 Because Landlock targets unprivileged access controls, it needs to properly
544 handle composition of rules. Such property al 432 handle composition of rules. Such property also implies rules nesting.
545 Properly handling multiple layers of rulesets, 433 Properly handling multiple layers of rulesets, each one of them able to
546 restrict access to files, also implies inherit 434 restrict access to files, also implies inheritance of the ruleset restrictions
547 from a parent to its hierarchy. Because files 435 from a parent to its hierarchy. Because files are identified and restricted by
548 their hierarchy, moving or linking a file from 436 their hierarchy, moving or linking a file from one directory to another implies
549 propagation of the hierarchy constraints, or r 437 propagation of the hierarchy constraints, or restriction of these actions
550 according to the potentially lost constraints. 438 according to the potentially lost constraints. To protect against privilege
551 escalations through renaming or linking, and f 439 escalations through renaming or linking, and for the sake of simplicity,
552 Landlock previously limited linking and renami 440 Landlock previously limited linking and renaming to the same directory.
553 Starting with the Landlock ABI version 2, it i 441 Starting with the Landlock ABI version 2, it is now possible to securely
554 control renaming and linking thanks to the new 442 control renaming and linking thanks to the new ``LANDLOCK_ACCESS_FS_REFER``
555 access right. 443 access right.
556 444
557 File truncation (ABI < 3) 445 File truncation (ABI < 3)
558 ------------------------- 446 -------------------------
559 447
560 File truncation could not be denied before the 448 File truncation could not be denied before the third Landlock ABI, so it is
561 always allowed when using a kernel that only s 449 always allowed when using a kernel that only supports the first or second ABI.
562 450
563 Starting with the Landlock ABI version 3, it i 451 Starting with the Landlock ABI version 3, it is now possible to securely control
564 truncation thanks to the new ``LANDLOCK_ACCESS 452 truncation thanks to the new ``LANDLOCK_ACCESS_FS_TRUNCATE`` access right.
565 453
566 Network support (ABI < 4) <<
567 ------------------------- <<
568 <<
569 Starting with the Landlock ABI version 4, it i <<
570 bind and connect actions to only a set of allo <<
571 ``LANDLOCK_ACCESS_NET_BIND_TCP`` and ``LANDLOC <<
572 access rights. <<
573 <<
574 IOCTL (ABI < 5) <<
575 --------------- <<
576 <<
577 IOCTL operations could not be denied before th <<
578 :manpage:`ioctl(2)` is always allowed when usi <<
579 earlier ABI. <<
580 <<
581 Starting with the Landlock ABI version 5, it i <<
582 :manpage:`ioctl(2)` using the new ``LANDLOCK_A <<
583 <<
584 Abstract UNIX socket scoping (ABI < 6) <<
585 -------------------------------------- <<
586 <<
587 Starting with the Landlock ABI version 6, it i <<
588 connections to an abstract :manpage:`unix(7)` <<
589 ``LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET`` to the <<
590 <<
591 Signal scoping (ABI < 6) <<
592 ------------------------ <<
593 <<
594 Starting with the Landlock ABI version 6, it i <<
595 :manpage:`signal(7)` sending by setting ``LAND <<
596 ``scoped`` ruleset attribute. <<
597 <<
598 .. _kernel_support: 454 .. _kernel_support:
599 455
600 Kernel support 456 Kernel support
601 ============== 457 ==============
602 458
603 Build time configuration <<
604 ------------------------ <<
605 <<
606 Landlock was first introduced in Linux 5.13 bu 459 Landlock was first introduced in Linux 5.13 but it must be configured at build
607 time with ``CONFIG_SECURITY_LANDLOCK=y``. Lan 460 time with ``CONFIG_SECURITY_LANDLOCK=y``. Landlock must also be enabled at boot
608 time as the other security modules. The list 461 time as the other security modules. The list of security modules enabled by
609 default is set with ``CONFIG_LSM``. The kerne 462 default is set with ``CONFIG_LSM``. The kernel configuration should then
610 contains ``CONFIG_LSM=landlock,[...]`` with `` 463 contains ``CONFIG_LSM=landlock,[...]`` with ``[...]`` as the list of other
611 potentially useful security modules for the ru 464 potentially useful security modules for the running system (see the
612 ``CONFIG_LSM`` help). 465 ``CONFIG_LSM`` help).
613 466
614 Boot time configuration <<
615 ----------------------- <<
616 <<
617 If the running kernel does not have ``landlock 467 If the running kernel does not have ``landlock`` in ``CONFIG_LSM``, then we can
618 enable Landlock by adding ``lsm=landlock,[...] !! 468 still enable it by adding ``lsm=landlock,[...]`` to
619 Documentation/admin-guide/kernel-parameters.rs !! 469 Documentation/admin-guide/kernel-parameters.rst thanks to the bootloader
620 configuration. 470 configuration.
621 <<
622 For example, if the current built-in configura <<
623 <<
624 .. code-block:: console <<
625 <<
626 $ zgrep -h "^CONFIG_LSM=" "/boot/config-$( <<
627 CONFIG_LSM="lockdown,yama,integrity,apparm <<
628 <<
629 ...and if the cmdline doesn't contain ``landlo <<
630 <<
631 .. code-block:: console <<
632 <<
633 $ sed -n 's/.*\(\<lsm=\S\+\).*/\1/p' /proc <<
634 lsm=lockdown,yama,integrity,apparmor <<
635 <<
636 ...we should configure the boot loader to set <<
637 list with the ``landlock,`` prefix:: <<
638 <<
639 lsm=landlock,lockdown,yama,integrity,apparmo <<
640 <<
641 After a reboot, we can check that Landlock is <<
642 kernel logs: <<
643 <<
644 .. code-block:: console <<
645 <<
646 # dmesg | grep landlock || journalctl -kb <<
647 [ 0.000000] Command line: [...] lsm=lan <<
648 [ 0.000000] Kernel command line: [...] <<
649 [ 0.000000] LSM: initializing lsm=lockd <<
650 [ 0.000000] landlock: Up and running. <<
651 <<
652 The kernel may be configured at build time to <<
653 ``capability`` LSMs. In that case, these LSMs <<
654 the ``LSM: initializing`` log line as well, ev <<
655 the boot loader. <<
656 <<
657 Network support <<
658 --------------- <<
659 <<
660 To be able to explicitly allow TCP operations <<
661 ``LANDLOCK_ACCESS_NET_BIND_TCP``), the kernel <<
662 (``CONFIG_INET=y``). Otherwise, sys_landlock_ <<
663 ``EAFNOSUPPORT`` error, which can safely be ig <<
664 operation is already not possible. <<
665 471
666 Questions and answers 472 Questions and answers
667 ===================== 473 =====================
668 474
669 What about user space sandbox managers? 475 What about user space sandbox managers?
670 --------------------------------------- 476 ---------------------------------------
671 477
672 Using user space process to enforce restrictio 478 Using user space process to enforce restrictions on kernel resources can lead
673 to race conditions or inconsistent evaluations 479 to race conditions or inconsistent evaluations (i.e. `Incorrect mirroring of
674 the OS code and state 480 the OS code and state
675 <https://www.ndss-symposium.org/ndss2003/traps 481 <https://www.ndss-symposium.org/ndss2003/traps-and-pitfalls-practical-problems-system-call-interposition-based-security-tools/>`_).
676 482
677 What about namespaces and containers? 483 What about namespaces and containers?
678 ------------------------------------- 484 -------------------------------------
679 485
680 Namespaces can help create sandboxes but they 486 Namespaces can help create sandboxes but they are not designed for
681 access-control and then miss useful features f 487 access-control and then miss useful features for such use case (e.g. no
682 fine-grained restrictions). Moreover, their c 488 fine-grained restrictions). Moreover, their complexity can lead to security
683 issues, especially when untrusted processes ca 489 issues, especially when untrusted processes can manipulate them (cf.
684 `Controlling access to user namespaces <https: 490 `Controlling access to user namespaces <https://lwn.net/Articles/673597/>`_).
685 491
686 Additional documentation 492 Additional documentation
687 ======================== 493 ========================
688 494
689 * Documentation/security/landlock.rst 495 * Documentation/security/landlock.rst
690 * https://landlock.io 496 * https://landlock.io
691 497
692 .. Links 498 .. Links
693 .. _samples/landlock/sandboxer.c: 499 .. _samples/landlock/sandboxer.c:
694 https://git.kernel.org/pub/scm/linux/kernel 500 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/samples/landlock/sandboxer.c
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.