diff options
Diffstat (limited to 'man7/landlock.7')
| -rw-r--r-- | man7/landlock.7 | 277 |
1 files changed, 260 insertions, 17 deletions
diff --git a/man7/landlock.7 b/man7/landlock.7 index 1f886af28..96f821742 100644 --- a/man7/landlock.7 +++ b/man7/landlock.7 @@ -1,10 +1,11 @@ +'\" 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 2023-02-05 "Linux man-pages 6.03" +.TH Landlock 7 2023-05-03 "Linux man-pages 6.05.01" .SH NAME Landlock \- unprivileged access-control .SH DESCRIPTION @@ -23,7 +24,7 @@ A Landlock security policy is a set of access rights tied to a file hierarchy. Such policy can be configured and enforced by processes for themselves using three system calls: -.IP \[bu] 2 +.IP \[bu] 3 .BR landlock_create_ruleset (2) creates a new ruleset; .IP \[bu] @@ -64,9 +65,39 @@ 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. .PP A directory can receive access rights related to files or directories. The following access right is applied to the directory itself, @@ -105,6 +136,56 @@ 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, @@ -170,7 +251,7 @@ 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. +according to their run-time parent policies. .\" .SS Ptrace restrictions A sandboxed process has less privileges than a non-sandboxed process and @@ -181,8 +262,104 @@ To be allowed to use 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. +.PP +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. +.PP +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" . +.PP +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. +.PP +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 added in Linux 5.13. +Landlock was introduced in Linux 5.13. +.PP +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 +.sp 1 +.PP +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. +.PP +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). +.PP +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 . @@ -201,11 +378,10 @@ command line parameter and further to the value of We can check that Landlock is enabled by looking for .I landlock: Up and running. in kernel logs. -.PP +.SH CAVEATS It is currently not possible to restrict some file-related actions accessible through these system call families: .BR chdir (2), -.BR truncate (2), .BR stat (2), .BR flock (2), .BR chmod (2), @@ -218,17 +394,20 @@ accessible through these system call families: Future Landlock evolutions will enable to restrict them. .SH EXAMPLES We first need to create the ruleset that will contain our rules. +.PP 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 below for the description of filesystem actions. +See the +.B DESCRIPTION +section for the description of filesystem actions. .PP .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 | @@ -242,19 +421,83 @@ attr.handled_access_fs = LANDLOCK_ACCESS_FS_MAKE_SOCK | LANDLOCK_ACCESS_FS_MAKE_FIFO | LANDLOCK_ACCESS_FS_MAKE_BLOCK | - LANDLOCK_ACCESS_FS_MAKE_SYM; - + LANDLOCK_ACCESS_FS_MAKE_SYM | + LANDLOCK_ACCESS_FS_REFER | + LANDLOCK_ACCESS_FS_TRUNCATE; +.EE +.in +.PP +To be compatible with older Linux versions, +we detect the available Landlock ABI version, +and only use the available subset of access rights: +.PP +.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 +.PP +The available access rights for each ABI version are listed in the +.B VERSIONS +section. +.PP +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. +.PP +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): +.PP +.in +4n +.EX ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0); -if (ruleset_fd == -1) { +if (ruleset_fd == \-1) { perror("Failed to create a ruleset"); exit(EXIT_FAILURE); } .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 +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. +.PP +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 @@ -269,14 +512,14 @@ with this file descriptor. .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) { +if (path_beneath.parent_fd == \-1) { perror("Failed to open file"); close(ruleset_fd); exit(EXIT_FAILURE); |