Commit | Line | Data |
---|---|---|
5526b450 MS |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | .. Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net> | |
3 | .. Copyright © 2019-2020 ANSSI | |
5e469829 | 4 | .. Copyright © 2021-2022 Microsoft Corporation |
5526b450 MS |
5 | |
6 | ===================================== | |
7 | Landlock: unprivileged access control | |
8 | ===================================== | |
9 | ||
10 | :Author: Mickaël Salaün | |
6f59abfa | 11 | :Date: May 2022 |
5526b450 MS |
12 | |
13 | The goal of Landlock is to enable to restrict ambient rights (e.g. global | |
14 | filesystem access) for a set of processes. Because Landlock is a stackable | |
15 | LSM, it makes possible to create safe security sandboxes as new security layers | |
16 | in addition to the existing system-wide access-controls. This kind of sandbox | |
17 | is expected to help mitigate the security impact of bugs or | |
18 | unexpected/malicious behaviors in user space applications. Landlock empowers | |
19 | any process, including unprivileged ones, to securely restrict themselves. | |
20 | ||
5e469829 MS |
21 | We can quickly make sure that Landlock is enabled in the running system by |
22 | looking for "landlock: Up and running" in kernel logs (as root): ``dmesg | grep | |
23 | landlock || journalctl -kg landlock`` . Developers can also easily check for | |
24 | Landlock support with a :ref:`related system call <landlock_abi_versions>`. If | |
25 | Landlock is not currently supported, we need to :ref:`configure the kernel | |
26 | appropriately <kernel_support>`. | |
27 | ||
5526b450 MS |
28 | Landlock rules |
29 | ============== | |
30 | ||
31 | A Landlock rule describes an action on an object. An object is currently a | |
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 children. | |
35 | ||
36 | Defining and enforcing a security policy | |
37 | ---------------------------------------- | |
38 | ||
6f59abfa | 39 | We first need to define the ruleset that will contain our rules. For this |
5526b450 MS |
40 | example, the ruleset will contain rules that only allow read actions, but write |
41 | actions will be denied. The ruleset then needs to handle both of these kind of | |
6f59abfa MS |
42 | actions. This is required for backward and forward compatibility (i.e. the |
43 | kernel and user space may not know each other's supported restrictions), hence | |
44 | the need to be explicit about the denied-by-default access rights. | |
5526b450 MS |
45 | |
46 | .. code-block:: c | |
47 | ||
5526b450 MS |
48 | struct landlock_ruleset_attr ruleset_attr = { |
49 | .handled_access_fs = | |
50 | LANDLOCK_ACCESS_FS_EXECUTE | | |
51 | LANDLOCK_ACCESS_FS_WRITE_FILE | | |
52 | LANDLOCK_ACCESS_FS_READ_FILE | | |
53 | LANDLOCK_ACCESS_FS_READ_DIR | | |
54 | LANDLOCK_ACCESS_FS_REMOVE_DIR | | |
55 | LANDLOCK_ACCESS_FS_REMOVE_FILE | | |
56 | LANDLOCK_ACCESS_FS_MAKE_CHAR | | |
57 | LANDLOCK_ACCESS_FS_MAKE_DIR | | |
58 | LANDLOCK_ACCESS_FS_MAKE_REG | | |
59 | LANDLOCK_ACCESS_FS_MAKE_SOCK | | |
60 | LANDLOCK_ACCESS_FS_MAKE_FIFO | | |
61 | LANDLOCK_ACCESS_FS_MAKE_BLOCK | | |
6f59abfa MS |
62 | LANDLOCK_ACCESS_FS_MAKE_SYM | |
63 | LANDLOCK_ACCESS_FS_REFER, | |
5526b450 MS |
64 | }; |
65 | ||
6f59abfa MS |
66 | Because we may not know on which kernel version an application will be |
67 | executed, it is safer to follow a best-effort security approach. Indeed, we | |
68 | should try to protect users as much as possible whatever the kernel they are | |
69 | using. To avoid binary enforcement (i.e. either all security features or | |
70 | none), we can leverage a dedicated Landlock command to get the current version | |
71 | of the Landlock ABI and adapt the handled accesses. Let's check if we should | |
72 | remove the `LANDLOCK_ACCESS_FS_REFER` access right which is only supported | |
73 | starting with the second version of the ABI. | |
74 | ||
75 | .. code-block:: c | |
76 | ||
77 | int abi; | |
78 | ||
79 | abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION); | |
80 | if (abi < 2) { | |
81 | ruleset_attr.handled_access_fs &= ~LANDLOCK_ACCESS_FS_REFER; | |
82 | } | |
83 | ||
84 | This enables to create an inclusive ruleset that will contain our rules. | |
85 | ||
86 | .. code-block:: c | |
87 | ||
88 | int ruleset_fd; | |
89 | ||
5526b450 MS |
90 | ruleset_fd = landlock_create_ruleset(&ruleset_attr, sizeof(ruleset_attr), 0); |
91 | if (ruleset_fd < 0) { | |
92 | perror("Failed to create a ruleset"); | |
93 | return 1; | |
94 | } | |
95 | ||
96 | We can now add a new rule to this ruleset thanks to the returned file | |
97 | descriptor referring to this ruleset. The rule will only allow reading the | |
98 | file hierarchy ``/usr``. Without another rule, write actions would then be | |
99 | denied by the ruleset. To add ``/usr`` to the ruleset, we open it with the | |
100 | ``O_PATH`` flag and fill the &struct landlock_path_beneath_attr with this file | |
101 | descriptor. | |
102 | ||
103 | .. code-block:: c | |
104 | ||
105 | int err; | |
106 | struct landlock_path_beneath_attr path_beneath = { | |
107 | .allowed_access = | |
108 | LANDLOCK_ACCESS_FS_EXECUTE | | |
109 | LANDLOCK_ACCESS_FS_READ_FILE | | |
110 | LANDLOCK_ACCESS_FS_READ_DIR, | |
111 | }; | |
112 | ||
113 | path_beneath.parent_fd = open("/usr", O_PATH | O_CLOEXEC); | |
114 | if (path_beneath.parent_fd < 0) { | |
115 | perror("Failed to open file"); | |
116 | close(ruleset_fd); | |
117 | return 1; | |
118 | } | |
119 | err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_PATH_BENEATH, | |
120 | &path_beneath, 0); | |
121 | close(path_beneath.parent_fd); | |
122 | if (err) { | |
123 | perror("Failed to update ruleset"); | |
124 | close(ruleset_fd); | |
125 | return 1; | |
126 | } | |
127 | ||
6f59abfa MS |
128 | It may also be required to create rules following the same logic as explained |
129 | for the ruleset creation, by filtering access rights according to the Landlock | |
130 | ABI version. In this example, this is not required because | |
131 | `LANDLOCK_ACCESS_FS_REFER` is not allowed by any rule. | |
132 | ||
5526b450 MS |
133 | We now have a ruleset with one rule allowing read access to ``/usr`` while |
134 | denying all other handled accesses for the filesystem. The next step is to | |
135 | restrict the current thread from gaining more privileges (e.g. thanks to a SUID | |
136 | binary). | |
137 | ||
138 | .. code-block:: c | |
139 | ||
140 | if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) { | |
141 | perror("Failed to restrict privileges"); | |
142 | close(ruleset_fd); | |
143 | return 1; | |
144 | } | |
145 | ||
146 | The current thread is now ready to sandbox itself with the ruleset. | |
147 | ||
148 | .. code-block:: c | |
149 | ||
150 | if (landlock_restrict_self(ruleset_fd, 0)) { | |
151 | perror("Failed to enforce ruleset"); | |
152 | close(ruleset_fd); | |
153 | return 1; | |
154 | } | |
155 | close(ruleset_fd); | |
156 | ||
157 | If the `landlock_restrict_self` system call succeeds, the current thread is now | |
158 | restricted and this policy will be enforced on all its subsequently created | |
159 | children as well. Once a thread is landlocked, there is no way to remove its | |
160 | security policy; only adding more restrictions is allowed. These threads are | |
161 | now in a new Landlock domain, merge of their parent one (if any) with the new | |
162 | ruleset. | |
163 | ||
164 | Full working code can be found in `samples/landlock/sandboxer.c`_. | |
165 | ||
09340cf4 MS |
166 | Good practices |
167 | -------------- | |
168 | ||
169 | It is recommended setting access rights to file hierarchy leaves as much as | |
170 | possible. For instance, it is better to be able to have ``~/doc/`` as a | |
171 | read-only hierarchy and ``~/tmp/`` as a read-write hierarchy, compared to | |
172 | ``~/`` as a read-only hierarchy and ``~/tmp/`` as a read-write hierarchy. | |
173 | Following this good practice leads to self-sufficient hierarchies that don't | |
174 | depend on their location (i.e. parent directories). This is particularly | |
175 | relevant when we want to allow linking or renaming. Indeed, having consistent | |
176 | access rights per directory enables to change the location of such directory | |
177 | without relying on the destination directory access rights (except those that | |
178 | are required for this operation, see `LANDLOCK_ACCESS_FS_REFER` documentation). | |
179 | Having self-sufficient hierarchies also helps to tighten the required access | |
180 | rights to the minimal set of data. This also helps avoid sinkhole directories, | |
181 | i.e. directories where data can be linked to but not linked from. However, | |
182 | this depends on data organization, which might not be controlled by developers. | |
183 | In this case, granting read-write access to ``~/tmp/``, instead of write-only | |
184 | access, would potentially allow to move ``~/tmp/`` to a non-readable directory | |
185 | and still keep the ability to list the content of ``~/tmp/``. | |
186 | ||
5526b450 MS |
187 | Layers of file path access rights |
188 | --------------------------------- | |
189 | ||
190 | Each time a thread enforces a ruleset on itself, it updates its Landlock domain | |
191 | with a new layer of policy. Indeed, this complementary policy is stacked with | |
192 | the potentially other rulesets already restricting this thread. A sandboxed | |
193 | thread can then safely add more constraints to itself with a new enforced | |
194 | ruleset. | |
195 | ||
196 | One policy layer grants access to a file path if at least one of its rules | |
197 | encountered on the path grants the access. A sandboxed thread can only access | |
198 | a file path if all its enforced policy layers grant the access as well as all | |
199 | the other system access controls (e.g. filesystem DAC, other LSM policies, | |
200 | etc.). | |
201 | ||
202 | Bind mounts and OverlayFS | |
203 | ------------------------- | |
204 | ||
205 | Landlock enables to restrict access to file hierarchies, which means that these | |
206 | access rights can be propagated with bind mounts (cf. | |
69fe5540 MCC |
207 | Documentation/filesystems/sharedsubtree.rst) but not with |
208 | Documentation/filesystems/overlayfs.rst. | |
5526b450 MS |
209 | |
210 | A bind mount mirrors a source file hierarchy to a destination. The destination | |
211 | hierarchy is then composed of the exact same files, on which Landlock rules can | |
212 | be tied, either via the source or the destination path. These rules restrict | |
213 | access when they are encountered on a path, which means that they can restrict | |
214 | access to multiple file hierarchies at the same time, whether these hierarchies | |
215 | are the result of bind mounts or not. | |
216 | ||
217 | An OverlayFS mount point consists of upper and lower layers. These layers are | |
218 | combined in a merge directory, result of the mount point. This merge hierarchy | |
219 | may include files from the upper and lower layers, but modifications performed | |
220 | on the merge hierarchy only reflects on the upper layer. From a Landlock | |
221 | policy point of view, each OverlayFS layers and merge hierarchies are | |
222 | standalone and contains their own set of files and directories, which is | |
223 | different from bind mounts. A policy restricting an OverlayFS layer will not | |
224 | restrict the resulted merged hierarchy, and vice versa. Landlock users should | |
225 | then only think about file hierarchies they want to allow access to, regardless | |
226 | of the underlying filesystem. | |
227 | ||
228 | Inheritance | |
229 | ----------- | |
230 | ||
231 | Every new thread resulting from a :manpage:`clone(2)` inherits Landlock domain | |
232 | restrictions from its parent. This is similar to the seccomp inheritance (cf. | |
69fe5540 MCC |
233 | Documentation/userspace-api/seccomp_filter.rst) or any other LSM dealing with |
234 | task's :manpage:`credentials(7)`. For instance, one process's thread may apply | |
5526b450 MS |
235 | Landlock rules to itself, but they will not be automatically applied to other |
236 | sibling threads (unlike POSIX thread credential changes, cf. | |
237 | :manpage:`nptl(7)`). | |
238 | ||
239 | When a thread sandboxes itself, we have the guarantee that the related security | |
240 | policy will stay enforced on all this thread's descendants. This allows | |
241 | creating standalone and modular security policies per application, which will | |
242 | automatically be composed between themselves according to their runtime parent | |
243 | policies. | |
244 | ||
245 | Ptrace restrictions | |
246 | ------------------- | |
247 | ||
248 | A sandboxed process has less privileges than a non-sandboxed process and must | |
249 | then be subject to additional restrictions when manipulating another process. | |
250 | To be allowed to use :manpage:`ptrace(2)` and related syscalls on a target | |
251 | process, a sandboxed process should have a subset of the target process rules, | |
252 | which means the tracee must be in a sub-domain of the tracer. | |
253 | ||
6f59abfa MS |
254 | Compatibility |
255 | ============= | |
256 | ||
257 | Backward and forward compatibility | |
258 | ---------------------------------- | |
259 | ||
260 | Landlock is designed to be compatible with past and future versions of the | |
261 | kernel. This is achieved thanks to the system call attributes and the | |
262 | associated bitflags, particularly the ruleset's `handled_access_fs`. Making | |
263 | handled access right explicit enables the kernel and user space to have a clear | |
264 | contract with each other. This is required to make sure sandboxing will not | |
265 | get stricter with a system update, which could break applications. | |
266 | ||
267 | Developers can subscribe to the `Landlock mailing list | |
268 | <https://subspace.kernel.org/lists.linux.dev.html>`_ to knowingly update and | |
269 | test their applications with the latest available features. In the interest of | |
270 | users, and because they may use different kernel versions, it is strongly | |
271 | encouraged to follow a best-effort security approach by checking the Landlock | |
272 | ABI version at runtime and only enforcing the supported features. | |
273 | ||
5e469829 MS |
274 | .. _landlock_abi_versions: |
275 | ||
6f59abfa MS |
276 | Landlock ABI versions |
277 | --------------------- | |
278 | ||
279 | The Landlock ABI version can be read with the sys_landlock_create_ruleset() | |
280 | system call: | |
281 | ||
282 | .. code-block:: c | |
283 | ||
284 | int abi; | |
285 | ||
286 | abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION); | |
287 | if (abi < 0) { | |
288 | switch (errno) { | |
289 | case ENOSYS: | |
290 | printf("Landlock is not supported by the current kernel.\n"); | |
291 | break; | |
292 | case EOPNOTSUPP: | |
293 | printf("Landlock is currently disabled.\n"); | |
294 | break; | |
295 | } | |
296 | return 0; | |
297 | } | |
298 | if (abi >= 2) { | |
299 | printf("Landlock supports LANDLOCK_ACCESS_FS_REFER.\n"); | |
300 | } | |
301 | ||
302 | The following kernel interfaces are implicitly supported by the first ABI | |
303 | version. Features only supported from a specific version are explicitly marked | |
304 | as such. | |
305 | ||
5526b450 MS |
306 | Kernel interface |
307 | ================ | |
308 | ||
309 | Access rights | |
310 | ------------- | |
311 | ||
312 | .. kernel-doc:: include/uapi/linux/landlock.h | |
313 | :identifiers: fs_access | |
314 | ||
315 | Creating a new ruleset | |
316 | ---------------------- | |
317 | ||
318 | .. kernel-doc:: security/landlock/syscalls.c | |
319 | :identifiers: sys_landlock_create_ruleset | |
320 | ||
321 | .. kernel-doc:: include/uapi/linux/landlock.h | |
322 | :identifiers: landlock_ruleset_attr | |
323 | ||
324 | Extending a ruleset | |
325 | ------------------- | |
326 | ||
327 | .. kernel-doc:: security/landlock/syscalls.c | |
328 | :identifiers: sys_landlock_add_rule | |
329 | ||
330 | .. kernel-doc:: include/uapi/linux/landlock.h | |
331 | :identifiers: landlock_rule_type landlock_path_beneath_attr | |
332 | ||
333 | Enforcing a ruleset | |
334 | ------------------- | |
335 | ||
336 | .. kernel-doc:: security/landlock/syscalls.c | |
337 | :identifiers: sys_landlock_restrict_self | |
338 | ||
339 | Current limitations | |
340 | =================== | |
341 | ||
5526b450 MS |
342 | Filesystem topology modification |
343 | -------------------------------- | |
344 | ||
345 | As for file renaming and linking, a sandboxed thread cannot modify its | |
346 | filesystem topology, whether via :manpage:`mount(2)` or | |
347 | :manpage:`pivot_root(2)`. However, :manpage:`chroot(2)` calls are not denied. | |
348 | ||
349 | Special filesystems | |
350 | ------------------- | |
351 | ||
352 | Access to regular files and directories can be restricted by Landlock, | |
353 | according to the handled accesses of a ruleset. However, files that do not | |
354 | come from a user-visible filesystem (e.g. pipe, socket), but can still be | |
355 | accessed through ``/proc/<pid>/fd/*``, cannot currently be explicitly | |
356 | restricted. Likewise, some special kernel filesystems such as nsfs, which can | |
357 | be accessed through ``/proc/<pid>/ns/*``, cannot currently be explicitly | |
358 | restricted. However, thanks to the `ptrace restrictions`_, access to such | |
359 | sensitive ``/proc`` files are automatically restricted according to domain | |
360 | hierarchies. Future Landlock evolutions could still enable to explicitly | |
361 | restrict such paths with dedicated ruleset flags. | |
362 | ||
363 | Ruleset layers | |
364 | -------------- | |
365 | ||
75c542d6 MS |
366 | There is a limit of 16 layers of stacked rulesets. This can be an issue for a |
367 | task willing to enforce a new ruleset in complement to its 16 inherited | |
5526b450 MS |
368 | rulesets. Once this limit is reached, sys_landlock_restrict_self() returns |
369 | E2BIG. It is then strongly suggested to carefully build rulesets once in the | |
370 | life of a thread, especially for applications able to launch other applications | |
371 | that may also want to sandbox themselves (e.g. shells, container managers, | |
372 | etc.). | |
373 | ||
374 | Memory usage | |
375 | ------------ | |
376 | ||
377 | Kernel memory allocated to create rulesets is accounted and can be restricted | |
69fe5540 | 378 | by the Documentation/admin-guide/cgroup-v1/memory.rst. |
5526b450 | 379 | |
6f59abfa MS |
380 | Previous limitations |
381 | ==================== | |
382 | ||
383 | File renaming and linking (ABI 1) | |
384 | --------------------------------- | |
385 | ||
386 | Because Landlock targets unprivileged access controls, it needs to properly | |
387 | handle composition of rules. Such property also implies rules nesting. | |
388 | Properly handling multiple layers of rulesets, each one of them able to | |
389 | restrict access to files, also implies inheritance of the ruleset restrictions | |
390 | from a parent to its hierarchy. Because files are identified and restricted by | |
391 | their hierarchy, moving or linking a file from one directory to another implies | |
392 | propagation of the hierarchy constraints, or restriction of these actions | |
393 | according to the potentially lost constraints. To protect against privilege | |
394 | escalations through renaming or linking, and for the sake of simplicity, | |
395 | Landlock previously limited linking and renaming to the same directory. | |
396 | Starting with the Landlock ABI version 2, it is now possible to securely | |
397 | control renaming and linking thanks to the new `LANDLOCK_ACCESS_FS_REFER` | |
398 | access right. | |
399 | ||
5e469829 MS |
400 | .. _kernel_support: |
401 | ||
402 | Kernel support | |
403 | ============== | |
404 | ||
405 | Landlock was first introduced in Linux 5.13 but it must be configured at build | |
406 | time with `CONFIG_SECURITY_LANDLOCK=y`. Landlock must also be enabled at boot | |
407 | time as the other security modules. The list of security modules enabled by | |
408 | default is set with `CONFIG_LSM`. The kernel configuration should then | |
409 | contains `CONFIG_LSM=landlock,[...]` with `[...]` as the list of other | |
410 | potentially useful security modules for the running system (see the | |
411 | `CONFIG_LSM` help). | |
412 | ||
413 | If the running kernel doesn't have `landlock` in `CONFIG_LSM`, then we can | |
414 | still enable it by adding ``lsm=landlock,[...]`` to | |
415 | Documentation/admin-guide/kernel-parameters.rst thanks to the bootloader | |
416 | configuration. | |
417 | ||
5526b450 MS |
418 | Questions and answers |
419 | ===================== | |
420 | ||
421 | What about user space sandbox managers? | |
422 | --------------------------------------- | |
423 | ||
424 | Using user space process to enforce restrictions on kernel resources can lead | |
425 | to race conditions or inconsistent evaluations (i.e. `Incorrect mirroring of | |
426 | the OS code and state | |
427 | <https://www.ndss-symposium.org/ndss2003/traps-and-pitfalls-practical-problems-system-call-interposition-based-security-tools/>`_). | |
428 | ||
429 | What about namespaces and containers? | |
430 | ------------------------------------- | |
431 | ||
432 | Namespaces can help create sandboxes but they are not designed for | |
433 | access-control and then miss useful features for such use case (e.g. no | |
434 | fine-grained restrictions). Moreover, their complexity can lead to security | |
435 | issues, especially when untrusted processes can manipulate them (cf. | |
436 | `Controlling access to user namespaces <https://lwn.net/Articles/673597/>`_). | |
437 | ||
438 | Additional documentation | |
439 | ======================== | |
440 | ||
69fe5540 | 441 | * Documentation/security/landlock.rst |
5526b450 MS |
442 | * https://landlock.io |
443 | ||
444 | .. Links | |
445 | .. _samples/landlock/sandboxer.c: | |
446 | https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/samples/landlock/sandboxer.c |