Re: [PATCH v5 3/3] landlock.7: Explain the best-effort fallback mechanism in the example

["Günther Noack" <gnoack3000@gmail.com>]

P.S.: I went back and forth a bit with the example,
but ended up implementing the full backwards compatibility
across all three existing Landlock versions for now.

The example corresponds to the simple case 1 from
https://blog.gnoack.org/post/landlock-best-effort/,
where the program does *not* need the refer right
after Landlock restriction.
This is not much more complicated than the variant
which is compatible with ABI V2 and V3.

Below the new part of the example,
I added a paragraph to talk about case 2,
where the program *does* need the refer right.
I hope this will be enough to keep most people
from implementing the fallback the wrong way.

Case 3 from the weblog article (where it can be either)
can be deduced with normal logic reasoning and hopefully
should not need additional explanation. -- You need
to figure out at runtime whether you are in case 1 or 2,
and then apply the respective logic.

Let me know what you think!
–Günther

On Fri, Mar 24, 2023 at 06:24:19PM +0100, Günther Noack wrote:
> Signed-off-by: Günther Noack <gnoack3000@gmail.com>
> ---
>  man7/landlock.7 | 65 ++++++++++++++++++++++++++++++++++++++++++++++---
>  1 file changed, 61 insertions(+), 4 deletions(-)
> 
> diff --git a/man7/landlock.7 b/man7/landlock.7
> index 9c305edef..d1214ba27 100644
> --- a/man7/landlock.7
> +++ b/man7/landlock.7
> @@ -393,11 +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.
> +See the
> +.B DESCRIPTION
> +section for the description of filesystem actions.
>  .PP
>  .in +4n
>  .EX
> @@ -420,7 +423,57 @@ attr.handled_access_fs =
>          LANDLOCK_ACCESS_FS_MAKE_SYM |
>          LANDLOCK_ACCESS_FS_REFER |
>          LANDLOCK_ACCESS_FS_TRUNCATE;
> +.EE
> +.in
> +.PP
> +To be compatible with older Linux versions,
> +we detect the available Landlock ABI version,
> +and only use the available subset of access rights:
> +.PP
> +.in +4n
> +.EX
> +/* Table of available file system access rights by ABI version */
> +__u64 landlock_fs_access_rights[] = {
> +    (1ULL << 13) \- 1,  /* ABI v1                 */
> +    (1ULL << 14) \- 1,  /* ABI v2: add "refer"    */
> +    (1ULL << 15) \- 1,  /* ABI v3: add "truncate" */
> +};
> +
> +int abi = landlock_create_ruleset(NULL, 0,
> +                                  LANDLOCK_CREATE_RULESET_VERSION);
> +if (abi <= 0) {
> +    perror("Giving up \- No Landlock support");
> +    exit(EXIT_FAILURE);
> +}
> +if (abi > 3)
> +    abi = 3;
>  
> +/* Only use the available rights in the ruleset. */
> +attr.handled_access_fs &= landlock_fs_access_rights[abi \- 1];
> +.EE
> +.in
> +.PP
> +The available access rights for each ABI version are listed in the
> +.B VERSIONS
> +section.
> +.PP
> +If our program needed to create hard links or rename files between different directories
> +.RB ( LANDLOCK_ACCESS_FS_REFER ),
> +we would require the following change to the backwards compatibility logic:
> +Directory reparenting is not possible in a process restricted with Landlock ABI version 1.
> +Therefore,
> +if the program needed to do file reparenting,
> +and if only Landlock ABI version 1 was available,
> +we could not restrict the process.
> +.PP
> +Now that the ruleset attributes are determined,
> +we create the Landlock ruleset
> +and acquire a file descriptor as a handle to it,
> +using
> +.BR landlock_create_ruleset (2):
> +.PP
> +.in +4n
> +.EX
>  ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0);
>  if (ruleset_fd == \-1) {
>      perror("Failed to create a ruleset");
> @@ -429,9 +482,13 @@ if (ruleset_fd == \-1) {
>  .EE
>  .in
>  .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
> +We can now add a new rule to the ruleset through the ruleset's file descriptor.
> +The requested access rights must be a subset of the access rights
> +which were specified in
> +.I attr.handled_access_fs
> +at ruleset creation time.
> +.PP
> +In this example, the rule will only allow reading the file hierarchy
>  .IR /usr .
>  Without another rule, write actions would then be denied by the ruleset.
>  To add
> -- 
> 2.39.2
>