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 | |
16023b05 | 11 | :Date: September 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 | |
2fff00c8 | 72 | remove the ``LANDLOCK_ACCESS_FS_REFER`` access right which is only supported |
6f59abfa MS |
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 | |
2fff00c8 | 131 | ``LANDLOCK_ACCESS_FS_REFER`` is not allowed by any rule. |
6f59abfa | 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 | ||
2fff00c8 MS |
157 | If the ``landlock_restrict_self`` system call succeeds, the current thread is |
158 | now restricted and this policy will be enforced on all its subsequently created | |
5526b450 MS |
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. | |
16023b05 | 173 | Following this good practice leads to self-sufficient hierarchies that do not |
09340cf4 MS |
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 | |
2fff00c8 MS |
178 | are required for this operation, see ``LANDLOCK_ACCESS_FS_REFER`` |
179 | documentation). | |
09340cf4 MS |
180 | Having self-sufficient hierarchies also helps to tighten the required access |
181 | rights to the minimal set of data. This also helps avoid sinkhole directories, | |
182 | i.e. directories where data can be linked to but not linked from. However, | |
183 | this depends on data organization, which might not be controlled by developers. | |
184 | In this case, granting read-write access to ``~/tmp/``, instead of write-only | |
185 | access, would potentially allow to move ``~/tmp/`` to a non-readable directory | |
186 | and still keep the ability to list the content of ``~/tmp/``. | |
187 | ||
5526b450 MS |
188 | Layers of file path access rights |
189 | --------------------------------- | |
190 | ||
191 | Each time a thread enforces a ruleset on itself, it updates its Landlock domain | |
192 | with a new layer of policy. Indeed, this complementary policy is stacked with | |
193 | the potentially other rulesets already restricting this thread. A sandboxed | |
194 | thread can then safely add more constraints to itself with a new enforced | |
195 | ruleset. | |
196 | ||
197 | One policy layer grants access to a file path if at least one of its rules | |
198 | encountered on the path grants the access. A sandboxed thread can only access | |
199 | a file path if all its enforced policy layers grant the access as well as all | |
200 | the other system access controls (e.g. filesystem DAC, other LSM policies, | |
201 | etc.). | |
202 | ||
203 | Bind mounts and OverlayFS | |
204 | ------------------------- | |
205 | ||
206 | Landlock enables to restrict access to file hierarchies, which means that these | |
207 | access rights can be propagated with bind mounts (cf. | |
69fe5540 MCC |
208 | Documentation/filesystems/sharedsubtree.rst) but not with |
209 | Documentation/filesystems/overlayfs.rst. | |
5526b450 MS |
210 | |
211 | A bind mount mirrors a source file hierarchy to a destination. The destination | |
212 | hierarchy is then composed of the exact same files, on which Landlock rules can | |
213 | be tied, either via the source or the destination path. These rules restrict | |
214 | access when they are encountered on a path, which means that they can restrict | |
215 | access to multiple file hierarchies at the same time, whether these hierarchies | |
216 | are the result of bind mounts or not. | |
217 | ||
218 | An OverlayFS mount point consists of upper and lower layers. These layers are | |
219 | combined in a merge directory, result of the mount point. This merge hierarchy | |
220 | may include files from the upper and lower layers, but modifications performed | |
221 | on the merge hierarchy only reflects on the upper layer. From a Landlock | |
222 | policy point of view, each OverlayFS layers and merge hierarchies are | |
223 | standalone and contains their own set of files and directories, which is | |
224 | different from bind mounts. A policy restricting an OverlayFS layer will not | |
225 | restrict the resulted merged hierarchy, and vice versa. Landlock users should | |
226 | then only think about file hierarchies they want to allow access to, regardless | |
227 | of the underlying filesystem. | |
228 | ||
229 | Inheritance | |
230 | ----------- | |
231 | ||
232 | Every new thread resulting from a :manpage:`clone(2)` inherits Landlock domain | |
233 | restrictions from its parent. This is similar to the seccomp inheritance (cf. | |
69fe5540 MCC |
234 | Documentation/userspace-api/seccomp_filter.rst) or any other LSM dealing with |
235 | task's :manpage:`credentials(7)`. For instance, one process's thread may apply | |
5526b450 MS |
236 | Landlock rules to itself, but they will not be automatically applied to other |
237 | sibling threads (unlike POSIX thread credential changes, cf. | |
238 | :manpage:`nptl(7)`). | |
239 | ||
240 | When a thread sandboxes itself, we have the guarantee that the related security | |
241 | policy will stay enforced on all this thread's descendants. This allows | |
242 | creating standalone and modular security policies per application, which will | |
243 | automatically be composed between themselves according to their runtime parent | |
244 | policies. | |
245 | ||
246 | Ptrace restrictions | |
247 | ------------------- | |
248 | ||
249 | A sandboxed process has less privileges than a non-sandboxed process and must | |
250 | then be subject to additional restrictions when manipulating another process. | |
251 | To be allowed to use :manpage:`ptrace(2)` and related syscalls on a target | |
252 | process, a sandboxed process should have a subset of the target process rules, | |
253 | which means the tracee must be in a sub-domain of the tracer. | |
254 | ||
6f59abfa MS |
255 | Compatibility |
256 | ============= | |
257 | ||
258 | Backward and forward compatibility | |
259 | ---------------------------------- | |
260 | ||
261 | Landlock is designed to be compatible with past and future versions of the | |
262 | kernel. This is achieved thanks to the system call attributes and the | |
2fff00c8 | 263 | associated bitflags, particularly the ruleset's ``handled_access_fs``. Making |
6f59abfa MS |
264 | handled access right explicit enables the kernel and user space to have a clear |
265 | contract with each other. This is required to make sure sandboxing will not | |
266 | get stricter with a system update, which could break applications. | |
267 | ||
268 | Developers can subscribe to the `Landlock mailing list | |
269 | <https://subspace.kernel.org/lists.linux.dev.html>`_ to knowingly update and | |
270 | test their applications with the latest available features. In the interest of | |
271 | users, and because they may use different kernel versions, it is strongly | |
272 | encouraged to follow a best-effort security approach by checking the Landlock | |
273 | ABI version at runtime and only enforcing the supported features. | |
274 | ||
5e469829 MS |
275 | .. _landlock_abi_versions: |
276 | ||
6f59abfa MS |
277 | Landlock ABI versions |
278 | --------------------- | |
279 | ||
280 | The Landlock ABI version can be read with the sys_landlock_create_ruleset() | |
281 | system call: | |
282 | ||
283 | .. code-block:: c | |
284 | ||
285 | int abi; | |
286 | ||
287 | abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION); | |
288 | if (abi < 0) { | |
289 | switch (errno) { | |
290 | case ENOSYS: | |
291 | printf("Landlock is not supported by the current kernel.\n"); | |
292 | break; | |
293 | case EOPNOTSUPP: | |
294 | printf("Landlock is currently disabled.\n"); | |
295 | break; | |
296 | } | |
297 | return 0; | |
298 | } | |
299 | if (abi >= 2) { | |
300 | printf("Landlock supports LANDLOCK_ACCESS_FS_REFER.\n"); | |
301 | } | |
302 | ||
303 | The following kernel interfaces are implicitly supported by the first ABI | |
304 | version. Features only supported from a specific version are explicitly marked | |
305 | as such. | |
306 | ||
5526b450 MS |
307 | Kernel interface |
308 | ================ | |
309 | ||
310 | Access rights | |
311 | ------------- | |
312 | ||
313 | .. kernel-doc:: include/uapi/linux/landlock.h | |
314 | :identifiers: fs_access | |
315 | ||
316 | Creating a new ruleset | |
317 | ---------------------- | |
318 | ||
319 | .. kernel-doc:: security/landlock/syscalls.c | |
320 | :identifiers: sys_landlock_create_ruleset | |
321 | ||
322 | .. kernel-doc:: include/uapi/linux/landlock.h | |
323 | :identifiers: landlock_ruleset_attr | |
324 | ||
325 | Extending a ruleset | |
326 | ------------------- | |
327 | ||
328 | .. kernel-doc:: security/landlock/syscalls.c | |
329 | :identifiers: sys_landlock_add_rule | |
330 | ||
331 | .. kernel-doc:: include/uapi/linux/landlock.h | |
332 | :identifiers: landlock_rule_type landlock_path_beneath_attr | |
333 | ||
334 | Enforcing a ruleset | |
335 | ------------------- | |
336 | ||
337 | .. kernel-doc:: security/landlock/syscalls.c | |
338 | :identifiers: sys_landlock_restrict_self | |
339 | ||
340 | Current limitations | |
341 | =================== | |
342 | ||
5526b450 MS |
343 | Filesystem topology modification |
344 | -------------------------------- | |
345 | ||
346 | As for file renaming and linking, a sandboxed thread cannot modify its | |
347 | filesystem topology, whether via :manpage:`mount(2)` or | |
348 | :manpage:`pivot_root(2)`. However, :manpage:`chroot(2)` calls are not denied. | |
349 | ||
350 | Special filesystems | |
351 | ------------------- | |
352 | ||
353 | Access to regular files and directories can be restricted by Landlock, | |
354 | according to the handled accesses of a ruleset. However, files that do not | |
355 | come from a user-visible filesystem (e.g. pipe, socket), but can still be | |
356 | accessed through ``/proc/<pid>/fd/*``, cannot currently be explicitly | |
357 | restricted. Likewise, some special kernel filesystems such as nsfs, which can | |
358 | be accessed through ``/proc/<pid>/ns/*``, cannot currently be explicitly | |
359 | restricted. However, thanks to the `ptrace restrictions`_, access to such | |
360 | sensitive ``/proc`` files are automatically restricted according to domain | |
361 | hierarchies. Future Landlock evolutions could still enable to explicitly | |
362 | restrict such paths with dedicated ruleset flags. | |
363 | ||
364 | Ruleset layers | |
365 | -------------- | |
366 | ||
75c542d6 MS |
367 | There is a limit of 16 layers of stacked rulesets. This can be an issue for a |
368 | task willing to enforce a new ruleset in complement to its 16 inherited | |
5526b450 MS |
369 | rulesets. Once this limit is reached, sys_landlock_restrict_self() returns |
370 | E2BIG. It is then strongly suggested to carefully build rulesets once in the | |
371 | life of a thread, especially for applications able to launch other applications | |
372 | that may also want to sandbox themselves (e.g. shells, container managers, | |
373 | etc.). | |
374 | ||
375 | Memory usage | |
376 | ------------ | |
377 | ||
378 | Kernel memory allocated to create rulesets is accounted and can be restricted | |
69fe5540 | 379 | by the Documentation/admin-guide/cgroup-v1/memory.rst. |
5526b450 | 380 | |
6f59abfa MS |
381 | Previous limitations |
382 | ==================== | |
383 | ||
16023b05 MS |
384 | File renaming and linking (ABI < 2) |
385 | ----------------------------------- | |
6f59abfa MS |
386 | |
387 | Because Landlock targets unprivileged access controls, it needs to properly | |
388 | handle composition of rules. Such property also implies rules nesting. | |
389 | Properly handling multiple layers of rulesets, each one of them able to | |
390 | restrict access to files, also implies inheritance of the ruleset restrictions | |
391 | from a parent to its hierarchy. Because files are identified and restricted by | |
392 | their hierarchy, moving or linking a file from one directory to another implies | |
393 | propagation of the hierarchy constraints, or restriction of these actions | |
394 | according to the potentially lost constraints. To protect against privilege | |
395 | escalations through renaming or linking, and for the sake of simplicity, | |
396 | Landlock previously limited linking and renaming to the same directory. | |
397 | Starting with the Landlock ABI version 2, it is now possible to securely | |
2fff00c8 | 398 | control renaming and linking thanks to the new ``LANDLOCK_ACCESS_FS_REFER`` |
6f59abfa MS |
399 | access right. |
400 | ||
5e469829 MS |
401 | .. _kernel_support: |
402 | ||
403 | Kernel support | |
404 | ============== | |
405 | ||
406 | Landlock was first introduced in Linux 5.13 but it must be configured at build | |
2fff00c8 | 407 | time with ``CONFIG_SECURITY_LANDLOCK=y``. Landlock must also be enabled at boot |
5e469829 | 408 | time as the other security modules. The list of security modules enabled by |
2fff00c8 MS |
409 | default is set with ``CONFIG_LSM``. The kernel configuration should then |
410 | contains ``CONFIG_LSM=landlock,[...]`` with ``[...]`` as the list of other | |
5e469829 | 411 | potentially useful security modules for the running system (see the |
2fff00c8 | 412 | ``CONFIG_LSM`` help). |
5e469829 | 413 | |
2fff00c8 | 414 | If the running kernel does not have ``landlock`` in ``CONFIG_LSM``, then we can |
5e469829 MS |
415 | still enable it by adding ``lsm=landlock,[...]`` to |
416 | Documentation/admin-guide/kernel-parameters.rst thanks to the bootloader | |
417 | configuration. | |
418 | ||
5526b450 MS |
419 | Questions and answers |
420 | ===================== | |
421 | ||
422 | What about user space sandbox managers? | |
423 | --------------------------------------- | |
424 | ||
425 | Using user space process to enforce restrictions on kernel resources can lead | |
426 | to race conditions or inconsistent evaluations (i.e. `Incorrect mirroring of | |
427 | the OS code and state | |
428 | <https://www.ndss-symposium.org/ndss2003/traps-and-pitfalls-practical-problems-system-call-interposition-based-security-tools/>`_). | |
429 | ||
430 | What about namespaces and containers? | |
431 | ------------------------------------- | |
432 | ||
433 | Namespaces can help create sandboxes but they are not designed for | |
434 | access-control and then miss useful features for such use case (e.g. no | |
435 | fine-grained restrictions). Moreover, their complexity can lead to security | |
436 | issues, especially when untrusted processes can manipulate them (cf. | |
437 | `Controlling access to user namespaces <https://lwn.net/Articles/673597/>`_). | |
438 | ||
439 | Additional documentation | |
440 | ======================== | |
441 | ||
69fe5540 | 442 | * Documentation/security/landlock.rst |
5526b450 MS |
443 | * https://landlock.io |
444 | ||
445 | .. Links | |
446 | .. _samples/landlock/sandboxer.c: | |
447 | https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/samples/landlock/sandboxer.c |