[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 at google.com>
> > Assisted-by: Codex:gpt-5.6-sol
> > Signed-off-by: Christopher Lusk <clusk at 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 at 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
>