[PATCH v2 2/2] man/man?/landlock*.?: Document UDP support

[Matthieu Buffet <matthieu@buffet.re>]

Landlock support for UDP-specific policy was merged in 7.2 in
linux.git 9a8ed15ce224 ("landlock: Add UDP bind() access control")
and
linux.git e61247a2e694 ("landlock: Add UDP send+connect access control")

Add documentation for new access rights taken from the UAPI header, plus:
- clarify the description of the most non-trivial behavior (auto-bind
  denials when emitting, which can occur even if CONNECT_SEND_UDP is not
  handled)
- improve AF_UNSPEC behavior description in both connect() and IPv6-send
  cases
- minor wording fixes to be backported in the UAPI header

Link: <https://github.com/landlock-lsm/linux/issues/66>
Signed-off-by: Matthieu Buffet <matthieu@buffet.re>
---
 man/man2/landlock_add_rule.2 | 14 +++++--
 man/man7/landlock.7          | 74 +++++++++++++++++++++++++++++++++++-
 2 files changed, 82 insertions(+), 6 deletions(-)

diff --git a/man/man2/landlock_add_rule.2 b/man/man2/landlock_add_rule.2
index 253498bfa2cf..337ff4150f2c 100644
--- a/man/man2/landlock_add_rule.2
+++ b/man/man2/landlock_add_rule.2
@@ -82,7 +82,7 @@ just a file.
 .TP
 .BR LANDLOCK_RULE_NET_PORT "  (since Landlock ABI version 4)"
 For these rules,
-the object is a TCP port,
+the object is a TCP or UDP port,
 and the related actions are defined with
 .IR "network access rights" .
 .IP
@@ -120,8 +120,13 @@ with
 A Landlock rule with port 0
 and the
 .B LANDLOCK_ACCESS_NET_BIND_TCP
-right means that requesting to bind on port 0 is allowed
-and it will automatically translate to binding on the related port range.
+or
+.B LANDLOCK_ACCESS_NET_BIND_UDP
+right means that requesting to bind on port 0
+(explicitly, or implicitly
+for instance by sending a datagram on an unbound UDP socket)
+is allowed
+and it will automatically translate to binding on a kernel-assigned ephemeral port.
 .P
 .I flags
 is a bit mask of the following optional flags:
@@ -181,7 +186,8 @@ can fail for the following reasons:
 .I rule_type
 is
 .BR LANDLOCK_RULE_NET_PORT ,
-but TCP is not supported by the running kernel.
+but the kernel was built without
+.BR CONFIG_INET .
 .TP
 .B EBADF
 .I ruleset_fd
diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
index ad63826da84f..296c4d74a22f 100644
--- a/man/man7/landlock.7
+++ b/man/man7/landlock.7
@@ -53,8 +53,8 @@ For these rules, the object is a file hierarchy,
 and the related filesystem actions are defined with
 .IR "filesystem access rights" .
 .TP
-.BR "Network rules" " (since ABI v4)"
-For these rules, the object is a TCP port,
+.BR "Network rules" " (since ABI v4 for TCP, v10 for UDP)"
+For these rules, the object is a TCP or UDP port,
 and the related actions are defined with
 .IR "network access rights" .
 .\"
@@ -276,6 +276,74 @@ Bind a TCP socket to a local port.
 .TP
 .BR LANDLOCK_ACCESS_NET_CONNECT_TCP "  (since Landlock ABI version 4)"
 Connect an active TCP socket to a remote port.
+.P
+And similarly for UDP port numbers:
+.TP
+.BR LANDLOCK_ACCESS_NET_BIND_UDP "  (since Landlock ABI version 10)"
+Bind UDP sockets to the given local port.
+.TP
+.BR LANDLOCK_ACCESS_NET_CONNECT_SEND_UDP "  (since Landlock ABI version 10)"
+Set the remote port of UDP sockets to the given port,
+or send datagrams to the given remote port
+ignoring any destination pre-set on a socket.
+.P
+Note on auto-binding:
+Setting a remote address
+or sending a first datagram
+auto-binds
+UDP sockets
+to an ephemeral local source port
+if not already bound.
+To allow this if
+.B LANDLOCK_ACCESS_NET_BIND_UDP
+is handled
+(even if
+.B LANDLOCK_ACCESS_NET_CONNECT_SEND_UDP
+is not),
+either:
+.IP \[bu] 3
+use a socket already bound to a port
+before the ruleset started being enforced;
+.IP \[bu] 3
+grant
+.B LANDLOCK_ACCESS_NET_BIND_UDP
+on port 0, meaning
+\[lq]any port in the ephemeral port range\[rq];
+.IP \[bu] 3
+grant
+.B LANDLOCK_ACCESS_NET_BIND_UDP
+on a specific port,
+and call
+.BR bind (2)
+on that port before trying to
+.BR connect (2)
+or send datagrams.
+.P
+Note on
+.BR AF_UNSPEC :
+Calling
+.BR connect (2)
+on a TCP or UDP socket
+with an address of the
+.B AF_UNSPEC
+family
+can only dissolve existing associations,
+and as such is always allowed.
+On IPv6 UDP sockets, if
+.B LANDLOCK_ACCESS_NET_CONNECT_SEND_UDP
+is handled,
+sending datagrams to
+.B AF_UNSPEC
+addresses is not supported
+and will always result in a denial,
+as if the policy rejected it:
+use a
+.I NULL
+address instead to get the same semantics
+inside and outside a Landlock domain.
+Other uses of the
+.B AF_UNSPEC
+family have unchanged semantics.
 .\"
 .SS Scope flags
 These flags enable isolating a sandboxed process from a set of IPC actions.
@@ -531,6 +599,8 @@ _	_	_
 9	7.1	LANDLOCK_ACCESS_FS_RESOLVE_UNIX
 _	_	_
 10	7.2	LANDLOCK_ADD_RULE_QUIET
+\^	\^	LANDLOCK_ACCESS_NET_BIND_UDP
+\^	\^	LANDLOCK_ACCESS_NET_CONNECT_SEND_UDP
 .TE
 .P
 Users should use the Landlock ABI version rather than the kernel version
-- 
2.47.3