[PATCH 2/2] landlock: Clarify IPC scoping documentation

[Günther Noack]

Hi!

This is an attempt to clarify the kernel documentation for Landlock's IPC
scoping support before I send the same wording to the man page list in troff
format.

(Adding Alejandro and the man-page list to get an early review on wording and
clarity.)

On Fri, Jan 24, 2025 at 03:44:45PM +0000, Günther Noack wrote:
> * Clarify terminology
> * Stop mixing the unix(7) and signal(7) aspects in the explanation.
> 
> Terminology:
> 
> * The *IPC Scope* of a Landlock domain is that Landlock domain and its
>   nested domains.
> * An *operation* (e.g., signaling, connecting to abstract UDS) is said
>   *to be scoped within a domain* when the flag for that operation was
>   *set at ruleset creation time.  This means that for the purpose of
>   *this operation, only processes within the domain's IPC scope are
>   *reachable.
> 
> Cc: Mickaël Salaün <mic at digikod.net>
> Cc: Tahera Fahimi <fahimitahera at gmail.com>
> Cc: Tanya Agarwal <tanyaagarwal25699 at gmail.com>
> Signed-off-by: Günther Noack <gnoack at google.com>
> ---
>  Documentation/userspace-api/landlock.rst | 53 ++++++++++++------------
>  1 file changed, 26 insertions(+), 27 deletions(-)
> 
> diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
> index ca8b325d53e5..6b80106d33de 100644
> --- a/Documentation/userspace-api/landlock.rst
> +++ b/Documentation/userspace-api/landlock.rst
> @@ -317,33 +317,32 @@ IPC scoping
>  -----------
>  
>  Similar 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 a restriction with ``LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET``.
> -Moreover, if a sandboxed process should not be able to send a signal to a
> -non-sandboxed process, we can specify this restriction with
> -``LANDLOCK_SCOPE_SIGNAL``.
> -
> -A sandboxed process can connect to a non-sandboxed process when its domain is
> -not scoped. If a process's domain is scoped, it can only connect to sockets
> -created by processes in the same scope.
> -Moreover, if a process is scoped to send signal to a non-scoped process, it can
> -only send signals to processes in the same scope.
> -
> -A connected datagram socket behaves like a stream socket when its domain is
> -scoped, meaning if the domain is scoped after the socket is connected, it can
> -still :manpage:`send(2)` data just like a stream socket.  However, in the same
> -scenario, a non-connected datagram socket cannot send data (with
> -:manpage:`sendto(2)`) outside its scope.
> -
> -A process with a scoped domain can inherit a socket created by a non-scoped
> -process. The process cannot connect to this socket since it has a scoped
> -domain.

Tahera, Mickaël:

I suspect what was meant in this paragraph are Abstract Unix Domain Sockets of
the datagram type? -- the scenario where the process has an (unconnected) Unix
Datagram Socket and then can not call connect(2) or send(2) *on* it?

I removed this paragraph because I believe it's sufficiently covered in the
section that I wrote about Abstract Unix Domain Sockets below.  If I'm
misunderstanding this, please let me know. :)

> -
> -IPC scoping does not support exceptions, so if a domain is scoped, no rules can
> -be added to allow access to resources or processes outside of the scope.
> +interactions between sandboxes.  Therefore, at ruleset creation time, each
> +Landlock domain can restrict the scope for certain operations, so that these
> +operations can only reach out to processes within the same Landlock domain or in
> +a nested Landlock domain (the "scope").
> +
> +The operations which can be scoped are:
> +
> +``LANDLOCK_SCOPE_SIGNAL``
> +    When set, this limits the sending of signals to target processes which run
> +    within the same or a nested Landlock domain.
> +
> +``LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET``
> +    When set, this limits the set of abstract :manpage:`unix(7)` sockets we can
> +    :manpage:`connect(2)` to to socket addresses which were created by a process
> +    in the same or a nested Landlock domain.
> +
> +    A :manpage:`send(2)` on a non-connected datagram socket is treated like an
> +    implicit :manpage:`connect(2)` and will be blocked when the remote end does
> +    not stem from the same or a nested Landlock domain.
> +
> +    A :manpage:`send(2)` on a socket which was previously connected will work.
> +    This works for both datagram and stream sockets.
> +
> +IPC scoping does not support exceptions via :manpage:`landlock_add_rule(2)`.
> +If an operation is scoped within a domain, no rules can be added to allow access
> +to resources or processes outside of the scope.
>  
>  Truncating files
>  ----------------
> -- 
> 2.48.1.262.g85cc9f2d1e-goog
> 

—Günther