| Message ID | 20250124154445.162841-2-gnoack@google.com (mailing list archive) |
|---|---|
| State | Handled Elsewhere |
| Headers | show |
| Series | [1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation | expand |
On 1/24/2025 10:44 AM, 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@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 | 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. > - > -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 The "to to" takes a couple of reads to parse. Would "...this limits the set of abstract :manpage:`unix(7)` sockets to which we can :manpage:`connect(2)` to socket addresses which were..." perhaps be easier to read? > + 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. Maybe overly pedantic, but I wonder if something like "will not be restricted" instead of "will work" would be clearer? "Work" just has a lot of meanings. I don't think it's actually ambiguous as written, I just think that a more precise word could avoid the potential for confusion. -Daniel > + 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 > ----------------
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@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 | 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
Hi Guenther! On Fri, Jan 24, 2025 at 04:59:29PM +0100, G??nther Noack wrote: > 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.) Sorry for not replying before. I had fever last week. :) > On Fri, Jan 24, 2025 at 03:44:45PM +0000, G??nther Noack wrote: > > -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, Do we need to say when set? I'd say that's redundant (of course if you don't set a flag, its effects don't apply). > > 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 I think *if* would be more appropriate than *when* here. > > + not stem from the same or a nested Landlock domain. This could be read such that send(2) is replaced by connect(2) on a non-connected datagram socket. But you want to say that a connect(2) is implicitly executed before the actual send(2) (which is still executed, if connect(2) succeeds). How about this wording? If send(2) is used on a non-connected datagram socket, an implicit connect(2) is executed first, and will be blocked when the remote end does not .... Have a lovely day! Alex > > + 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
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. - -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 ----------------
* 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@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 | 53 ++++++++++++------------ 1 file changed, 26 insertions(+), 27 deletions(-)