[PATCH v4 1/3] landlock.7: Document Landlock ABI v2 (file reparenting; Linux 5.19)

[PATCH v4 1/3] landlock.7: Document Landlock ABI v2 (file reparenting; Linux 5.19)

[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/20230202204623.10345-1-gnoack3000@gmail.com/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://git.kernel.org/torvalds/c/cb44e4f061e16be65b8a16505e121490c66d30d0
* https://lore.kernel.org/all/20230221165205.4231-1-gnoack3000@gmail.com/ (documentation update)

Signed-off-by: Günther Noack <gnoack3000@gmail.com>
Reviewed-by: Mickaël Salaün <mic@digikod.net>
---
 man7/landlock.7 | 102 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 100 insertions(+), 2 deletions(-)

diff --git a/man7/landlock.7 b/man7/landlock.7
index bbe00d4c2..d3a7ec0d2 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]
+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
+.BR 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,
@@ -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: 0440d04f831796e92d968422b8c49941e046cb8a
-- 
2.39.2

[PATCH v4 2/3] landlock.7: Document Landlock ABI v3 (file truncation; Linux 6.2)

[Günther Noack]

https://git.kernel.org/torvalds/c/299e2b1967578b1442128ba8b3e86ed3427d3651

Signed-off-by: Günther Noack <gnoack3000@gmail.com>
Reviewed-by: Mickaël Salaün <mic@digikod.net>
---
 man7/landlock.7 | 83 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 81 insertions(+), 2 deletions(-)

diff --git a/man7/landlock.7 b/man7/landlock.7
index d3a7ec0d2..9c305edef 100644
--- a/man7/landlock.7
+++ b/man7/landlock.7
@@ -64,9 +64,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,
@@ -231,6 +261,53 @@ 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 introduced in Linux 5.13.
 .PP
@@ -257,6 +334,8 @@ _	_	_
 \^	\^	LANDLOCK_ACCESS_FS_MAKE_SYM
 _	_	_
 2	5.19	LANDLOCK_ACCESS_FS_REFER
+_	_	_
+3	6.2	LANDLOCK_ACCESS_FS_TRUNCATE
 .TE
 .sp 1
 .PP
@@ -302,7 +381,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),
@@ -340,7 +418,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) {
-- 
2.39.2

[PATCH v4 3/3] landlock.7: Give a pointer to how to implement a fallback mechanism

[Günther Noack]

Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---
 man7/landlock.7 | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/man7/landlock.7 b/man7/landlock.7
index 9c305edef..c173cbb98 100644
--- a/man7/landlock.7
+++ b/man7/landlock.7
@@ -393,12 +393,14 @@ 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.
-.PP
+See the
+.B DESCRIPTION
+section for the description of filesystem actions.
 .in +4n
 .EX
 struct landlock_ruleset_attr attr = {0};
@@ -429,6 +431,16 @@ if (ruleset_fd == \-1) {
 .EE
 .in
 .PP
+The ruleset we have constructed requires Landlock ABI version 3 or higher.
+On kernels which do not provide that,
+the call to
+.BR landlock_create_ruleset (2)
+will fail.
+You can build a more graceful fallback mechanism
+by using the version compatibility table from the
+.B VERSIONS
+section.
+.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
-- 
2.39.2

Re: [PATCH v4 3/3] landlock.7: Give a pointer to how to implement a fallback mechanism

[Mickaël Salaün]

On 10/03/2023 23:08, Günther Noack wrote:
> Signed-off-by: Günther Noack <gnoack3000@gmail.com>
> ---
>   man7/landlock.7 | 16 ++++++++++++++--
>   1 file changed, 14 insertions(+), 2 deletions(-)
> 
> diff --git a/man7/landlock.7 b/man7/landlock.7
> index 9c305edef..c173cbb98 100644
> --- a/man7/landlock.7
> +++ b/man7/landlock.7
> @@ -393,12 +393,14 @@ 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.
> -.PP
> +See the
> +.B DESCRIPTION
> +section for the description of filesystem actions.
>   .in +4n
>   .EX
>   struct landlock_ruleset_attr attr = {0};
> @@ -429,6 +431,16 @@ if (ruleset_fd == \-1) {
>   .EE
>   .in
>   .PP
> +The ruleset we have constructed requires Landlock ABI version 3 or higher.
> +On kernels which do not provide that,
> +the call to
> +.BR landlock_create_ruleset (2)
> +will fail.

One of the goal of Landlock is to avoid developers and their code to 
(lazily) error out if one feature is not supported by the running 
kernel. If this happens, a lot of sandboxing will be disabled (and then 
useless) because users don't necessarily have the same kernel as 
developers'.

Such security feature is not the same as a "necessary" feature. Indeed, 
sandboxing is and should be optional for applications to run correctly, 
hence the recommended best-effort approach: 
https://docs.kernel.org/userspace-api/landlock.html#backward-and-forward-compatibility

I agree that the man page should not be too complex, but I think 
teaching the best (default) approach should be the goal.

For the example, we can ignore LANDLOCK_ACCESS_FS_REFER but use all 
other access rights, especially LANDLOCK_ACCESS_FS_TRUNCATE. However, 
this last one should be masked if not supported by the running kernel. 
See 
https://docs.kernel.org/userspace-api/landlock.html#defining-and-enforcing-a-security-policy

An alternative would be to ignore access rights for ABI > 1 to make it 
simple, but this would not help developers dealing with real use cases.

This comment applies to all these 3 patches.


> +You can build a more graceful fallback mechanism
> +by using the version compatibility table from the
> +.B VERSIONS
> +section.
> +.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

Re: [PATCH v4 3/3] landlock.7: Give a pointer to how to implement a fallback mechanism

[Günther Noack]

Thank you for the review!

On Wed, Mar 15, 2023 at 10:39:50PM +0100, Mickaël Salaün wrote:
> On 10/03/2023 23:08, Günther Noack wrote:
> > +The ruleset we have constructed requires Landlock ABI version 3 or higher.
> > +On kernels which do not provide that,
> > +the call to
> > +.BR landlock_create_ruleset (2)
> > +will fail.
> 
> One of the goal of Landlock is to avoid developers and their code to
> (lazily) error out if one feature is not supported by the running kernel. If
> this happens, a lot of sandboxing will be disabled (and then useless)
> because users don't necessarily have the same kernel as developers'.
> 
> Such security feature is not the same as a "necessary" feature. Indeed,
> sandboxing is and should be optional for applications to run correctly,
> hence the recommended best-effort approach: https://docs.kernel.org/userspace-api/landlock.html#backward-and-forward-compatibility
> 
> I agree that the man page should not be too complex, but I think teaching
> the best (default) approach should be the goal.
> 
> For the example, we can ignore LANDLOCK_ACCESS_FS_REFER but use all other
> access rights, especially LANDLOCK_ACCESS_FS_TRUNCATE. However, this last
> one should be masked if not supported by the running kernel. See https://docs.kernel.org/userspace-api/landlock.html#defining-and-enforcing-a-security-policy
> 
> An alternative would be to ignore access rights for ABI > 1 to make it
> simple, but this would not help developers dealing with real use cases.
> 
> This comment applies to all these 3 patches.

I can do it either way, but I would need you and Alejandro to find a
common ground on this.  Alejandro's stance in a previous review thread
was to only support the latest and greatest kernel:
https://lore.kernel.org/linux-man/cb3d6b3e-0c9b-635e-380a-c79e36ae8ede@gmail.com/

Alejandro, what are your thoughts?  (Happy Birthday, btw :))


(My personal stance is: I'm concerned that the man page example might
become too long if we try to add the "best effort" fallback to it, so
I would slightly prefer to explain the fallback logic outside, but
could be convinced otherwise.  I see the point that people might
cut&paste the example from the man page and miss the longer
explanation in a different place.

I have attempted to explain the "best effort" fallback on my weblog
starting from a blank slate, and ended up with the explanation at
https://blog.gnoack.org/post/landlock-best-effort/.  I believe that
most users can use a simpler "best effort" fallback logic when doing
this case analysis, but the explanation is probably too long for the
man page.)

Another alternative would be to make the example assume Landlock v2
(Linux 5.19). In that case, the fallback logic would be simpler and
the case analysis from the weblog entry collapse into a single case,
but the example would fall back to not using Landlock on Linux 5.13 to
5.18 (including the long-term release 5.15), which is also not nice.)

–-Günther

Re: [PATCH v4 3/3] landlock.7: Give a pointer to how to implement a fallback mechanism

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1802 bytes --]

Hi Günther, Mickaël,

On 3/16/23 07:54, Günther Noack wrote:
> Alejandro, what are your thoughts?

It all depends on how much complexity increases.  If it's not much, we
can keep everything.  You can send the complete example, and then if
it's too much we can cut pieces of it.

>  (Happy Birthday, btw :))

:)

> 
> 
> (My personal stance is: I'm concerned that the man page example might
> become too long if we try to add the "best effort" fallback to it, so
> I would slightly prefer to explain the fallback logic outside, but
> could be convinced otherwise.  I see the point that people might
> cut&paste the example from the man page and miss the longer
> explanation in a different place.
> 
> I have attempted to explain the "best effort" fallback on my weblog
> starting from a blank slate, and ended up with the explanation at
> https://blog.gnoack.org/post/landlock-best-effort/.  I believe that
> most users can use a simpler "best effort" fallback logic when doing
> this case analysis, but the explanation is probably too long for the
> man page.)
> 
> Another alternative would be to make the example assume Landlock v2
> (Linux 5.19). In that case, the fallback logic would be simpler and
> the case analysis from the weblog entry collapse into a single case,
> but the example would fall back to not using Landlock on Linux 5.13 to
> 5.18 (including the long-term release 5.15), which is also not nice.)

Debian Bullseye (stable) has 6.0.12 in bullseye-backports.  Maybe it's
not crazy to assume >=5.19.  No Debian release has anything in the
range [5.13, 5.18] (non-backports Bullseye has 5.10).

> 
> –-Günther

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v4 3/3] landlock.7: Give a pointer to how to implement a fallback mechanism

[Mickaël Salaün]

OK, so if that makes the sample code simpler, I guess we can assume (and 
note) that this if for a kernel >= 5.19, hence force the use of 
LANDLOCK_ACCESS_FS_REFER (e.g. the app needs to rename files in a 
temporary directory), and only handle the LANDLOCK_ACCESS_FS_TRUNCATE 
right as optional.


On 16/03/2023 14:33, Alejandro Colomar wrote:
> Hi Günther, Mickaël,
> 
> On 3/16/23 07:54, Günther Noack wrote:
>> Alejandro, what are your thoughts?
> 
> It all depends on how much complexity increases.  If it's not much, we
> can keep everything.  You can send the complete example, and then if
> it's too much we can cut pieces of it.
> 
>>   (Happy Birthday, btw :))
> 
> :)
> 
>>
>>
>> (My personal stance is: I'm concerned that the man page example might
>> become too long if we try to add the "best effort" fallback to it, so
>> I would slightly prefer to explain the fallback logic outside, but
>> could be convinced otherwise.  I see the point that people might
>> cut&paste the example from the man page and miss the longer
>> explanation in a different place.
>>
>> I have attempted to explain the "best effort" fallback on my weblog
>> starting from a blank slate, and ended up with the explanation at
>> https://blog.gnoack.org/post/landlock-best-effort/.  I believe that
>> most users can use a simpler "best effort" fallback logic when doing
>> this case analysis, but the explanation is probably too long for the
>> man page.)
>>
>> Another alternative would be to make the example assume Landlock v2
>> (Linux 5.19). In that case, the fallback logic would be simpler and
>> the case analysis from the weblog entry collapse into a single case,
>> but the example would fall back to not using Landlock on Linux 5.13 to
>> 5.18 (including the long-term release 5.15), which is also not nice.)
> 
> Debian Bullseye (stable) has 6.0.12 in bullseye-backports.  Maybe it's
> not crazy to assume >=5.19.  No Debian release has anything in the
> range [5.13, 5.18] (non-backports Bullseye has 5.10).
> 
>>
>> –-Günther
> 
> Cheers,
> 
> Alex
>