[PATCH v7 4/4] documentation/landlock: Adding scoping mechanism documentation

[Mickaël Salaün]

The subject should start with "landlock:" not "documentation/landlock:"
See similar commits.

On Wed, Jul 17, 2024 at 10:15:22PM -0600, Tahera Fahimi wrote:
> - Defining ABI version 6 that supports IPC restriction.
> - Adding "scoped" to the "Access rights".
> - In current limitation, unnamed sockets are specified as
>   sockets that are not restricted.

It would help to write (small) paragraphs instead of bullet points (here
and for other patches).

> 
> Signed-off-by: Tahera Fahimi <fahimitahera at gmail.com>
> ---
>  Documentation/userspace-api/landlock.rst | 23 ++++++++++++++++++++---
>  1 file changed, 20 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
> index 07b63aec56fa..61b91cc03560 100644
> --- a/Documentation/userspace-api/landlock.rst
> +++ b/Documentation/userspace-api/landlock.rst
> @@ -8,7 +8,7 @@ Landlock: unprivileged access control
>  =====================================
>  
>  :Author: Mickaël Salaün
> -:Date: April 2024
> +:Date: July 2024
>  
>  The goal of Landlock is to enable to restrict ambient rights (e.g. global
>  filesystem or network access) for a set of processes.  Because Landlock
> @@ -306,6 +306,16 @@ To be allowed to use :manpage:`ptrace(2)` 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.
>  
> +IPC Scoping
> +-----------
> +
> +Similar to Ptrace, a sandboxed process should not be able to access the resources
> +(like abstract unix sockets, or signals) outside of the sandbox domain. For example,
> +a sandboxed process should not be able to :manpage:`connect(2)` to a non-sandboxed
> +process through abstract unix sockets (:manpage:`unix(7)`). This restriction is
> +applicable by optionally specifying ``LANDLOCK_SCOPED_ABSTRACT_UNIX_SOCKET`` in
> +the ruleset.

Here is a proposal based on your text:

Complementary to the implicit `ptrace restrictions`_, we may want to
further restrict interactions between sandboxes.  Each Landlock domain
can be explicitly scoped for a set of actions by specifying it on a
ruleset.

For example, if a sandboxed process should not be able to
:manpage:`connect(2)` to a non-sandboxed process through abstract
:manpage:`unix(7)` sockets, we can specify such restriction with
``LANDLOCK_SCOPED_ABSTRACT_UNIX_SOCKET``.


(We also need to explain how scoping works, especially between scoped
and non-scoped domains)

> +
>  Truncating files
>  ----------------
>  
> @@ -404,7 +414,7 @@ Access rights
>  -------------
>  
>  .. kernel-doc:: include/uapi/linux/landlock.h
> -    :identifiers: fs_access net_access
> +    :identifiers: fs_access net_access scoped
>  
>  Creating a new ruleset
>  ----------------------
> @@ -446,7 +456,7 @@ Special filesystems
>  
>  Access to regular files and directories can be restricted by Landlock,
>  according to the handled accesses of a ruleset.  However, files that do not
> -come from a user-visible filesystem (e.g. pipe, socket), but can still be
> +come from a user-visible filesystem (e.g. pipe, unnamed socket), but can still be

Why this change? Opened named sockets are still visible in /proc/self/fd/

>  accessed through ``/proc/<pid>/fd/*``, cannot currently be explicitly
>  restricted.  Likewise, some special kernel filesystems such as nsfs, which can
>  be accessed through ``/proc/<pid>/ns/*``, cannot currently be explicitly
> @@ -541,6 +551,13 @@ earlier ABI.
>  Starting with the Landlock ABI version 5, it is possible to restrict the use of
>  :manpage:`ioctl(2)` using the new ``LANDLOCK_ACCESS_FS_IOCTL_DEV`` right.
>  
> +Special filesystems (ABI < 6)

"Special filesystems"? This patch series is about abstract unix socket
scoping.  The signal scoping one can inlcude a patch rewriting this title.

> +-----------------------------
> +
> +With ABI version 6, it is possible to restrict IPC actions such as connecting to

The signal patch series may be merged with this one for the same kernel
release but we should be explicit about the *current" changes.  You can
write this section talking only about
LANDLOCK_SCOPED_ABSTRACT_UNIX_SOCKET, and in the signal scoping patch
series you can extend this section.

> +an abstract Unix socket through ``LANDLOCK_SCOPED_ABSTRACT_UNIX_SOCKET``, thanks
> +to the ``.scoped`` ruleset attribute.

The dot is superfluous (here and in comments):

"thanks to the ruleset's ``scoped`` attribute."

> +
>  .. _kernel_support:
>  
>  Kernel support
> -- 
> 2.34.1
> 
>