Thanks for this update Günther. On 2023-02-21T21:50:22.000+01:00, Günther Noack <gnoack3000@xxxxxxxxx> wrote: > * 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: I think this table is useful, but it should contain a warning to make sure developers don't rely on kernel versions to check Landlock features, but use the dedicated Landlock syscall instead. It should be explained that this table is true for the mainline/vanilla kernel, but that can be incorrect for any other kernel (e.g. patched distro kernel, like chromeOS that may backport upstream features). > +.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
