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

["Günther Noack" <gnoack@google.com>]

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