[PATCH v2] docs: landlock: clarify TTY signal scoping

[PATCH v2] docs: landlock: clarify TTY signal scoping

[Christopher Lusk]

The LANDLOCK_SCOPE_SIGNAL documentation does not describe how TTY-driven
signals interact with signal scoping.  Holding a PTY master file descriptor
is a separate capability: its holder can cause the TTY layer to signal
processes running under that terminal, even across a Landlock domain
boundary.

Add a concise clarification to the userspace API guide and the UAPI header.
This records the capability boundary identified during review of the
TIOCSIG discussion without enumerating individual TTY signal paths.

The documentation text and changelog were drafted with assistance from
Codex (gpt-5.6-sol).

The userspace API documentation builds successfully with the kernel-pinned
Sphinx dependencies.  The patch introduces no new warnings; the existing
missing-graphviz and undefined-label warnings are unchanged.

Link: https://lore.kernel.org/r/aqqJAZfG9FC7PgMW@google.com
Suggested-by: Günther Noack <gnoack@google.com>
Assisted-by: Codex:gpt-5.6-sol
Signed-off-by: Christopher Lusk <clusk@northecho.dev>
---
 Documentation/userspace-api/landlock.rst | 3 +++
 include/uapi/linux/landlock.h            | 2 ++
 2 files changed, 5 insertions(+)

diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
index 84cb7bf6b3ed..33a514ebc615 100644
--- a/Documentation/userspace-api/landlock.rst
+++ b/Documentation/userspace-api/landlock.rst
@@ -430,6 +430,9 @@ The operations which can be scoped are:
     This limits the sending of signals to target processes which run within the
     same or a nested Landlock domain.
 
+    Holding a PTY master FD still grants the capability to issue signals through
+    that PTY to the processes running under that terminal.
+
 ``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
diff --git a/include/uapi/linux/landlock.h b/include/uapi/linux/landlock.h
index cceda3b3b961..6485af37dd25 100644
--- a/include/uapi/linux/landlock.h
+++ b/include/uapi/linux/landlock.h
@@ -501,6 +501,8 @@ struct landlock_net_port_attr {
  *   related Landlock domain (e.g., a parent domain or a non-sandboxed process).
  * - %LANDLOCK_SCOPE_SIGNAL: Restrict a sandboxed process from sending a signal
  *   to another process outside the domain.
+ *   Holding a PTY master FD still grants the capability to issue signals
+ *   through that PTY to the processes running under that terminal.
  */
 /* clang-format off */
 #define LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET		(1ULL << 0)
-- 
2.55.0

Re: [PATCH v2] docs: landlock: clarify TTY signal scoping

[Günther Noack]

On Wed, Sep 16, 2026 at 11:23:36AM -0400, Christopher Lusk wrote:
> The LANDLOCK_SCOPE_SIGNAL documentation does not describe how TTY-driven
> signals interact with signal scoping.  Holding a PTY master file descriptor
> is a separate capability: its holder can cause the TTY layer to signal
> processes running under that terminal, even across a Landlock domain
> boundary.
> 
> Add a concise clarification to the userspace API guide and the UAPI header.
> This records the capability boundary identified during review of the
> TIOCSIG discussion without enumerating individual TTY signal paths.
> 
> The documentation text and changelog were drafted with assistance from
> Codex (gpt-5.6-sol).
> 
> The userspace API documentation builds successfully with the kernel-pinned
> Sphinx dependencies.  The patch introduces no new warnings; the existing
> missing-graphviz and undefined-label warnings are unchanged.

Minor nit: Last two paragraphs of the commit message would have been
fine to drop for conciseness (the Assisted-by line already lists Codex
and the other paragraph talks about things that didn't change).

But really just very minor, and probably not worth changing unless we
unexpectedly need a V3.

> 
> Link: https://lore.kernel.org/r/aqqJAZfG9FC7PgMW@google.com
> Suggested-by: Günther Noack <gnoack@google.com>
> Assisted-by: Codex:gpt-5.6-sol
> Signed-off-by: Christopher Lusk <clusk@northecho.dev>
> ---
>  Documentation/userspace-api/landlock.rst | 3 +++
>  include/uapi/linux/landlock.h            | 2 ++
>  2 files changed, 5 insertions(+)
> 
> diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
> index 84cb7bf6b3ed..33a514ebc615 100644
> --- a/Documentation/userspace-api/landlock.rst
> +++ b/Documentation/userspace-api/landlock.rst
> @@ -430,6 +430,9 @@ The operations which can be scoped are:
>      This limits the sending of signals to target processes which run within the
>      same or a nested Landlock domain.
>  
> +    Holding a PTY master FD still grants the capability to issue signals through
> +    that PTY to the processes running under that terminal.
> +
>  ``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
> diff --git a/include/uapi/linux/landlock.h b/include/uapi/linux/landlock.h
> index cceda3b3b961..6485af37dd25 100644
> --- a/include/uapi/linux/landlock.h
> +++ b/include/uapi/linux/landlock.h
> @@ -501,6 +501,8 @@ struct landlock_net_port_attr {
>   *   related Landlock domain (e.g., a parent domain or a non-sandboxed process).
>   * - %LANDLOCK_SCOPE_SIGNAL: Restrict a sandboxed process from sending a signal
>   *   to another process outside the domain.
> + *   Holding a PTY master FD still grants the capability to issue signals
> + *   through that PTY to the processes running under that terminal.
>   */
>  /* clang-format off */
>  #define LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET		(1ULL << 0)
> -- 
> 2.55.0
> 

Reviewed-by: Günther Noack <gnoack@google.com>

Thank you very much for your contribution! :)

It ended up as a much smaller patch than we started out with, but the
real advancement lies in the understanding of the semantics and in the
double checking of these boundary conditions.  The LLM output was in
some cases a bit wordy ;-) but overall this was a good discovery and
useful discussion.

Thanks,
—Günther

Re: [PATCH v2] docs: landlock: clarify TTY signal scoping

[Mickaël Salaün]

This looks good, much simpler.  Could you please send the (new) test
with the v3 of this series?

On Wed, Sep 16, 2026 at 05:37:45PM +0200, Günther Noack wrote:
> On Wed, Sep 16, 2026 at 11:23:36AM -0400, Christopher Lusk wrote:
> > The LANDLOCK_SCOPE_SIGNAL documentation does not describe how TTY-driven
> > signals interact with signal scoping.  Holding a PTY master file descriptor
> > is a separate capability: its holder can cause the TTY layer to signal
> > processes running under that terminal, even across a Landlock domain
> > boundary.
> > 
> > Add a concise clarification to the userspace API guide and the UAPI header.
> > This records the capability boundary identified during review of the
> > TIOCSIG discussion without enumerating individual TTY signal paths.
> > 
> > The documentation text and changelog were drafted with assistance from
> > Codex (gpt-5.6-sol).
> > 
> > The userspace API documentation builds successfully with the kernel-pinned
> > Sphinx dependencies.  The patch introduces no new warnings; the existing
> > missing-graphviz and undefined-label warnings are unchanged.
> 
> Minor nit: Last two paragraphs of the commit message would have been
> fine to drop for conciseness (the Assisted-by line already lists Codex
> and the other paragraph talks about things that didn't change).
> 
> But really just very minor, and probably not worth changing unless we
> unexpectedly need a V3.
> 
> > 
> > Link: https://lore.kernel.org/r/aqqJAZfG9FC7PgMW@google.com
> > Suggested-by: Günther Noack <gnoack@google.com>
> > Assisted-by: Codex:gpt-5.6-sol
> > Signed-off-by: Christopher Lusk <clusk@northecho.dev>
> > ---
> >  Documentation/userspace-api/landlock.rst | 3 +++
> >  include/uapi/linux/landlock.h            | 2 ++
> >  2 files changed, 5 insertions(+)
> > 
> > diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
> > index 84cb7bf6b3ed..33a514ebc615 100644
> > --- a/Documentation/userspace-api/landlock.rst
> > +++ b/Documentation/userspace-api/landlock.rst
> > @@ -430,6 +430,9 @@ The operations which can be scoped are:
> >      This limits the sending of signals to target processes which run within the
> >      same or a nested Landlock domain.
> >  
> > +    Holding a PTY master FD still grants the capability to issue signals through
> > +    that PTY to the processes running under that terminal.

It would be more complete to quickly explain that a master TTY FD should
be considered at least as privileged as the processes using/trusting the
slave side.  See
https://lore.kernel.org/all/20260923.eehieph7UaX1@digikod.net/

So, this paragraph should really be short.

> > +
> >  ``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
> > diff --git a/include/uapi/linux/landlock.h b/include/uapi/linux/landlock.h
> > index cceda3b3b961..6485af37dd25 100644
> > --- a/include/uapi/linux/landlock.h
> > +++ b/include/uapi/linux/landlock.h
> > @@ -501,6 +501,8 @@ struct landlock_net_port_attr {
> >   *   related Landlock domain (e.g., a parent domain or a non-sandboxed process).
> >   * - %LANDLOCK_SCOPE_SIGNAL: Restrict a sandboxed process from sending a signal
> >   *   to another process outside the domain.
> > + *   Holding a PTY master FD still grants the capability to issue signals
> > + *   through that PTY to the processes running under that terminal.

What about rewording the LANDLOCK_SCOPE_SIGNAL description to say that
it is about signaling *arbitrary* processes (which is not the case with
the TTY master FD)?  This way we would not have to specifically re-talk
about the TTY case.

> >   */
> >  /* clang-format off */
> >  #define LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET		(1ULL << 0)
> > -- 
> > 2.55.0
> > 
> 
> Reviewed-by: Günther Noack <gnoack@google.com>
> 
> Thank you very much for your contribution! :)
> 
> It ended up as a much smaller patch than we started out with, but the
> real advancement lies in the understanding of the semantics and in the
> double checking of these boundary conditions.  The LLM output was in
> some cases a bit wordy ;-) but overall this was a good discovery and
> useful discussion.
> 
> Thanks,
> —Günther
> 

Re: [PATCH v2] docs: landlock: clarify TTY signal scoping

[Günther Noack]

On Wed, Sep 23, 2026 at 12:14:01PM +0200, Mickaël Salaün wrote:
> This looks good, much simpler.  Could you please send the (new) test
> with the v3 of this series?
> 
> On Wed, Sep 16, 2026 at 05:37:45PM +0200, Günther Noack wrote:
> > On Wed, Sep 16, 2026 at 11:23:36AM -0400, Christopher Lusk wrote:
> > > The LANDLOCK_SCOPE_SIGNAL documentation does not describe how TTY-driven
> > > signals interact with signal scoping.  Holding a PTY master file descriptor
> > > is a separate capability: its holder can cause the TTY layer to signal
> > > processes running under that terminal, even across a Landlock domain
> > > boundary.
> > > 
> > > Add a concise clarification to the userspace API guide and the UAPI header.
> > > This records the capability boundary identified during review of the
> > > TIOCSIG discussion without enumerating individual TTY signal paths.
> > > 
> > > The documentation text and changelog were drafted with assistance from
> > > Codex (gpt-5.6-sol).
> > > 
> > > The userspace API documentation builds successfully with the kernel-pinned
> > > Sphinx dependencies.  The patch introduces no new warnings; the existing
> > > missing-graphviz and undefined-label warnings are unchanged.
> > 
> > Minor nit: Last two paragraphs of the commit message would have been
> > fine to drop for conciseness (the Assisted-by line already lists Codex
> > and the other paragraph talks about things that didn't change).
> > 
> > But really just very minor, and probably not worth changing unless we
> > unexpectedly need a V3.
> > 
> > > 
> > > Link: https://lore.kernel.org/r/aqqJAZfG9FC7PgMW@google.com
> > > Suggested-by: Günther Noack <gnoack@google.com>
> > > Assisted-by: Codex:gpt-5.6-sol
> > > Signed-off-by: Christopher Lusk <clusk@northecho.dev>
> > > ---
> > >  Documentation/userspace-api/landlock.rst | 3 +++
> > >  include/uapi/linux/landlock.h            | 2 ++
> > >  2 files changed, 5 insertions(+)
> > > 
> > > diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
> > > index 84cb7bf6b3ed..33a514ebc615 100644
> > > --- a/Documentation/userspace-api/landlock.rst
> > > +++ b/Documentation/userspace-api/landlock.rst
> > > @@ -430,6 +430,9 @@ The operations which can be scoped are:
> > >      This limits the sending of signals to target processes which run within the
> > >      same or a nested Landlock domain.
> > >  
> > > +    Holding a PTY master FD still grants the capability to issue signals through
> > > +    that PTY to the processes running under that terminal.
> 
> It would be more complete to quickly explain that a master TTY FD should
> be considered at least as privileged as the processes using/trusting the
> slave side.  See
> https://lore.kernel.org/all/20260923.eehieph7UaX1@digikod.net/
> 
> So, this paragraph should really be short.
> 
> > > +
> > >  ``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
> > > diff --git a/include/uapi/linux/landlock.h b/include/uapi/linux/landlock.h
> > > index cceda3b3b961..6485af37dd25 100644
> > > --- a/include/uapi/linux/landlock.h
> > > +++ b/include/uapi/linux/landlock.h
> > > @@ -501,6 +501,8 @@ struct landlock_net_port_attr {
> > >   *   related Landlock domain (e.g., a parent domain or a non-sandboxed process).
> > >   * - %LANDLOCK_SCOPE_SIGNAL: Restrict a sandboxed process from sending a signal
> > >   *   to another process outside the domain.
> > > + *   Holding a PTY master FD still grants the capability to issue signals
> > > + *   through that PTY to the processes running under that terminal.
> 
> What about rewording the LANDLOCK_SCOPE_SIGNAL description to say that
> it is about signaling *arbitrary* processes (which is not the case with
> the TTY master FD)?  This way we would not have to specifically re-talk
> about the TTY case.

In "Restrict a sandboxed process from sending a signal to another process
outside the domain", I think it is already implicit that this applies
to all (arbitrary) processes.

How about this:

   Restrict a sandboxed process from sending a signal to another
   process outside the domain, unless it is done through a controlled
   indirection mechanism (e.g. a PTY master FD).

I think it's worth mentioning the PTY explicitly here.  This is the
interface description for what these LANDLOCK_* constants mean, and
for documentation clarity, it would be good to be specific about the
cases that we know.

—Günther