From: Mickaël Salaün <mic@xxxxxxxxxxxxxxxxxxx> >From the user point of view, Landlock is a set of system calls enabling to build and enforce a set of access-control rules. A ruleset can be created with landlock_create_ruleset(2), populated with landlock_add_rule(2) and enforced with landlock_restrict_self(2). This man page gives an overview of the whole mechanism. Details of these system calls are documented in their respective man pages. This is an adaptation of https://www.kernel.org/doc/html/v5.13/userspace-api/landlock.html Signed-off-by: Mickaël Salaün <mic@xxxxxxxxxxxxxxxxxxx> Link: https://lore.kernel.org/r/20210706182217.32338-2-mic@xxxxxxxxxxx --- man7/landlock.7 | 354 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 354 insertions(+) create mode 100644 man7/landlock.7 diff --git a/man7/landlock.7 b/man7/landlock.7 new file mode 100644 index 000000000000..32127d3b2061 --- /dev/null +++ b/man7/landlock.7 @@ -0,0 +1,354 @@ +.\" Copyright © 2017-2020 Mickaël Salaün <mic@xxxxxxxxxxx> +.\" Copyright © 2019-2020 ANSSI +.\" Copyright © 2021 Microsoft Corporation +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH LANDLOCK 7 2021-06-27 Linux "Linux Programmer's Manual" +.SH NAME +Landlock \- security sandboxing +.SH DESCRIPTION +Landlock is a sandboxing mechanism that enables any processes to securely +restrict themselves and their future children. +Because Landlock is a stackable LSM, it makes possible to create safe +security sandboxes as new security layers in addition to the existing +system-wide access-controls. This kind of sandbox is expected to help +mitigate the security impact of bugs, and unexpected or malicious behaviors +in applications. +.PP +A Landlock security policy is a set of access rights (e.g., open a file in +read-only, make a directory, etc.) tied to a file hierarchy. Such policy +can be configured and enforced by processes for themselves using three +system calls: +.IP \(bu 2 +.BR landlock_create_ruleset (2) +creates a new ruleset; +.IP \(bu +.BR landlock_add_rule (2) +adds a new rule to a ruleset; +.IP \(bu +.BR landlock_restrict_self (2) +enforces a ruleset on the calling thread. +.PP +To be able to use these system calls, the running kernel must support +Landlock and it must be enabled at boot time. +.\" +.SS Landlock rules +A Landlock rule describes an action on an object. An object is currently a +file hierarchy, and the related filesystem actions are defined with access +rights (see +.BR landlock_add_rule (2) +). A set of rules is aggregated in a ruleset, which can +then restrict the thread enforcing it, and its future children. +.\" +.SS Defining and enforcing a security policy +We first need to create the ruleset that will contain our rules. For this +example, the ruleset will contain rules that only allow read actions, but +write actions will be denied. The ruleset then needs to handle both of +these kind of actions. See below for the description of filesystem +actions. +.PP +.in +4n +.EX +int ruleset_fd; +struct landlock_ruleset_attr ruleset_attr = { + .handled_access_fs = + LANDLOCK_ACCESS_FS_EXECUTE | + LANDLOCK_ACCESS_FS_WRITE_FILE | + LANDLOCK_ACCESS_FS_READ_FILE | + LANDLOCK_ACCESS_FS_READ_DIR | + LANDLOCK_ACCESS_FS_REMOVE_DIR | + LANDLOCK_ACCESS_FS_REMOVE_FILE | + LANDLOCK_ACCESS_FS_MAKE_CHAR | + LANDLOCK_ACCESS_FS_MAKE_DIR | + LANDLOCK_ACCESS_FS_MAKE_REG | + LANDLOCK_ACCESS_FS_MAKE_SOCK | + LANDLOCK_ACCESS_FS_MAKE_FIFO | + LANDLOCK_ACCESS_FS_MAKE_BLOCK | + LANDLOCK_ACCESS_FS_MAKE_SYM, +}; + +ruleset_fd = landlock_create_ruleset(&ruleset_attr, sizeof(ruleset_attr), 0); +if (ruleset_fd < 0) { + perror("Failed to create a ruleset"); + return 1; +} +.EE +.in +.PP +We can now add a new rule to this ruleset thanks to the returned file +descriptor referring to this ruleset. The rule will only allow reading the +file hierarchy +.I /usr +\&. Without another rule, write actions would then be denied by the +ruleset. To add +.I /usr +to the ruleset, we open it with the +.I O_PATH +flag and fill the +.I struct landlock_path_beneath_attr +with this file descriptor. +.PP +.in +4n +.EX +int err; +struct landlock_path_beneath_attr path_beneath = { + .allowed_access = + LANDLOCK_ACCESS_FS_EXECUTE | + LANDLOCK_ACCESS_FS_READ_FILE | + LANDLOCK_ACCESS_FS_READ_DIR, +}; + +path_beneath.parent_fd = open("/usr", O_PATH | O_CLOEXEC); +if (path_beneath.parent_fd < 0) { + perror("Failed to open file"); + close(ruleset_fd); + return 1; +} +err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_PATH_BENEATH, + &path_beneath, 0); +close(path_beneath.parent_fd); +if (err) { + perror("Failed to update ruleset"); + close(ruleset_fd); + return 1; +} +.EE +.in +.PP +We now have a ruleset with one rule allowing read access to +.I /usr +while denying all other handled accesses for the filesystem. The next step +is to restrict the current thread from gaining more privileges (e.g., +thanks to a set-user-ID binary). +.PP +.in +4n +.EX +if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) { + perror("Failed to restrict privileges"); + close(ruleset_fd); + return 1; +} +.EE +.in +.PP +The current thread is now ready to sandbox itself with the ruleset. +.PP +.in +4n +.EX +if (landlock_restrict_self(ruleset_fd, 0)) { + perror("Failed to enforce ruleset"); + close(ruleset_fd); + return 1; +} +close(ruleset_fd); +.EE +.in +.PP +If the +.BR landlock_restrict_self (2) +system call succeeds, the current thread is now restricted and this policy +will be enforced on all its subsequently created children as well. Once a +thread is landlocked, there is no way to remove its security policy; only +adding more restrictions is allowed. These threads are now in a new +Landlock domain, merge of their parent one (if any) with the new ruleset. +.PP +Full working code can be found in +.UR https://git.kernel.org\:/pub\:/scm\:/linux\:/kernel\:/git\:/stable\:/linux.git\:/tree\:/samples\:/landlock\:/sandboxer.c +.UE +.\" +.SS Filesystem actions +These flags enable to restrict a sandboxed process to a set of actions on +files and directories. Files or directories opened before the sandboxing +are not subject to these restrictions. See +.BR landlock_add_rule (2) +and +.BR landlock_create_ruleset (2) +for more context. +.PP +A file can only receive these access rights: +.TP +.BR LANDLOCK_ACCESS_FS_EXECUTE +Execute a file. +.TP +.BR LANDLOCK_ACCESS_FS_WRITE_FILE +Open a file with write access. +.TP +.BR LANDLOCK_ACCESS_FS_READ_FILE +Open a file with read access. +.PP +A directory can receive access rights related to files or directories. The +following access right is applied to the directory itself, and the +directories beneath it: +.TP +.BR LANDLOCK_ACCESS_FS_READ_DIR +Open a directory or list its content. +.PP +However, the following access rights only apply to the content of a +directory, not the directory itself: +.TP +.BR LANDLOCK_ACCESS_FS_REMOVE_DIR +Remove an empty directory or rename one. +.TP +.BR LANDLOCK_ACCESS_FS_REMOVE_FILE +Unlink (or rename) a file. +.TP +.BR LANDLOCK_ACCESS_FS_MAKE_CHAR +Create (or rename or link) a character device. +.TP +.BR LANDLOCK_ACCESS_FS_MAKE_DIR +Create (or rename) a directory. +.TP +.BR LANDLOCK_ACCESS_FS_MAKE_REG +Create (or rename or link) a regular file. +.TP +.BR LANDLOCK_ACCESS_FS_MAKE_SOCK +Create (or rename or link) a UNIX domain socket. +.TP +.BR LANDLOCK_ACCESS_FS_MAKE_FIFO +Create (or rename or link) a named pipe. +.TP +.BR LANDLOCK_ACCESS_FS_MAKE_BLOCK +Create (or rename or link) a block device. +.TP +.BR LANDLOCK_ACCESS_FS_MAKE_SYM +Create (or rename or link) a symbolic link. +.\" +.SS Layers of file path access rights +Each time a thread enforces a ruleset on itself, it updates its Landlock +domain with a new layer of policy. Indeed, this complementary policy is +composed with the potentially other rulesets already restricting this +thread. A sandboxed thread can then safely add more constraints to itself +with a new enforced ruleset. +.PP +One policy layer grants access to a file path if at least one of its rules +encountered on the path grants the access. A sandboxed thread can only +access a file path if all its enforced policy layers grant the access as +well as all the other system access controls (e.g., filesystem DAC, other +LSM policies, etc.). +.\" +.SS Bind mounts and OverlayFS +Landlock enables restricting access to file hierarchies, which means that +these access rights can be propagated with bind mounts (cf. +.BR mount_namespaces (7) +) but not with OverlayFS. +.PP +A bind mount mirrors a source file hierarchy to a destination. The +destination hierarchy is then composed of the exact same files, on which +Landlock rules can be tied, either via the source or the destination path. +These rules restrict access when they are encountered on a path, which +means that they can restrict access to multiple file hierarchies at the +same time, whether these hierarchies are the result of bind mounts or not. +.PP +An OverlayFS mount point consists of upper and lower layers. These layers +are combined in a merge directory, result of the mount point. This merge +hierarchy may include files from the upper and lower layers, but +modifications performed on the merge hierarchy only reflects on the upper +layer. From a Landlock policy point of view, each OverlayFS layers and +merge hierarchies are standalone and contains their own set of files and +directories, which is different from bind mounts. A policy restricting an +OverlayFS layer will not restrict the resulted merged hierarchy, and vice +versa. Landlock users should then only think about file hierarchies they +want to allow access to, regardless of the underlying filesystem. +.\" +.SS Inheritance +Every new thread resulting from a +.BR clone (2) +inherits Landlock domain restrictions from its parent. This is similar to +the +.BR seccomp (2) +inheritance or any other LSM dealing with task's +.BR credentials (7) +\&. For instance, one process's thread may apply Landlock rules to itself, +but they will not be automatically applied to other sibling threads (unlike +POSIX thread credential changes, cf. +.BR nptl (7) +). +.PP +When a thread sandboxes itself, we have the guarantee that the related +security policy will stay enforced on all this thread's descendants. This +allows creating standalone and modular security policies per application, +which will automatically be composed between themselves according to their +runtime parent policies. +.\" +.SS Ptrace restrictions +A sandboxed process has less privileges than a non-sandboxed process and +must then be subject to additional restrictions when manipulating another +process. To be allowed to use +.BR ptrace (2) +and related syscalls on a target process, a sandboxed process should have a +subset of the target process rules, which means the tracee must be in a +sub-domain of the tracer. +.SH VERSIONS +Landlock was added in Linux 5.13. +.SH NOTES +Landlock is enabled by CONFIG_SECURITY_LANDLOCK. +The +.I lsm=lsm1,...,lsmN +command line parameter controls the sequence of the initialization of +Linux Security Modules. +It must contain the string +.I landlock +to enable Landlock. +If the command line parameter is not specified, +the initialization falls back to the value of the deprecated +.I security= +command line parameter and further to the value of CONFIG_LSM. +We can check that Landlock is enabled by looking for +.I +landlock: Up and running. +in kernel logs. +.\" +.PP +It is currently not possible to restrict some file-related actions +accessible through these syscall families: +.BR chdir (2) +, +.BR truncate (2) +, +.BR stat (2) +, +.BR flock (2) +, +.BR chmod (2) +, +.BR chown (2) +, +.BR setxattr (2) +, +.BR utime (2) +, +.BR ioctl (2) +, +.BR fcntl (2) +, +.BR access (2) +\&. +Future Landlock evolutions will enable to restrict them. +.SH SEE ALSO +.BR landlock_create_ruleset (2), +.BR landlock_add_rule (2), +.BR landlock_restrict_self (2) +.PP +.UR https://landlock.io\:/ +.UE -- 2.32.0
