Hi Günther, On 2/28/23 21:52, Günther Noack 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 | 102 +++++++++++++++++++++++++++++++++++++++++++++++- > 1 file changed, 100 insertions(+), 2 deletions(-) > > diff --git a/man7/landlock.7 b/man7/landlock.7 > index b2bc9e10b..f70a01484 100644 > --- a/man7/landlock.7 > +++ b/man7/landlock.7 > @@ -105,6 +105,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] 3 You only need to specify the indentation (the "3") in the first consecutive .IP. All others reuse the indentation level until a .PP appears (or a few other situations that I won't enumerate for brevity). > +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_* The * should be in italics, since it's not part of the literal, but rather a variable part. I know the pages are not very consistent in this, but I'd like to make them consistent in the future. Cheers, Alex > +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 +232,54 @@ 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 > +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 > +.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 . > @@ -242,7 +339,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) { > > base-commit: 53a7e5dfc3554a2e8dbdfdc4504e99652e1d6382 -- <http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
