[PATCH v7 9/9] landlock: Document IOCTL support

[Günther Noack]

Hello Jeff!

On Fri, Dec 01, 2023 at 11:55:03AM -0800, Jeff Xu wrote:
> On Fri, Dec 1, 2023 at 6:41 AM Günther Noack <gnoack at google.com> wrote:
> > +Rights associated with file descriptors
> > +---------------------------------------
> > +
> > +When opening a file, the availability of the ``LANDLOCK_ACCESS_FS_TRUNCATE`` and
> > +``LANDLOCK_ACCESS_FS_IOCTL`` rights is associated with the newly created file
> > +descriptor and will be used for subsequent truncation and ioctl attempts using
> > +:manpage:`ftruncate(2)` and :manpage:`ioctl(2)`.  The behavior is similar to
> > +opening a file for reading or writing, where permissions are checked during
> > +:manpage:`open(2)`, but not during the subsequent :manpage:`read(2)` and
> >  :manpage:`write(2)` calls.
> >
> > -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.
> > +As a consequence, it is possible to have multiple open file descriptors
> > +referring to the same file, where one grants the truncate or ioctl right 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.
> >
> I understand the "passing fd between process ", but not the " multiple
> open fds referring to the same file, with different permission", are
> those fds all opened within the same domain ?
> 
> Can we have a pseudocode to help understanding ?

It's a little bit expanding the scope here, as the documentation existed alredy
prior to the patch set, but it's a fair comment that this paragraph is not clear
enough.  I tried to rephrase it.  Maybe this is better:

  As a consequence, it is possible that a process has multiple open file
  descriptors referring to the same file, but Landlock enforces different things
  when operating with these file descriptors.  This can happen when a Landlock
  ruleset gets enforced and the process keeps file descriptors which were opened
  both before and after the enforcement.  It is also possible to pass such file
  descriptors between processes, keeping their Landlock properties, even when
  some of the involved processes do not have an enforced Landlock ruleset.

Some example code to clarify:

One way that this can happen is:

  (1) fd1 = open("foobar.txt", O_RDWR)
  (2) enforce_landlock(forbid all ioctls)
  (3) fd2 = open("foobar.txt", O_RDWR)

  ==> You now have fd1 and fd2 referring to the same file on disk,
      but you can only do ioctls on it through fd1, but not through fd2.

Or, using SCM_RIGHTS (unix(7)):

  (1) Process 1: Listen on Unix socket
  (2) Process 2: Enforce Landlock so that ioctls are forbidden
  (3) Process 2: fd = open("foobar.txt", O_RDWR)
  (4) Process 2: send fd to Process 1
  (5) Process 1: receive fd

  ==> Process 1 can not do ioctls on the received fd,
      as configured by the Landlock policy enforced in Process 2

Or, simply by inheriting file descriptors through execve:

  (1) Parent process/main thread: Spawn thread t
    (t.1) Enforce Landlock so that ioctls are forbidden
          (This policy is local to the thread)
    (t.2) fd = open("foobar.txt", O_RDWR)
  (2) Parent process/main thread: join (exit) thread t
  (3) Parent process/main thread: execve and inherit fd!

  ==> The child process can not use ioctls with the inherited fd,
      as configured by the Landlock policy before

The same is also possible with the truncation right.

—Günther