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

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

[Günther Noack]

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 <mic@digikod.net>
    -    Cc: Tahera Fahimi <fahimitahera@gmail.com>
    -    Cc: Tanya Agarwal <tanyaagarwal25699@gmail.com>
         Signed-off-by: Günther Noack <gnoack@google.com>
     
      ## 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
-- 
2.48.1.711.g2feabab25a-goog

[PATCH v2 1/1] landlock: Clarify IPC scoping documentation

[Günther Noack]

* 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.

Signed-off-by: Günther Noack <gnoack@google.com>
---
 Documentation/userspace-api/landlock.rst | 45 ++++++++++++------------
 1 file changed, 22 insertions(+), 23 deletions(-)

diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
index ad587f53fe41..4832b16deedb 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``.
+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").
 
-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.
+The operations which can be scoped are:
 
-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.
+``LANDLOCK_SCOPE_SIGNAL``
+    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``
+    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:`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:`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
+to resources or processes outside of the scope.
 
 Truncating files
 ----------------
-- 
2.48.1.711.g2feabab25a-goog

[PATCH v2 1/3] landlock.7: Update description of Landlock rules

[Günther Noack]

This brings it up to date with the wording in the kernel documentation.

Signed-off-by: Günther Noack <gnoack@google.com>
---
 man/man7/landlock.7 | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
index c6b7272ea..11f76b072 100644
--- a/man/man7/landlock.7
+++ b/man/man7/landlock.7
@@ -39,13 +39,25 @@ the running kernel must support Landlock and
 it must be enabled at boot time.
 .\"
 .SS Landlock rules
-A Landlock rule describes an action on an object.
-An object is currently a file hierarchy,
-and the related filesystem actions are defined with access rights (see
-.BR landlock_add_rule (2)).
+A Landlock rule describes an action on an object
+which the process intends to perform.
 A set of rules is aggregated in a ruleset,
 which can then restrict the thread enforcing it,
 and its future children.
+.P
+The two existing types of rules are:
+.P
+.TP
+.B Filesystem rules
+For these rules, the object is a file hierarchy,
+and the related filesystem actions are defined with
+.IR "filesystem access rights" .
+.TP
+.B Network rules (since ABI v4)
+For these rules, the object is a TCP port,
+and the related actions are defined with
+.IR "network access rights" .
+.BR landlock_add_rule (2)).
 .\"
 .SS Filesystem actions
 These flags enable to restrict a sandboxed process to a
-- 
2.48.1.711.g2feabab25a-goog

[PATCH v2 2/3] landlock.7: Move over documentation for ABI version 6

[Günther Noack]

With this ABI version, Landlock can restrict outgoing interactions with
higher-privileged Landlock domains through Abstract Unix Domain sockets and
signals.

Signed-off-by: Günther Noack <gnoack@google.com>
---
 man/man7/landlock.7 | 69 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 68 insertions(+), 1 deletion(-)

diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
index 11f76b072..30dbac73d 100644
--- a/man/man7/landlock.7
+++ b/man/man7/landlock.7
@@ -248,7 +248,8 @@ This access right is available since the fifth version of the Landlock ABI.
 .SS Network flags
 These flags enable to restrict a sandboxed process
 to a set of network actions.
-This is supported since the Landlock ABI version 4.
+.P
+This is supported since Landlock ABI version 4.
 .P
 The following access rights apply to TCP port numbers:
 .TP
@@ -258,6 +259,24 @@ Bind a TCP socket to a local port.
 .B LANDLOCK_ACCESS_NET_CONNECT_TCP
 Connect an active TCP socket to a remote port.
 .\"
+.SS Scope flags
+These flags enable to isolate a sandboxed process from a set of IPC actions.
+Setting a flag for a ruleset will isolate the Landlock domain
+to forbid connections to resources outside the domain.
+.P
+This is supported since Landlock ABI version 6.
+.P
+The following scopes exist:
+.TP
+.B LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
+Restrict a sandboxed process from connecting to an abstract UNIX socket
+created by a process outside the related Landlock domain
+(e.g., a parent domain or a non-sandboxed process).
+.TP
+.B LANDLOCK_SCOPE_SIGNAL
+Restrict a sandboxed process from sending a signal
+to another process outside the domain.
+.\"
 .SS Layers of file path access rights
 Each time a thread enforces a ruleset on itself,
 it updates its Landlock domain with a new layer of policy.
@@ -334,6 +353,51 @@ 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.
 .\"
+.SS IPC scoping
+Similar to the implicit
+.BR "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
+.BR connect (2)
+to a non-sandboxed process through abstract
+.BR unix (7)
+sockets,
+we can specify such a restriction with
+.BR 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
+.BR LANDLOCK_SCOPE_SIGNAL .
+.P
+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.
+.P
+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
+.BR send (2)
+data just like a stream socket.
+However, in the same scenario,
+a non-connected datagram socket cannot send data (with
+.BR sendto (2))
+outside its scope.
+.P
+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.
+.P
+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.
+.\"
 .SS Truncating files
 The operations covered by
 .B LANDLOCK_ACCESS_FS_WRITE_FILE
@@ -413,6 +477,9 @@ _	_	_
 \^	\^	LANDLOCK_ACCESS_NET_CONNECT_TCP
 _	_	_
 5	6.10	LANDLOCK_ACCESS_FS_IOCTL_DEV
+_	_	_
+6	6.12	LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
+\^	\^	LANDLOCK_SCOPE_SIGNAL
 .TE
 .P
 Users should use the Landlock ABI version rather than the kernel version
-- 
2.48.1.711.g2feabab25a-goog

[PATCH v2 3/3] landlock.7: Clarify IPC scoping documentation in line with kernel side

[Günther Noack]

* 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.

Link: https://lore.kernel.org/all/20250226211814.31420-4-gnoack@google.com/
Signed-off-by: Günther Noack <gnoack@google.com>
---
 man/man7/landlock.7 | 73 ++++++++++++++++++++++-----------------------
 1 file changed, 35 insertions(+), 38 deletions(-)

diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
index 30dbac73d..42cd7286f 100644
--- a/man/man7/landlock.7
+++ b/man/man7/landlock.7
@@ -357,46 +357,43 @@ which means the tracee must be in a sub-domain of the tracer.
 Similar to the implicit
 .BR "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
-.BR connect (2)
-to a non-sandboxed process through abstract
+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").
+.P
+The operations which can be scoped are:
+.P
+.TP
+.B LANDLOCK_SCOPE_SIGNAL
+This limits the sending of signals to target processes
+which run within the same or a nested Landlock domain.
+.TP
+.B LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
+This limits the set of abstract
 .BR unix (7)
-sockets,
-we can specify such a restriction with
-.BR 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
-.BR LANDLOCK_SCOPE_SIGNAL .
+sockets to which we can
+.BR connect (2)
+to socket addresses which were created
+by a process in the same or a nested Landlock domain.
+.IP
+A
+.BR sendto (2)
+on a non-connected datagram socket is treated as if it were doing an implicit
+.BR connect (2)
+and will be blocked if the remote end does not stem
+from the same or a nested Landlock domain.
+.IP
+A
+.BR sendto (2)
+on a socket which was previously connected will not be restricted.
+This works for both datagram and stream sockets.
 .P
-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.
-.P
-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
-.BR send (2)
-data just like a stream socket.
-However, in the same scenario,
-a non-connected datagram socket cannot send data (with
-.BR sendto (2))
-outside its scope.
-.P
-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.
-.P
-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.
+IPC scoping does not support exceptions via
+.BR 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.
 .\"
 .SS Truncating files
 The operations covered by
-- 
2.48.1.711.g2feabab25a-goog

Re: [PATCH v2 1/3] landlock.7: Update description of Landlock rules

[Günther Noack]

On Wed, Feb 26, 2025 at 10:29:10PM +0100, Günther Noack wrote:
> This brings it up to date with the wording in the kernel documentation.
> 
> Signed-off-by: Günther Noack <gnoack@google.com>

Apologies, I missed to add a "man" tag to the last three subject lines.
The last three commits in the overall patch set belong to the man-pages repo.

(See threaded view at
https://lore.kernel.org/all/20250226211814.31420-2-gnoack@google.com/ for the
full overview)

—Günther

Re: [PATCH v2 2/3] landlock.7: Move over documentation for ABI version 6

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 5194 bytes --]

Hi Günther!

On Wed, Feb 26, 2025 at 10:29:11PM +0100, Günther Noack wrote:
> With this ABI version, Landlock can restrict outgoing interactions with
> higher-privileged Landlock domains through Abstract Unix Domain sockets and
> signals.
> 
> Signed-off-by: Günther Noack <gnoack@google.com>
> ---
>  man/man7/landlock.7 | 69 ++++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 68 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
> index 11f76b072..30dbac73d 100644
> --- a/man/man7/landlock.7
> +++ b/man/man7/landlock.7
> @@ -248,7 +248,8 @@ This access right is available since the fifth version of the Landlock ABI.
>  .SS Network flags
>  These flags enable to restrict a sandboxed process
>  to a set of network actions.
> -This is supported since the Landlock ABI version 4.
> +.P
> +This is supported since Landlock ABI version 4.
>  .P
>  The following access rights apply to TCP port numbers:
>  .TP
> @@ -258,6 +259,24 @@ Bind a TCP socket to a local port.
>  .B LANDLOCK_ACCESS_NET_CONNECT_TCP
>  Connect an active TCP socket to a remote port.
>  .\"
> +.SS Scope flags
> +These flags enable to isolate a sandboxed process from a set of IPC actions.

s/to isolate/isolating/

AFAIU, to be able to use an infinitive with enable/allow you need a
direct object in the sentence.  If there's no direct object, you need a
gerund.

> +Setting a flag for a ruleset will isolate the Landlock domain
> +to forbid connections to resources outside the domain.
> +.P
> +This is supported since Landlock ABI version 6.

I'm wondering if we should have this as a parenthetical next to the
title, like we usually do with "(since Linux X.Y)".  Don't do it for
now, but please consider it for when you have some time.  I'm not saying
you should do it though, just that you consider it, and tell me if you
agree or not.

> +.P
> +The following scopes exist:
> +.TP
> +.B LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
> +Restrict a sandboxed process from connecting to an abstract UNIX socket
> +created by a process outside the related Landlock domain
> +(e.g., a parent domain or a non-sandboxed process).
> +.TP
> +.B LANDLOCK_SCOPE_SIGNAL
> +Restrict a sandboxed process from sending a signal
> +to another process outside the domain.
> +.\"
>  .SS Layers of file path access rights
>  Each time a thread enforces a ruleset on itself,
>  it updates its Landlock domain with a new layer of policy.
> @@ -334,6 +353,51 @@ 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.
>  .\"
> +.SS IPC scoping
> +Similar to the implicit
> +.BR "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
> +.BR connect (2)
> +to a non-sandboxed process through abstract
> +.BR unix (7)
> +sockets,
> +we can specify such a restriction with
> +.BR 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
> +.BR LANDLOCK_SCOPE_SIGNAL .
> +.P
> +A sandboxed process can connect to a non-sandboxed process
> +when its domain is not scoped.

Does "its" refer to the sandboxed one or to the non-snadboxed one?

> +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

Is this a typo?  s/signal/&s/

> to a non-scoped process,

Should we use plural here?

> +it can only send signals to processes in the same scope.
> +.P
> +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
> +.BR send (2)
> +data just like a stream socket.
> +However, in the same scenario,
> +a non-connected datagram socket cannot send data (with
> +.BR sendto (2))
> +outside its scope.
> +.P
> +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.
> +.P
> +IPC scoping does not support exceptions, so if a domain is scoped,

Please break after the first ',' too.

> +no rules can be added to allow access to resources or processes

Please break after the second 'to'.

> +outside of the scope.
> +.\"
>  .SS Truncating files
>  The operations covered by
>  .B LANDLOCK_ACCESS_FS_WRITE_FILE
> @@ -413,6 +477,9 @@ _	_	_
>  \^	\^	LANDLOCK_ACCESS_NET_CONNECT_TCP
>  _	_	_
>  5	6.10	LANDLOCK_ACCESS_FS_IOCTL_DEV
> +_	_	_
> +6	6.12	LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
> +\^	\^	LANDLOCK_SCOPE_SIGNAL
>  .TE
>  .P
>  Users should use the Landlock ABI version rather than the kernel version
> -- 
> 2.48.1.711.g2feabab25a-goog
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 1/3] landlock.7: Update description of Landlock rules

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2590 bytes --]

Hi,

On Wed, Feb 26, 2025 at 10:29:10PM +0100, Günther Noack wrote:
> This brings it up to date with the wording in the kernel documentation.
> 
> Signed-off-by: Günther Noack <gnoack@google.com>

I'd like some more justification in the commit message.

> ---
>  man/man7/landlock.7 | 20 ++++++++++++++++----
>  1 file changed, 16 insertions(+), 4 deletions(-)
> 
> diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
> index c6b7272ea..11f76b072 100644
> --- a/man/man7/landlock.7
> +++ b/man/man7/landlock.7
> @@ -39,13 +39,25 @@ the running kernel must support Landlock and
>  it must be enabled at boot time.
>  .\"
>  .SS Landlock rules
> -A Landlock rule describes an action on an object.
> -An object is currently a file hierarchy,
> -and the related filesystem actions are defined with access rights (see
> -.BR landlock_add_rule (2)).
> +A Landlock rule describes an action on an object
> +which the process intends to perform.
>  A set of rules is aggregated in a ruleset,
>  which can then restrict the thread enforcing it,
>  and its future children.
> +.P
> +The two existing types of rules are:
> +.P

This will trigger a diagnostic due to being redundant before TP.

(Both P and TP are paragraphing macros, so you're theoretically creating
 an empty paragraph, which is just ignored by groff(1).)

> +.TP
> +.B Filesystem rules
> +For these rules, the object is a file hierarchy,
> +and the related filesystem actions are defined with
> +.IR "filesystem access rights" .
> +.TP
> +.B Network rules (since ABI v4)

Most of the pages use Roman for the parenthetical:

	$ grep -rn 'BR.*(since' | sort -R | head
	man7/ip.7:782:.BR IP_PKTINFO " (since Linux 2.2)"
	man2/set_mempolicy.2:109:.BR MPOL_F_STATIC_NODES " (since Linux 2.6.26)"
	man2/kexec_load.2:60:.BR KEXEC_PRESERVE_CONTEXT " (since Linux 2.6.27)"
	man2/perf_event_open.2:823:.BR PERF_SAMPLE_REGS_USER " (since Linux 3.7)"
	man2/perf_event_open.2:1522:.BR PERF_SAMPLE_BRANCH_COND " (since Linux 3.16)"
	man7/socket.7:998:.BR SO_TIMESTAMPNS " (since Linux 2.6.22)"
	man2/perf_event_open.2:1537:.BR PERF_SAMPLE_BRANCH_CALL_STACK " (since Linux 4.1)"
	man2/clone.2:1303:.BR EINVAL " (since Linux 3.9)"
	man2/eventfd.2:52:.BR EFD_NONBLOCK " (since Linux 2.6.27)"
	man2/perf_event_open.2:912:.BR PERF_SAMPLE_CGROUP " (since Linux 5.7)"

> +For these rules, the object is a TCP port,
> +and the related actions are defined with
> +.IR "network access rights" .
> +.BR landlock_add_rule (2)).

Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 3/3] landlock.7: Clarify IPC scoping documentation in line with kernel side

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 4460 bytes --]

Hi,

On Wed, Feb 26, 2025 at 10:29:12PM +0100, 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.
> 
> Link: https://lore.kernel.org/all/20250226211814.31420-4-gnoack@google.com/
> Signed-off-by: Günther Noack <gnoack@google.com>
> ---
>  man/man7/landlock.7 | 73 ++++++++++++++++++++++-----------------------
>  1 file changed, 35 insertions(+), 38 deletions(-)
> 
> diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
> index 30dbac73d..42cd7286f 100644
> --- a/man/man7/landlock.7
> +++ b/man/man7/landlock.7
> @@ -357,46 +357,43 @@ which means the tracee must be in a sub-domain of the tracer.
>  Similar to the implicit
>  .BR "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
> -.BR connect (2)
> -to a non-sandboxed process through abstract
> +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").
> +.P
> +The operations which can be scoped are:
> +.P

Redundant P before TP.

> +.TP
> +.B LANDLOCK_SCOPE_SIGNAL
> +This limits the sending of signals to target processes
> +which run within the same or a nested Landlock domain.
> +.TP
> +.B LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
> +This limits the set of abstract
>  .BR unix (7)
> -sockets,
> -we can specify such a restriction with
> -.BR 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
> -.BR LANDLOCK_SCOPE_SIGNAL .
> +sockets to which we can
> +.BR connect (2)
> +to socket addresses which were created
> +by a process in the same or a nested Landlock domain.
> +.IP
> +A
> +.BR sendto (2)
> +on a non-connected datagram socket is treated as if it were doing an implicit
> +.BR connect (2)
> +and will be blocked if the remote end does not stem
> +from the same or a nested Landlock domain.
> +.IP
> +A
> +.BR sendto (2)
> +on a socket which was previously connected will not be restricted.
> +This works for both datagram and stream sockets.
>  .P
> -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.
> -.P
> -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
> -.BR send (2)
> -data just like a stream socket.
> -However, in the same scenario,
> -a non-connected datagram socket cannot send data (with
> -.BR sendto (2))
> -outside its scope.
> -.P
> -A process with a scoped domain can inherit a socket

This text seems to have been added in patch 2/3.  Why is it being
removed in the same set?


Cheers,
Alex

> -created by a non-scoped process.
> -The process cannot connect to this socket since it has a scoped domain.
> -.P
> -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.
> +IPC scoping does not support exceptions via
> +.BR 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.
>  .\"
>  .SS Truncating files
>  The operations covered by
> -- 
> 2.48.1.711.g2feabab25a-goog
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 1/3] landlock.7: Update description of Landlock rules

[Günther Noack]

Hello!

On Fri, Feb 28, 2025 at 10:31:09PM +0100, Alejandro Colomar wrote:
> Hi,
> 
> On Wed, Feb 26, 2025 at 10:29:10PM +0100, Günther Noack wrote:
> > This brings it up to date with the wording in the kernel documentation.
> > 
> > Signed-off-by: Günther Noack <gnoack@google.com>
> 
> I'd like some more justification in the commit message.

Adding that. (linking to matching commit in kernel which introduced this)

> 
> > ---
> >  man/man7/landlock.7 | 20 ++++++++++++++++----
> >  1 file changed, 16 insertions(+), 4 deletions(-)
> > 
> > diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
> > index c6b7272ea..11f76b072 100644
> > --- a/man/man7/landlock.7
> > +++ b/man/man7/landlock.7
> > @@ -39,13 +39,25 @@ the running kernel must support Landlock and
> >  it must be enabled at boot time.
> >  .\"
> >  .SS Landlock rules
> > -A Landlock rule describes an action on an object.
> > -An object is currently a file hierarchy,
> > -and the related filesystem actions are defined with access rights (see
> > -.BR landlock_add_rule (2)).
> > +A Landlock rule describes an action on an object
> > +which the process intends to perform.
> >  A set of rules is aggregated in a ruleset,
> >  which can then restrict the thread enforcing it,
> >  and its future children.
> > +.P
> > +The two existing types of rules are:
> > +.P
> 
> This will trigger a diagnostic due to being redundant before TP.
> 
> (Both P and TP are paragraphing macros, so you're theoretically creating
>  an empty paragraph, which is just ignored by groff(1).)

Thanks, fixed.


> > +.TP
> > +.B Filesystem rules
> > +For these rules, the object is a file hierarchy,
> > +and the related filesystem actions are defined with
> > +.IR "filesystem access rights" .
> > +.TP
> > +.B Network rules (since ABI v4)
> 
> Most of the pages use Roman for the parenthetical:
> 
> 	$ grep -rn 'BR.*(since' | sort -R | head
> 	man7/ip.7:782:.BR IP_PKTINFO " (since Linux 2.2)"
> 	man2/set_mempolicy.2:109:.BR MPOL_F_STATIC_NODES " (since Linux 2.6.26)"
> 	man2/kexec_load.2:60:.BR KEXEC_PRESERVE_CONTEXT " (since Linux 2.6.27)"
> 	man2/perf_event_open.2:823:.BR PERF_SAMPLE_REGS_USER " (since Linux 3.7)"
> 	man2/perf_event_open.2:1522:.BR PERF_SAMPLE_BRANCH_COND " (since Linux 3.16)"
> 	man7/socket.7:998:.BR SO_TIMESTAMPNS " (since Linux 2.6.22)"
> 	man2/perf_event_open.2:1537:.BR PERF_SAMPLE_BRANCH_CALL_STACK " (since Linux 4.1)"
> 	man2/clone.2:1303:.BR EINVAL " (since Linux 3.9)"
> 	man2/eventfd.2:52:.BR EFD_NONBLOCK " (since Linux 2.6.27)"
> 	man2/perf_event_open.2:912:.BR PERF_SAMPLE_CGROUP " (since Linux 5.7)"
> 
> > +For these rules, the object is a TCP port,
> > +and the related actions are defined with
> > +.IR "network access rights" .
> > +.BR landlock_add_rule (2)).

Removing this stray last line as well, which was left over from an earlier
version of the text.

—Günther

Re: [PATCH v2 2/3] landlock.7: Move over documentation for ABI version 6

[Günther Noack]

Hello Alejandro!

For context, in this patch set, we have three commits:

  * 1/3 and 2/3 copy documentation from the kernel side unmodified.
  * 3/3 revises a section about Landlock's "scoped" restriction features.

I thought it would be easier to discuss with the "copy" and "rewrite" parts
separate, but actually, as you also noticed, 3/3 does rewrite large chunks of
the 2/3 commit along the way, and it is probably not worth correcting much of
that wording any more.

Would you prefer if I squashed commits 2/3 and 3/3 into one?

On Fri, Feb 28, 2025 at 10:23:47PM +0100, Alejandro Colomar wrote:
> On Wed, Feb 26, 2025 at 10:29:11PM +0100, Günther Noack wrote:
> > With this ABI version, Landlock can restrict outgoing interactions with
> > higher-privileged Landlock domains through Abstract Unix Domain sockets and
> > signals.
> > 
> > Signed-off-by: Günther Noack <gnoack@google.com>
> > ---
> >  man/man7/landlock.7 | 69 ++++++++++++++++++++++++++++++++++++++++++++-
> >  1 file changed, 68 insertions(+), 1 deletion(-)
> > 
> > diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
> > index 11f76b072..30dbac73d 100644
> > --- a/man/man7/landlock.7
> > +++ b/man/man7/landlock.7
> > @@ -248,7 +248,8 @@ This access right is available since the fifth version of the Landlock ABI.
> >  .SS Network flags
> >  These flags enable to restrict a sandboxed process
> >  to a set of network actions.
> > -This is supported since the Landlock ABI version 4.
> > +.P
> > +This is supported since Landlock ABI version 4.
> >  .P
> >  The following access rights apply to TCP port numbers:
> >  .TP
> > @@ -258,6 +259,24 @@ Bind a TCP socket to a local port.
> >  .B LANDLOCK_ACCESS_NET_CONNECT_TCP
> >  Connect an active TCP socket to a remote port.
> >  .\"
> > +.SS Scope flags
> > +These flags enable to isolate a sandboxed process from a set of IPC actions.
> 
> s/to isolate/isolating/
> 
> AFAIU, to be able to use an infinitive with enable/allow you need a
> direct object in the sentence.  If there's no direct object, you need a
> gerund.

Thanks, this is useful.  Changed it to infinitive for now.

FWIW, the same phrases exist on the kernel side as well, unfortunately.

> > +Setting a flag for a ruleset will isolate the Landlock domain
> > +to forbid connections to resources outside the domain.
> > +.P
> > +This is supported since Landlock ABI version 6.
> 
> I'm wondering if we should have this as a parenthetical next to the
> title, like we usually do with "(since Linux X.Y)".  Don't do it for
> now, but please consider it for when you have some time.  I'm not saying
> you should do it though, just that you consider it, and tell me if you
> agree or not.

I added it to my notes for further revisions,
I think this would indeed be more appropriate in the man pages.

Is it possible to set the paranthetical without bold as well,
even in a .SS subsection header?


> > +.P
> > +The following scopes exist:
> > +.TP
> > +.B LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
> > +Restrict a sandboxed process from connecting to an abstract UNIX socket
> > +created by a process outside the related Landlock domain
> > +(e.g., a parent domain or a non-sandboxed process).
> > +.TP
> > +.B LANDLOCK_SCOPE_SIGNAL
> > +Restrict a sandboxed process from sending a signal
> > +to another process outside the domain.
> > +.\"
> >  .SS Layers of file path access rights
> >  Each time a thread enforces a ruleset on itself,
> >  it updates its Landlock domain with a new layer of policy.
> > @@ -334,6 +353,51 @@ 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.
> >  .\"
> > +.SS IPC scoping
> > +Similar to the implicit
> > +.BR "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
> > +.BR connect (2)
> > +to a non-sandboxed process through abstract
> > +.BR unix (7)
> > +sockets,
> > +we can specify such a restriction with
> > +.BR 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
> > +.BR LANDLOCK_SCOPE_SIGNAL .
> > +.P
> > +A sandboxed process can connect to a non-sandboxed process
> > +when its domain is not scoped.
> 
> Does "its" refer to the sandboxed one or to the non-snadboxed one?

It refers to the sandboxed process.

This correction would be overwritten in the following commit.
I don't think it's worth fixing any more.

> > +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
> 
> Is this a typo?  s/signal/&s/

It is a typo, copied from kernel documentation.  Oops.

This correction is overwritten in the following commit.


> > to a non-scoped process,
> 
> Should we use plural here?

This correction is overwritten in the following commit.

> > +it can only send signals to processes in the same scope.
> > +.P
> > +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
> > +.BR send (2)
> > +data just like a stream socket.
> > +However, in the same scenario,
> > +a non-connected datagram socket cannot send data (with
> > +.BR sendto (2))
> > +outside its scope.
> > +.P
> > +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.
> > +.P
> > +IPC scoping does not support exceptions, so if a domain is scoped,
> 
> Please break after the first ',' too.

Done.


> > +no rules can be added to allow access to resources or processes
> 
> Please break after the second 'to'.

Done.


> > +outside of the scope.

Thanks for the review,
—Günther

Re: [PATCH v2 3/3] landlock.7: Clarify IPC scoping documentation in line with kernel side

[Günther Noack]

Hello Alejandro!

On Fri, Feb 28, 2025 at 10:37:17PM +0100, Alejandro Colomar wrote:
> On Wed, Feb 26, 2025 at 10:29:12PM +0100, 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.
> > 
> > Link: https://lore.kernel.org/all/20250226211814.31420-4-gnoack@google.com/
> > Signed-off-by: Günther Noack <gnoack@google.com>
> > ---
> >  man/man7/landlock.7 | 73 ++++++++++++++++++++++-----------------------
> >  1 file changed, 35 insertions(+), 38 deletions(-)
> > 
> > diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
> > index 30dbac73d..42cd7286f 100644
> > --- a/man/man7/landlock.7
> > +++ b/man/man7/landlock.7
> > @@ -357,46 +357,43 @@ which means the tracee must be in a sub-domain of the tracer.
> >  Similar to the implicit
> >  .BR "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
> > -.BR connect (2)
> > -to a non-sandboxed process through abstract
> > +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").
> > +.P
> > +The operations which can be scoped are:
> > +.P
> 
> Redundant P before TP.

Thanks, done.


> > [...]
> > 
> > -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.
> > -.P
> > -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
> > -.BR send (2)
> > -data just like a stream socket.
> > -However, in the same scenario,
> > -a non-connected datagram socket cannot send data (with
> > -.BR sendto (2))
> > -outside its scope.
> > -.P
> > -A process with a scoped domain can inherit a socket
> 
> This text seems to have been added in patch 2/3.  Why is it being
> removed in the same set?

I attempted to keep the "copy existing documentation" apart from the "rewrite"
part, but this was maybe a mistake given that this results in throwaway
corrections.  Should I rather squash them instead?

Thanks for the detailed review,
—Günther

Re: [PATCH v2 2/3] landlock.7: Move over documentation for ABI version 6

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1990 bytes --]

On Mon, Mar 03, 2025 at 05:24:45PM +0100, Günther Noack wrote:
> Hello Alejandro!

Hello Günther!

> For context, in this patch set, we have three commits:
> 
>   * 1/3 and 2/3 copy documentation from the kernel side unmodified.
>   * 3/3 revises a section about Landlock's "scoped" restriction features.
> 
> I thought it would be easier to discuss with the "copy" and "rewrite" parts
> separate, but actually, as you also noticed, 3/3 does rewrite large chunks of
> the 2/3 commit along the way, and it is probably not worth correcting much of
> that wording any more.
> 
> Would you prefer if I squashed commits 2/3 and 3/3 into one?

I think so.  :-)

> > > +Setting a flag for a ruleset will isolate the Landlock domain
> > > +to forbid connections to resources outside the domain.
> > > +.P
> > > +This is supported since Landlock ABI version 6.
> > 
> > I'm wondering if we should have this as a parenthetical next to the
> > title, like we usually do with "(since Linux X.Y)".  Don't do it for
> > now, but please consider it for when you have some time.  I'm not saying
> > you should do it though, just that you consider it, and tell me if you
> > agree or not.
> 
> I added it to my notes for further revisions,
> I think this would indeed be more appropriate in the man pages.
> 
> Is it possible to set the paranthetical without bold as well,
> even in a .SS subsection header?

Yes.  It requires you to use \f, but you can.  We avoid \f as much as
possible, but here it's not possible, and I think I've used it already
in a few places.  Here's an example of how to do it:

	alx@debian:~/tmp$ cat roman.man 
	.TH a s d f
	.SH foo
	.SS bar \f[R]baz\f[]
	asdf

\f[R] starts a roman (non-bold) text, and \f[] reverts to the previous
thing, which in this case is bold.


> > > +outside of the scope.
> 
> Thanks for the review,
> —Günther

:-)


Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]