[v2,0/1] landlock: Clarify IPC scoping documentation

Message

Günther Noack Feb. 26, 2025, 9:18 p.m. UTC

Hello!

Thank you for your feedback, here is the second version.

Changes in V2:

* As Mickaël already applied the first commit ("Minor typo and grammar fixes in
  IPC scoping documentation"), this one is left out here.

* Applied remarks by Daniel Burgener, Alejandro Colomar and Mickaël Salaün

* Replaced reference to send(2) with sendto(2), which is slightly more
  appropriate in that place.

For your convenience, the range-diff at the bottom shows the diff between the
two patch sets (checkpatch.pl complains about it, but it's just in the cover
letter).

—Günther

Günther Noack (1):
  landlock: Clarify IPC scoping documentation

 Documentation/userspace-api/landlock.rst | 45 ++++++++++++------------
 1 file changed, 22 insertions(+), 23 deletions(-)

Range-diff against v1:
1:  7df39814a3a6 < -:  ------------ landlock: Minor typo and grammar fixes in IPC scoping documentation
2:  c86636efac8d ! 1:  d288be2c7b94 landlock: Clarify IPC scoping documentation
    @@ Commit message
     
         * 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.
    +    * 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 <[e-mail]>
    -    Cc: Tahera Fahimi <[e-mail]>
    -    Cc: Tanya Agarwal <[e-mail]>
         Signed-off-by: Günther Noack <[e-mail]>
     
      ## Documentation/userspace-api/landlock.rst ##
    @@ Documentation/userspace-api/landlock.rst: IPC scoping
     -scenario, a non-connected datagram socket cannot send data (with
     -:manpage:`sendto(2)`) outside its scope.
     +``LANDLOCK_SCOPE_SIGNAL``
    -+    When set, this limits the sending of signals to target processes which run
    -+    within the same or a nested Landlock domain.
    ++    This limits the sending of signals to target processes which run within the
    ++    same or a nested Landlock domain.
      
     -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.
     +``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.
    ++    This limits the set of abstract :manpage:`unix(7)` sockets to which we can
    ++    :manpage:`connect(2)` to socket addresses which were created by a process in
    ++    the same or a nested Landlock domain.
      
     -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.
    -+    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:`sendto(2)` on a non-connected datagram socket is treated as if
    ++    it were doing an implicit :manpage:`connect(2)` and will be blocked if 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.
    ++    A :manpage:`sendto(2)` on a socket which was previously connected will not
    ++    be restricted.  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