[PATCH] docs: landlock: clarify TTY signal scoping

[Christopher Lusk]

LANDLOCK_SCOPE_SIGNAL mediates signal delivery when a sandboxed process
selects the recipient, including SIGIO through fowner.  It does not mediate
signals directed by the TTY layer to processes attached to a terminal in
response to terminal activity.  This distinction was clarified while
discussing TIOCSIG handling because the PTY master acts as a capability and
the signal recipients have attached to the terminal.

Document the TTY-driven signal paths which are outside the scope and advise
controlling access to the terminal or PTY master instead.  This records the
outcome of the RFC discussion and avoids implying that
LANDLOCK_SCOPE_SIGNAL covers every signal-delivery mechanism.

The documentation text and changelog were drafted with assistance from
Claude (claude-opus-4-8) and Codex (gpt-5.6-sol).

The userspace API documentation builds successfully with the kernel-pinned
Sphinx dependencies.  The remaining warnings are unrelated to the changed
Landlock text.

Link: https://lore.kernel.org/r/20260914.b8a029f9abb8@gnoack.org
Suggested-by: Günther Noack <gnoack at google.com>
Assisted-by: Claude:claude-opus-4-8
Assisted-by: Codex:gpt-5.6-sol
Signed-off-by: Christopher Lusk <clusk at northecho.dev>
---
 Documentation/userspace-api/landlock.rst | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
index 84cb7bf6b3ed..64418b09840d 100644
--- a/Documentation/userspace-api/landlock.rst
+++ b/Documentation/userspace-api/landlock.rst
@@ -430,6 +430,21 @@ 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.
 
+    This scope does not cover signals delivered by the TTY layer.  A process
+    holding a PTY master, or otherwise driving a terminal, can cause the TTY
+    driver to deliver signals to processes attached to that terminal across
+    Landlock domain boundaries.  This includes ``SIGINT``, ``SIGQUIT``, and
+    ``SIGTSTP`` via the ``TIOCSIG`` :manpage:`ioctl(2)` command or the
+    corresponding control characters.  The TTY layer may also deliver
+    ``SIGWINCH``, ``SIGHUP``, and ``SIGCONT``.
+
+    These signals originate from the TTY driver in response to terminal
+    activity rather than from a :manpage:`kill(2)`-style request.  They can
+    only reach processes attached to the terminal.  To restrict this
+    interaction, control possession of the PTY master and terminal attachment.
+    For example, do not pass a PTY master to a sandboxed process if its slave
+    has processes from outside the Landlock domain attached to it.
+
 ``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
-- 
2.55.0