On Fri, Dec 08, 2023 at 04:51:21PM +0100, Günther Noack wrote: > In the paragraph above the fallback logic, use the shorter phrasing > from the landlock(7) man page. > > Signed-off-by: Günther Noack <gnoack@xxxxxxxxxx> > --- > Documentation/userspace-api/landlock.rst | 119 ++++++++++++++++++++--- > 1 file changed, 104 insertions(+), 15 deletions(-) > > +Restricting IOCTL commands > +-------------------------- > + > +When the ``LANDLOCK_ACCESS_FS_IOCTL`` access right is handled, Landlock will > +restrict the invocation of IOCTL commands. However, to *permit* these IOCTL > +commands again, some of these IOCTL commands are then granted through other, > +preexisting access rights. > + > +For example, consider a program which handles ``LANDLOCK_ACCESS_FS_IOCTL`` and > +``LANDLOCK_ACCESS_FS_READ_FILE``. The program *permits* > +``LANDLOCK_ACCESS_FS_READ_FILE`` on a file ``foo.log``. > + > +By virtue of granting this access on the ``foo.log`` file, it is now possible to > +use common and harmless IOCTL commands which are useful when reading files, such > +as ``FIONREAD``. > + > +On the other hand, if the program permits ``LANDLOCK_ACCESS_FS_IOCTL`` on > +another file, ``FIONREAD`` will not work on that file when it is opened. As > +soon as ``LANDLOCK_ACCESS_FS_READ_FILE`` is *handled* in the ruleset, the IOCTL > +commands affected by it can not be reenabled though ``LANDLOCK_ACCESS_FS_IOCTL`` > +any more, but are then governed by ``LANDLOCK_ACCESS_FS_READ_FILE``. > + > +The following table illustrates how IOCTL attempts for ``FIONREAD`` are > +filtered, depending on how a Landlock ruleset handles and permits the > +``LANDLOCK_ACCESS_FS_IOCTL`` and ``LANDLOCK_ACCESS_FS_READ_FILE`` access rights: > + > ++------------------------+-------------+-------------------+-------------------+ > +| | ``IOCTL`` | ``IOCTL`` handled | ``IOCTL`` handled | > +| | not handled | and permitted | and not permitted | > ++------------------------+-------------+-------------------+-------------------+ > +| ``READ_FILE`` not | allow | allow | deny | > +| handled | | | | > ++------------------------+ +-------------------+-------------------+ > +| ``READ_FILE`` handled | | allow | > +| and permitted | | | > ++------------------------+ +-------------------+-------------------+ > +| ``READ_FILE`` handled | | deny | > +| and not permitted | | | > ++------------------------+-------------+-------------------+-------------------+ Great! Could you please format this table with the flat-table syntax? See https://docs.kernel.org/doc-guide/sphinx.html#tables > + > +The full list of IOCTL commands and the access rights which affect them is > +documented below.
