* Add the description for LANDLOCK_ACCESS_FS_REFER, in line with recent update to the uapi headers: https://lore.kernel.org/linux-security-module/20230202204623.10345-1-gnoack3000@xxxxxxxxx/T/ * VERSIONS: Add a table of Landlock versions and their changes. Briefly talk about how to probe ABI levels and warn users about the special semantics of the LANDLOCK_ACCESS_FS_REFER right. * Add LANDLOCK_ACCESS_FS_REFER to the code example. Code review threads for the "refer" feature: * https://lore.kernel.org/all/20220506161102.525323-1-mic@xxxxxxxxxxx/ (initial commit) * https://lore.kernel.org/all/20220823144123.633721-1-mic@xxxxxxxxxxx/ (bugfix) * https://lore.kernel.org/all/20230221165205.4231-1-gnoack3000@xxxxxxxxx/ (documentation update) --- man7/landlock.7 | 90 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 88 insertions(+), 2 deletions(-) diff --git a/man7/landlock.7 b/man7/landlock.7 index 099f68067..6321b56ab 100644 --- a/man7/landlock.7 +++ b/man7/landlock.7 @@ -105,6 +105,53 @@ 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 3 +When linking or renaming, the +.B LANDLOCK_ACCESS_FS_MAKE_* +right for the respective file type must be granted for the destination +directory. Otherwise, the operation results in an +.BR EACCES +error. +.IP \(bu 3 +When renaming, the +.B 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, @@ -182,7 +229,45 @@ 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. +Landlock was introduced in Linux 5.13. +.PP +The availability of individual Landlock features is versioned through +ABI levels: +.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 +.TE +.PP +To query the running kernel's Landlock ABI level, 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 . @@ -242,7 +327,8 @@ 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; ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0); if (ruleset_fd == -1) { -- 2.39.2
