Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)

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

On Wed, Feb 22, 2023 at 08:45:28AM +0100, Mickaël Salaün wrote:
> On 2023-02-21T21:50:22.000+01:00, Günther Noack wrote:
> > @@ -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