landlock.7: Move the warning about missing features into the CAVEATS section
PATCH 1/3 landlock.7: Move the warning about missing features into the CAVEATS section
Putting the warning there makes it more prominent. CAVEATS is a standard section that exists in many man pages and is also described in man-pages(7).
--- man7/landlock.7 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
man7/landlock.7 +1 -1
@@ -201,7 +201,7 @@ 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),
base-commit: 887b913eb2687f34bc056597c0501a4325bebf28
Signature · 1 line
2.39.2
PATCH 2/3 landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)
* Add the description for LANDLOCK_ACCESS_FS_REFER,
in line with recent update to the uapi headers:
https://lore.kernel.org/linux-security-module/[email protected]/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/[email protected]/ (initial commit)
* https://lore.kernel.org/all/[email protected]/ (bugfix)
* https://lore.kernel.org/all/[email protected]/ (documentation update)
--- man7/landlock.7 | 90 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 88 insertions(+), 2 deletions(-)
man7/landlock.7 +88 -2
@@ -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) {
Signature · 1 line
2.39.2
Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)
Thanks for this update Günther.
Quoted 75 lines · Günther Noack
* Add the description for
LANDLOCK_ACCESS_FS_REFER,
in line with recent update to the uapi headers:
https://lore.kernel.org/linux-security-module/[email protected]/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 theLANDLOCK_ACCESS_FS_REFERright.
* AddLANDLOCK_ACCESS_FS_REFERto the code example.Code review threads for the "refer" feature:
* https://lore.kernel.org/all/[email protected]/ (initial commit)
* https://lore.kernel.org/all/[email protected]/ (bugfix)
* https://lore.kernel.org/all/[email protected]/ (documentation update)--- man7/landlock.7 | 90 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 88 insertions(+), 2 deletions(-)man7/landlock.7 +47
-0@@ -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,
man7/landlock.7 and related syscalls on a target process, · line 235
Quoted 8 lines
man7/landlock.7 +4
-1@@ -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).
Quoted 40 lines
man7/landlock.7 +35
-0+.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 .
man7/landlock.7 attr.handled_access_fs = · line 334
Quoted 9 lines
man7/landlock.7 +2
-1@@ -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
Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)
Quoted 2 lines · Mickaël Salaün
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).
Thanks, that's a good point. I'll add that.
Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)
In reply to Günther NoackOn 2023-02-21T21:50:22.000+01:00, Günther Noack wrote:
[...]
Quoted 19 lines
.SH VERSIONS
man7/landlock.7 +17
-1-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
man7/landlock.7 and related syscalls on a target process, · line 258
Quoted 10 lines
man7/landlock.7 +10
-0+\^ \^ 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
A line break would be nice here.
Quoted 1 line
+To query the running kernel's Landlock ABI level, programs may pass
s/level/version/
Quoted 4 lines
man7/landlock.7 +4
-0+the +.B LANDLOCK_CREATE_RULESET_VERSION +flag to +.BR landlock_create_ruleset (2).
Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)
Quoted 20 lines · Mickaël Salaün
Quoted 19 lines · Günther Noack
man7/landlock.7 +19
-0+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
Quoted 8 lines
Quoted 6 lines
+\^ \^
LANDLOCK_ACCESS_FS_MAKE_BLOCK
+\^ \^LANDLOCK_ACCESS_FS_MAKE_SYM
+_ _ _
+2 5.19LANDLOCK_ACCESS_FS_REFER
+.TE
+.PPA line break would be nice here.
Added. (Used .sp 1 for that, as it is already used in the mount_namespaces.7, ip.7 and other man pages.)
Quoted 3 lines
Quoted 1 line
+To query the running kernel's Landlock ABI level, programs may pass
s/level/version/
Thanks, I'm removing the word "level" here.
Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)
Hi Branden,
Quoted 30 lines · Günther Noack
Quoted 20 lines · Mickaël Salaün
Quoted 19 lines · Günther Noack
man7/landlock.7 +19
-0+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_FIFOQuoted 8 lines
Quoted 6 lines
+\^ \^
LANDLOCK_ACCESS_FS_MAKE_BLOCK
+\^ \^LANDLOCK_ACCESS_FS_MAKE_SYM
+_ _ _
+2 5.19LANDLOCK_ACCESS_FS_REFER
+.TE
+.PPA line break would be nice here.
Quoted 2 lines
Added. (Used .sp 1 for that, as it is already used in the mount_namespaces.7, ip.7 and other man pages.)
This sounds weird, but they are right that there seems to be a missing blank line. Could you explain why it's happening? I'd expect the .PP to separate paragraphs with a blank, right? I see:
The availability of individual Landlock features is versioned through ABI levels:
┌────┬────────┬────────────────────────────────────────────────┐
│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 │
└────┴────────┴────────────────────────────────────────────────┘ To query the running kernel's Landlock ABI level, programs may pass the LANDLOCK_CREATE_RULESET_VERSION flag to landlock_cre‐ ate_ruleset(2).
Cheers,
Alex
Quoted 6 lines
Quoted 4 lines
Quoted 2 lines
+To query the running kernel's Landlock ABI level, programs may pass
s/level/version/
Thanks, I'm removing the word "level" here.
Signature · 2 lines
<http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)
Hi Alex,
Quoted 31 lines · Alex Colomar
Quoted 30 lines · Günther Noack
Quoted 28 lines · Mickaël Salaün
Quoted 15 lines · Günther Noack
man7/landlock.7 +15
-0+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_CHARman7/landlock.7 and related syscalls on a target process, · line 258
Quoted 10 lines
man7/landlock.7 +10
-0+\^ \^ 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 +.PPA line break would be nice here.
Quoted 3 lines
Quoted 2 lines
Added. (Used .sp 1 for that, as it is already used in the mount_namespaces.7, ip.7 and other man pages.)
[reorganized]
Quoted 19 lines
I see:
The availability of individual Landlock features is versioned through ABI levels:
┌────┬────────┬────────────────────────────────────────────────┐
│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│
Quoted 8 lines
│ │ │
LANDLOCK_ACCESS_FS_MAKE_BLOCK│
│ │ │LANDLOCK_ACCESS_FS_MAKE_SYM│
├────┼────────┼────────────────────────────────────────────────┤
│ 2 │ 5.19 │LANDLOCK_ACCESS_FS_REFER│
└────┴────────┴────────────────────────────────────────────────┘ To query the running kernel's Landlock ABI level, programs may pass theLANDLOCK_CREATE_RULESET_VERSIONflag to landlock_cre‐ate_ruleset(2).
[reorganized]
Quoted 2 lines
This sounds weird, but they are right that there seems to be a missing blank line.
Yes, they are.
Quoted 1 line
Could you explain why it's happening?
This is Savannah #49390.
https://savannah.gnu.org/bugs/?49390
It is fixed in groff 1.23.0. Which, by the way, is at release candidate 3 now. Final release may be this weekend, depending on Bertrand's opinion of the changes I've made this week.[1]
Quoted 1 line
I'd expect the .PP to separate paragraphs with a blank, right?
It does, and it is, but you can't see it because groff 1.22.4 and earlier table did not move the drawing position below the bottom box border on nroff devices.
The '.sp 1' workaround (which is synonymous with plain '.sp') can be removed when you feel groff 1.23.0 has spread sufficiently.
Regards,
Branden
Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)
Hi Branden,
Quoted 71 lines · G. Branden Robinson
Hi Alex,
Quoted 31 lines · Alex Colomar
Quoted 30 lines · Günther Noack
Quoted 28 lines · Mickaël Salaün
Quoted 15 lines · Günther Noack
man7/landlock.7 +15
-0+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_CHARman7/landlock.7 and related syscalls on a target process, · line 258
Quoted 10 lines
man7/landlock.7 +10
-0+\^ \^ 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 +.PPA line break would be nice here.
Quoted 3 lines
Quoted 2 lines
Added. (Used .sp 1 for that, as it is already used in the mount_namespaces.7, ip.7 and other man pages.)
[reorganized]
Quoted 19 lines
I see:
The availability of individual Landlock features is versioned through ABI levels:
┌────┬────────┬────────────────────────────────────────────────┐
│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│Quoted 8 lines
│ │ │
LANDLOCK_ACCESS_FS_MAKE_BLOCK│
│ │ │LANDLOCK_ACCESS_FS_MAKE_SYM│
├────┼────────┼────────────────────────────────────────────────┤
│ 2 │ 5.19 │LANDLOCK_ACCESS_FS_REFER│
└────┴────────┴────────────────────────────────────────────────┘ To query the running kernel's Landlock ABI level, programs may pass theLANDLOCK_CREATE_RULESET_VERSIONflag to landlock_cre‐ate_ruleset(2).[reorganized]
Quoted 2 lines
This sounds weird, but they are right that there seems to be a missing blank line.
Yes, they are.
Quoted 8 lines
Quoted 1 line
Could you explain why it's happening?
This is Savannah #49390.
https://savannah.gnu.org/bugs/?49390
It is fixed in groff 1.23.0. Which, by the way, is at release candidate 3 now.
Ahh, I forgot that in my laptop I still have 1.22.4 :) Good to know that it's already fixed. Thanks!
Quoted 2 lines
Final release may be this weekend, depending on Bertrand's
opinion of the changes I've made this week.[1]
Nice, we'll hopefully have it before I turn 30 (which BTW coincides with the deadline for having it in Bookworm, AFAIK :p)
Quoted 9 lines
Quoted 2 lines
I'd expect the .PP to separate paragraphs with a blank, right?
It does, and it is, but you can't see it because groff 1.22.4 and earlier table did not move the drawing position below the bottom box border on nroff devices.
The '.sp 1' workaround (which is synonymous with plain '.sp') can be removed when you feel groff 1.23.0 has spread sufficiently.
Since the bug is so minor, I'm in favor of removing it as soon as you release. A little bit of lack-of-blank-line inconvenience is not so bad.
Cheers,
Alex
Quoted 5 lines
Regards,
Branden
Signature · 2 lines
<http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)
Quoted 6 lines · Alex Colomar
Quoted 2 lines · G. Branden Robinson
The '.sp 1' workaround (which is synonymous with plain '.sp') can be removed when you feel groff 1.23.0 has spread sufficiently.
Since the bug is so minor, I'm in favor of removing it as soon as you release. A little bit of lack-of-blank-line inconvenience is not so bad.
OK, thanks for investigating this!
I'll keep it in the man page for now then.
–-Günther
Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)
In reply to Mickaël SalaünHi Mickaël,
Quoted 27 lines · Mickaël Salaün
On 2023-02-21T21:50:22.000+01:00, Günther Noack wrote:
[...]
Quoted 23 lines
.SH VERSIONS
man7/landlock.7 +21
-1-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
Quoted 8 lines
Quoted 6 lines
+\^ \^
LANDLOCK_ACCESS_FS_MAKE_BLOCK
+\^ \^LANDLOCK_ACCESS_FS_MAKE_SYM
+_ _ _
+2 5.19LANDLOCK_ACCESS_FS_REFER
+.TE
+.PPA line break would be nice here.
.PP should be performing a line break. I didn't yet read the formatted version, so maybe there's something wrong with the table, but from inspection of the source it seems reasonable to me.
Cheers,
Alex
Quoted 9 lines
Quoted 2 lines
+To query the running kernel's Landlock ABI level, programs may pass
s/level/version/
Quoted 4 lines
man7/landlock.7 +4
-0+the +.B LANDLOCK_CREATE_RULESET_VERSION +flag to +.BR landlock_create_ruleset (2).
Signature · 2 lines
<http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)
In reply to Günther NoackOn 2023-02-21T21:50:22.000+01:00, Günther Noack wrote:
[...]
Quoted 45 lines
.SH VERSIONS
man7/landlock.7 +39
-1-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 .
man7/landlock.7 attr.handled_access_fs = · line 331
Quoted 6 lines
man7/landlock.7 +2
-1@@ -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;
This code example should now query the Landlock ABI version and mask new access right to make it works with old kernels.
man7/landlock.7 attr.handled_access_fs = · line 334
Quoted 4 lines
man7/landlock.7 +0
-0ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0); if (ruleset_fd == -1) {
2.39.2
Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)
Quoted 10 lines · Mickaël Salaün
man7/landlock.7 attr.handled_access_fs = · line 331
Quoted 7 lines · Günther Noack
man7/landlock.7 +2
-1@@ -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;This code example should now query the Landlock ABI version and mask new access right to make it works with old kernels.
The changes I would have to do are:
- I would *remove* LANDLOCK_ACCESS_FS_REFER from attr.handled_access_fs, because it is not used in the LANDLOCK_RULE_PATH_PENEATH and that right is implicit anyway.
- Patch 3/3: I would *keep* LANDLOCK_ACCESS_FS_TRUNCATE in attr.handled_access_fs.
- Patch 3/3: I would query the ABI version, and mask away the LANDLOCK_ACCESS_FS_TRUNCATE right in handled_access_fs if the ABI version is < 3.
Things I don't like yet about this approach are:
* I believe if I were to read that example for the first time, I would be puzzled when seeing the "truncate" right set in handled_access_fs, but the "refer" right omitted. This requires additional explanation.
* It does not really describe what to do if you actually need to reparent files with the "refer" right in your program. The fallback logic is simpler in the man page example because "refer" is not needed in the LANDLOCK_RULE_PATH_BENEATH rule.
At the same time, I feel that the more complicated "refer" fallback logic might be beyond what would reasonably fit into a man page. Especially given that many users probably don't need the "refer" right for their programs.
So my proposal would be to change the example as described in the three bullet points above, but to point out that users who need "refer" should refer (ha ha) to the kernel documentation for more details.
Does that sound reasonable to you?
–-Günther
Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)
In reply to Günther NoackHi Günther,
Quoted 8 lines · Günther Noack
* Add the description for
LANDLOCK_ACCESS_FS_REFER, in line with recent update to the uapi headers:https://lore.kernel.org/linux-security-module/[email protected]/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_REFERright.
* AddLANDLOCK_ACCESS_FS_REFERto the code example.
Quoted 4 lines
Code review threads for the "refer" feature:
* https://lore.kernel.org/all/[email protected]/ (initial commit)
* https://lore.kernel.org/all/[email protected]/ (bugfix)
* https://lore.kernel.org/all/[email protected]/ (documentation update)
I finally found some time to review your work. Thanks for the patience!
Please see some comments below.
Thanks!
Alex
Quoted 9 lines
--- man7/landlock.7 | 90 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 88 insertions(+), 2 deletions(-)man7/landlock.7 +0
-0
man7/landlock.7 Create (or rename or link) a block device. · line 111
Quoted 7 lines
man7/landlock.7 +4
-0@@ -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).
Please have a look at man-pages(7):
Use semantic newlines
In the source of a manual page, new sentences should be started on new lines, long sentences should be split into lines at clause breaks (commas, semicolons, colons, and so on), and long clauses should be split at phrase boundaries. This convention, sometimes known as "semantic newlines", makes it easier to see the effect of patches, which often operate at the level of in‐ dividual sentences, clauses, or phrases.
Here,
that would mean
breaking the line right before the opening parenthesis; please also apply it to the rest of the patch where appropriate.
Quoted 9 lines
man7/landlock.7 +9
-0+.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.
man7/landlock.7 Create (or rename or link) a block device. · line 130
Quoted 10 lines
man7/landlock.7 +10
-0+.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
We now use \[bu] instead of \(bu (they are equivalent).
commit 36f73ba37945c7ff4aa2d8383f831519a38e3f27
Author: Alejandro Colomar <[email protected]> Date: Sun Feb 5 22:59:22 2023 +0100
man-pages.7: Recommend using \[..] instead of \(.. escapes
They are more readable.
man7/man-pages.7 +1 -1
@@ -666,7 +666,7 @@ These represent a set of (normally) exclusive alternatives. .TP Bullet lists Elements are preceded by bullet symbols -.RB ( \e(bu ). +.RB ( \e[bu] ). Anything that doesn't fit elsewhere is usually covered by this type of list. .TP
@@
[...]
commit cdede5cdd1b0ba75135d3b32d96354026e96f866
Author: Alejandro Colomar <[email protected]> Date: Sun Feb 5 23:14:38 2023 +0100
Many pages: Use \[bu] instead of \(bu
Quoted 6 lines
man7/landlock.7 +6
-0+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
man7/landlock.7 Create (or rename or link) a block device. · line 146
Quoted 10 lines
man7/landlock.7 +10
-0+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
80 columns is a strong limit.
Using semantic newlines as suggested above should fix this.
Quoted 18 lines
man7/landlock.7 +10
-1+.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
man7/landlock.7 and related syscalls on a target process, · line 243
Quoted 10 lines
man7/landlock.7 +10
-0+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
What character do you want here?
If you want ASCII 0x5E,
then you want to use \[ha].
Quoted 40 lines
man7/landlock.7 +29
-1+\^ \^ 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) {
Signature · 2 lines
<http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Günther Noack
AppliedRe: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)
Hello Alex!
Thank you for the review! Please see answers inline:
Quoted 9 lines · Alex Colomar
On 2/21/23 21:50, Günther Noack wrote:
Please have a look at man-pages(7):
Use semantic newlines[...]Here,
that would mean
breaking the line right before the opening parenthesis; please also apply it to the rest of the patch where appropriate.
Thanks,
I applied this
so that the text is properly formatted now,
according to man-pages(7).
Quoted 3 lines
Quoted 1 line
+.IP \(bu 3
We now use \[bu] instead of \(bu (they are equivalent).
Thanks, applied.
Quoted 2 lines
80 columns is a strong limit.
Using semantic newlines as suggested above should fix this.
Done.
Quoted 4 lines
Quoted 4 lines
+.TS
(quoted diff) +3
-0+box; +ntb| ntb| lbx +nt| nt| lbx.
Quoted 8 lines
Review
Quoted 4 lines
(quoted diff) +4
-0+ABI Kernel Newly introduced access rights +_ _ _ +1 5.13 LANDLOCK_ACCESS_FS_EXECUTE +\^ \^ LANDLOCK_ACCESS_FS_WRITE_FILEWhat character do you want here?
If you want ASCII0x5E,
then you want to use \[ha].
I don't want it to show a character there. The intent is to make the table cells for ABI version and kernel version span across multiple rows, for the case where a single kernel version introduced multiple access rights at once. \^ is a data item in the tbl(1) syntax which has that special meaning.
https://manpages.debian.org/testing/groff-base/tbl.1.en.html
A data item consisting only of ‘\^’ indicates that the field immediately above spans downward over this row.
Quoted 5 lines
Quoted 5 lines
+\^ \^
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
Quoted 8 lines
Quoted 8 lines
+\^ \^
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.19LANDLOCK_ACCESS_FS_REFER
Thanks for the review!
–Günther
PATCH 3/3 landlock.7: Document Landlock ABI v3 (file truncation; kernel 6.2)
In reply to Günther Noackhttps://lore.kernel.org/all/[email protected]/
--- man7/landlock.7 | 80 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 77 insertions(+), 3 deletions(-)
man7/landlock.7 +77 -3
@@ -63,10 +63,38 @@ A file can only receive these access rights: Execute a file. .TP .B LANDLOCK_ACCESS_FS_WRITE_FILE -Open a file with write access. +Open a file with write access. Note that you might additionally need the +.B LANDLOCK_ACCESS_FS_TRUNCATE +right in order to overwrite files with +.BR open (2) +using +.B O_TRUNC +or +.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,
@@ -228,6 +256,50 @@ 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 +.BR "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 introduced in Linux 5.13. .PP
@@ -254,6 +326,8 @@ _ _ _ \^ \^ LANDLOCK_ACCESS_FS_MAKE_SYM _ _ _ 2 5.19 LANDLOCK_ACCESS_FS_REFER +_ _ _ +3 6.2 LANDLOCK_ACCESS_FS_TRUNCATE .TE .PP To query the running kernel's Landlock ABI level, programs may pass
@@ -290,7 +364,6 @@ in kernel logs. 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),
@@ -328,7 +401,8 @@ attr.handled_access_fs = LANDLOCK_ACCESS_FS_MAKE_FIFO | LANDLOCK_ACCESS_FS_MAKE_BLOCK | LANDLOCK_ACCESS_FS_MAKE_SYM | - LANDLOCK_ACCESS_FS_REFER; + LANDLOCK_ACCESS_FS_REFER |; + LANDLOCK_ACCESS_FS_TRUNCATE; ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0); if (ruleset_fd == -1) {
Signature · 1 line
2.39.2
Re: [PATCH 3/3] landlock.7: Document Landlock ABI v3 (file truncation; kernel 6.2)
Quoted 1 line · Günther Noack
We should point to the git (merge) commit once it is merged in the kernel:
https://git.kernel.org/torvalds/c/299e2b1967578b1442128ba8b3e86ed3427d3651
[...]
man7/landlock.7 attr.handled_access_fs = · line 404
Quoted 6 lines
man7/landlock.7 +1
-1@@ -328,7 +401,8 @@ attr.handled_access_fs = LANDLOCK_ACCESS_FS_MAKE_FIFO | LANDLOCK_ACCESS_FS_MAKE_BLOCK | LANDLOCK_ACCESS_FS_MAKE_SYM | - LANDLOCK_ACCESS_FS_REFER; + LANDLOCK_ACCESS_FS_REFER |;
trailing ";"
man7/landlock.7 attr.handled_access_fs = · line 408
Quoted 5 lines
man7/landlock.7 +1
-0+ LANDLOCK_ACCESS_FS_TRUNCATE; ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0); if (ruleset_fd == -1) {
2.39.2
Re: [PATCH 3/3] landlock.7: Document Landlock ABI v3 (file truncation; kernel 6.2)
Quoted 4 lines · Mickaël Salaün
Quoted 1 line · Günther Noack
We should point to the git (merge) commit once it is merged in the kernel:
https://git.kernel.org/torvalds/c/299e2b1967578b1442128ba8b3e86ed3427d3651
Ah, thanks. Will change it in the next patch version.
Quoted 8 lines
man7/landlock.7 attr.handled_access_fs = · line 404
Quoted 6 lines
man7/landlock.7 +1
-1@@ -328,7 +401,8 @@ attr.handled_access_fs = LANDLOCK_ACCESS_FS_MAKE_FIFO | LANDLOCK_ACCESS_FS_MAKE_BLOCK | LANDLOCK_ACCESS_FS_MAKE_SYM | - LANDLOCK_ACCESS_FS_REFER; + LANDLOCK_ACCESS_FS_REFER |;trailing ";"
Oops. Done.
Re: [PATCH 3/3] landlock.7: Document Landlock ABI v3 (file truncation; kernel 6.2)
In reply to Günther NoackHi Günther,
Quoted 1 line · Günther Noack
Please see some comments below.
Cheers,
Alex
Quoted 9 lines
--- man7/landlock.7 | 80 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 77 insertions(+), 3 deletions(-)man7/landlock.7 +0
-0
man7/landlock.7 A file can only receive these access rights: · line 66
Quoted 5 lines
man7/landlock.7 +1
-1@@ -63,10 +63,38 @@ A file can only receive these access rights: Execute a file. .TP .B LANDLOCK_ACCESS_FS_WRITE_FILE -Open a file with write access. +Open a file with write access. Note that you might additionally need the
Again,
please use semantic newlines.
Also,
roff(7) requires two spaces after period in source code, to detect sentence endings.
I say this as a curiosity,
since due to the requirement of semantic newlines, we always write a newline after period.
Quoted 21 lines
man7/landlock.7 +18
-0+.B LANDLOCK_ACCESS_FS_TRUNCATE +right in order to overwrite files with +.BR open (2) +using +.B O_TRUNC +or +.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
man7/landlock.7 A file can only receive these access rights: · line 97
Quoted 10 lines
man7/landlock.7 +10
-0+.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.
Maybe it's simpler to say Landlock ABI v3? That's usual convention in software, so not using formal English for that is not a crime :).
Quoted 81 lines
man7/landlock.7 +48
-2.PP A directory can receive access rights related to files or directories. The following access right is applied to the directory itself,@@ -228,6 +256,50 @@ 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 +.BR "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 introduced in Linux 5.13. .PP@@ -254,6 +326,8 @@ _ _ _ \^ \^ LANDLOCK_ACCESS_FS_MAKE_SYM _ _ _ 2 5.19 LANDLOCK_ACCESS_FS_REFER +_ _ _ +3 6.2 LANDLOCK_ACCESS_FS_TRUNCATE .TE .PP To query the running kernel's Landlock ABI level, programs may pass@@ -290,7 +364,6 @@ in kernel logs. 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),@@ -328,7 +401,8 @@ attr.handled_access_fs = LANDLOCK_ACCESS_FS_MAKE_FIFO | LANDLOCK_ACCESS_FS_MAKE_BLOCK | LANDLOCK_ACCESS_FS_MAKE_SYM | - LANDLOCK_ACCESS_FS_REFER; + LANDLOCK_ACCESS_FS_REFER |; + LANDLOCK_ACCESS_FS_TRUNCATE; ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0); if (ruleset_fd == -1) {
Signature · 2 lines
<http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Re: [PATCH 3/3] landlock.7: Document Landlock ABI v3 (file truncation; kernel 6.2)
Quoted 6 lines · Alex Colomar
Quoted 1 line · Günther Noack
+Open a file with write access. Note that you might additionally need the
Again,
please use semantic newlines.
Quoted 6 lines
Also,
roff(7) requires two spaces after period in source code, to detect sentence endings.
I say this as a curiosity,
since due to the requirement of semantic newlines, we always write a newline after period.
Applied semantic newlines. There are no single-space sentence ends left.
Quoted 6 lines
Quoted 6 lines
man7/landlock.7 +6
-0+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)
Quoted 8 lines
man7/landlock.7 A file can only receive these access rights: · line 97
Quoted 5 lines
man7/landlock.7 +5
-0+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.Maybe it's simpler to say Landlock ABI v3? That's usual convention in software, so not using formal English for that is not a crime :).
Hm, I took that sentence from the kernel documentation, and I would like to avoid deviating in minor wording aspects.
https://docs.kernel.org/userspace-api/landlock.html
I would be in favor of "ABI v3" as well though, for brevity. Mickaël, do you have a strong opinion on this?
Thank you for the review!
–Günther
Hi Günther,
Quoted 3 lines · Günther Noack
Putting the warning there makes it more prominent. CAVEATS is a standard section that exists in many man pages and is also described in man-pages(7).
Patch applied.
Thanks,
Alex
Quoted 19 lines
--- man7/landlock.7 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)man7/landlock.7 +1
-1@@ -201,7 +201,7 @@ 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),base-commit:
887b913eb2687f34bc056597c0501a4325bebf28
Signature · 2 lines
<http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5