diff options
Diffstat (limited to 'man/man7/landlock.7')
| -rw-r--r-- | man/man7/landlock.7 | 585 |
1 files changed, 585 insertions, 0 deletions
diff --git a/man/man7/landlock.7 b/man/man7/landlock.7 new file mode 100644 index 000000000..4a98f6549 --- /dev/null +++ b/man/man7/landlock.7 @@ -0,0 +1,585 @@ +'\" t +.\" Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net> +.\" Copyright © 2019-2020 ANSSI +.\" Copyright © 2021 Microsoft Corporation +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH Landlock 7 (date) "Linux man-pages (unreleased)" +.SH NAME +Landlock \- unprivileged access-control +.SH DESCRIPTION +Landlock is an access-control system that enables any processes to +securely restrict themselves and their future children. +Because Landlock is a stackable Linux Security Module (LSM), +it makes it 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. +.P +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] 3 +.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. +.P +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 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. +.P +A file can only receive these access rights: +.TP +.B LANDLOCK_ACCESS_FS_EXECUTE +Execute a file. +.TP +.B LANDLOCK_ACCESS_FS_WRITE_FILE +Open a file with write access. +.IP +When opening files for writing, +you will often additionally need the +.B LANDLOCK_ACCESS_FS_TRUNCATE +right. +In many cases, +these system calls truncate existing files when overwriting them +(e.g., +.BR creat (2)). +.TP +.B LANDLOCK_ACCESS_FS_READ_FILE +Open a file with read access. +.TP +.B LANDLOCK_ACCESS_FS_TRUNCATE +Truncate a file with +.BR truncate (2), +.BR ftruncate (2), +.BR creat (2), +or +.BR open (2) +with +.BR O_TRUNC . +Whether an opened file can be truncated with +.BR ftruncate (2) +is determined during +.BR open (2), +in the same way as read and write permissions are checked during +.BR open (2) +using +.B LANDLOCK_ACCESS_FS_READ_FILE +and +.BR LANDLOCK_ACCESS_FS_WRITE_FILE . +This access right is available since the third version of the Landlock ABI. +.P +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 +.B LANDLOCK_ACCESS_FS_READ_DIR +Open a directory or list its content. +.P +However, +the following access rights only apply to the content of a directory, +not the directory itself: +.TP +.B LANDLOCK_ACCESS_FS_REMOVE_DIR +Remove an empty directory or rename one. +.TP +.B LANDLOCK_ACCESS_FS_REMOVE_FILE +Unlink (or rename) a file. +.TP +.B LANDLOCK_ACCESS_FS_MAKE_CHAR +Create (or rename or link) a character device. +.TP +.B LANDLOCK_ACCESS_FS_MAKE_DIR +Create (or rename) a directory. +.TP +.B LANDLOCK_ACCESS_FS_MAKE_REG +Create (or rename or link) a regular file. +.TP +.B LANDLOCK_ACCESS_FS_MAKE_SOCK +Create (or rename or link) a UNIX domain socket. +.TP +.B LANDLOCK_ACCESS_FS_MAKE_FIFO +Create (or rename or link) a named pipe. +.TP +.B LANDLOCK_ACCESS_FS_MAKE_BLOCK +Create (or rename or link) a block device. +.TP +.B LANDLOCK_ACCESS_FS_MAKE_SYM +Create (or rename or link) a symbolic link. +.TP +.B LANDLOCK_ACCESS_FS_REFER +Link or rename a file from or to a different directory +(i.e., reparent a file hierarchy). +.IP +This access right is available since the second version of the Landlock ABI. +.IP +This is the only access right which is denied by default by any ruleset, +even if the right is not specified as handled at ruleset creation time. +The only way to make a ruleset grant this right +is to explicitly allow it for a specific directory +by adding a matching rule to the ruleset. +.IP +In particular, when using the first Landlock ABI version, +Landlock will always deny attempts to reparent files +between different directories. +.IP +In addition to the source and destination directories having the +.B LANDLOCK_ACCESS_FS_REFER +access right, +the attempted link or rename operation must meet the following constraints: +.RS +.IP \[bu] 3 +The reparented file may not gain more access rights in the destination directory +than it previously had in the source directory. +If this is attempted, the operation results in an +.B EXDEV +error. +.IP \[bu] +When linking or renaming, the +.BI LANDLOCK_ACCESS_FS_MAKE_ * +right for the respective file type must be granted +for the destination directory. +Otherwise, the operation results in an +.B EACCES +error. +.IP \[bu] +When renaming, the +.BI LANDLOCK_ACCESS_FS_REMOVE_ * +right for the respective file type must be granted +for the source directory. +Otherwise, the operation results in an +.B EACCES +error. +.RE +.IP +If multiple requirements are not met, the +.B EACCES +error code takes precedence over +.BR EXDEV . +.\" +.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. +.P +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. +.P +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. +.P +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 reflect on the upper layer. +From a Landlock policy point of view, +each of the OverlayFS layers and merge hierarchies is standalone and +contains its own set of files and directories, +which is different from a bind mount. +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 tasks' +.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)). +.P +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 run-time 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. +.\" +.SS Truncating files +The operations covered by +.B LANDLOCK_ACCESS_FS_WRITE_FILE +and +.B LANDLOCK_ACCESS_FS_TRUNCATE +both change the contents of a file and sometimes overlap in +non-intuitive ways. +It is recommended to always specify both of these together. +.P +A particularly surprising example is +.BR creat (2). +The name suggests that this system call requires +the rights to create and write files. +However, it also requires the truncate right +if an existing file under the same name is already present. +.P +It should also be noted that truncating files does not require the +.B LANDLOCK_ACCESS_FS_WRITE_FILE +right. +Apart from the +.BR truncate (2) +system call, this can also be done through +.BR open (2) +with the flags +.IR "O_RDONLY\ |\ O_TRUNC" . +.P +When opening a file, the availability of the +.B LANDLOCK_ACCESS_FS_TRUNCATE +right is associated with the newly created file descriptor +and will be used for subsequent truncation attempts using +.BR ftruncate (2). +The behavior is similar to opening a file for reading or writing, +where permissions are checked during +.BR open (2), +but not during the subsequent +.BR read (2) +and +.BR write (2) +calls. +.P +As a consequence, +it is possible to have multiple open file descriptors for the same file, +where one grants the right to truncate the file and the other does not. +It is also possible to pass such file descriptors between processes, +keeping their Landlock properties, +even when these processes do not have an enforced Landlock ruleset. +.SH VERSIONS +Landlock was introduced in Linux 5.13. +.P +To determine which Landlock features are available, +users should query the Landlock ABI version: +.TS +box; +ntb| ntb| lbx +nt| nt| lbx. +ABI Kernel Newly introduced access rights +_ _ _ +1 5.13 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 +_ _ _ +2 5.19 LANDLOCK_ACCESS_FS_REFER +_ _ _ +3 6.2 LANDLOCK_ACCESS_FS_TRUNCATE +.TE +.P +Users should use the Landlock ABI version rather than the kernel version +to determine which features are available. +The mainline kernel versions listed here are only included for orientation. +Kernels from other sources may contain backported features, +and their version numbers may not match. +.P +To query the running kernel's Landlock ABI version, +programs may pass the +.B LANDLOCK_CREATE_RULESET_VERSION +flag to +.BR landlock_create_ruleset (2). +.P +When building fallback mechanisms for compatibility with older kernels, +users are advised to consider the special semantics of the +.B LANDLOCK_ACCESS_FS_REFER +access right: +In ABI v1, +linking and moving of files between different directories is always forbidden, +so programs relying on such operations are only compatible +with Landlock ABI v2 and higher. +.SH NOTES +Landlock is enabled by +.BR 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 +.BR CONFIG_LSM . +We can check that Landlock is enabled by looking for +.I landlock: Up and running. +in kernel logs. +.SH CAVEATS +It is currently not possible to restrict some file-related actions +accessible through these system call families: +.BR chdir (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 EXAMPLES +We first need to create the ruleset that will contain our rules. +.P +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 kinds of actions. +See the +.B DESCRIPTION +section for the description of filesystem actions. +.P +.in +4n +.EX +struct landlock_ruleset_attr attr = {0}; +int ruleset_fd; +\& +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 | + LANDLOCK_ACCESS_FS_REFER | + LANDLOCK_ACCESS_FS_TRUNCATE; +.EE +.in +.P +To be compatible with older Linux versions, +we detect the available Landlock ABI version, +and only use the available subset of access rights: +.P +.in +4n +.EX +/* + * Table of available file system access rights by ABI version, + * numbers hardcoded to keep the example short. + */ +__u64 landlock_fs_access_rights[] = { + (LANDLOCK_ACCESS_FS_MAKE_SYM << 1) \- 1, /* v1 */ + (LANDLOCK_ACCESS_FS_REFER << 1) \- 1, /* v2: add "refer" */ + (LANDLOCK_ACCESS_FS_TRUNCATE << 1) \- 1, /* v3: add "truncate" */ +}; +\& +int abi = landlock_create_ruleset(NULL, 0, + LANDLOCK_CREATE_RULESET_VERSION); +if (abi == \-1) { + /* + * Kernel too old, not compiled with Landlock, + * or Landlock was not enabled at boot time. + */ + perror("Unable to use Landlock"); + return; /* Graceful fallback: Do nothing. */ +} +abi = MIN(abi, 3); +\& +/* Only use the available rights in the ruleset. */ +attr.handled_access_fs &= landlock_fs_access_rights[abi \- 1]; +.EE +.in +.P +The available access rights for each ABI version are listed in the +.B VERSIONS +section. +.P +If our program needed to create hard links +or rename files between different directories +.RB ( LANDLOCK_ACCESS_FS_REFER ), +we would require the following change to the backwards compatibility logic: +Directory reparenting is not possible +in a process restricted with Landlock ABI version 1. +Therefore, +if the program needed to do file reparenting, +and if only Landlock ABI version 1 was available, +we could not restrict the process. +.P +Now that the ruleset attributes are determined, +we create the Landlock ruleset +and acquire a file descriptor as a handle to it, +using +.BR landlock_create_ruleset (2): +.P +.in +4n +.EX +ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0); +if (ruleset_fd == \-1) { + perror("Failed to create a ruleset"); + exit(EXIT_FAILURE); +} +.EE +.in +.P +We can now add a new rule to the ruleset through the ruleset's file descriptor. +The requested access rights must be a subset of the access rights +which were specified in +.I attr.handled_access_fs +at ruleset creation time. +.P +In this example, the rule will only allow reading the file hierarchy +.IR /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. +.P +.in +4n +.EX +struct landlock_path_beneath_attr path_beneath = {0}; +int err; +\& +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 == \-1) { + perror("Failed to open file"); + close(ruleset_fd); + exit(EXIT_FAILURE); +} +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); + exit(EXIT_FAILURE); +} +.EE +.in +.P +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). +.P +.in +4n +.EX +if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) { + perror("Failed to restrict privileges"); + close(ruleset_fd); + exit(EXIT_FAILURE); +} +.EE +.in +.P +The current thread is now ready to sandbox itself with the ruleset. +.P +.in +4n +.EX +if (landlock_restrict_self(ruleset_fd, 0)) { + perror("Failed to enforce ruleset"); + close(ruleset_fd); + exit(EXIT_FAILURE); +} +close(ruleset_fd); +.EE +.in +.P +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. +.P +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 +.SH SEE ALSO +.BR landlock_create_ruleset (2), +.BR landlock_add_rule (2), +.BR landlock_restrict_self (2) +.P +.UR https://landlock.io/ +.UE |