Document LANDLOCK_ACCESS_FS_RESOLVE_UNIX

* Use cardinal numbers for referring to Landlock ABI versions, where possible.

* Adopt the format already used in landlock_restrict_self(2), where the ABI versions are described next to the flag names in their tagged paragraphs. For example:

.TP
.BR FLAG " (since Landlock ABI version X)"

Signed-off-by Günther Noack <[email protected]>

---
 man/man7/landlock.7 | 26 ++++++++------------------
 1 file changed, 8 insertions(+), 18 deletions(-)

man/man7/landlock.7 +8 -18

index 0e3a11489af2..60915bdd9728 100644
@@ -89,7 +89,7 @@ these system calls truncate existing files when overwriting them
 .B LANDLOCK_ACCESS_FS_READ_FILE
 Open a file with read access.
 .TP
-.B LANDLOCK_ACCESS_FS_TRUNCATE
+.BR LANDLOCK_ACCESS_FS_TRUNCATE "  (since Landlock ABI version 3)"
 Truncate a file with
 .BR truncate (2),
 .BR ftruncate (2),

@@ -98,10 +98,8 @@ or
 .BR open (2)
 with
 .BR O_TRUNC .
-.IP
-This access right is available since the third version of the Landlock ABI.
 .TP
-.B LANDLOCK_ACCESS_FS_IOCTL_DEV
+.BR LANDLOCK_ACCESS_FS_IOCTL_DEV "  (since Landlock ABI version 5)"
 Invoke
 .BR ioctl (2)
 commands on an opened character or block device.

@@ -137,8 +135,6 @@ whose implementations are safe and return the right error codes
 .BR FICLONERANGE ,
 .BR FIDEDUPERANGE )
 .RE
-.IP
-This access right is available since the fifth version of the Landlock ABI.
 .P
 Whether an opened file can be truncated with
 .BR ftruncate (2)

@@ -191,19 +187,17 @@ Create (or rename or link) a block device.
 .B LANDLOCK_ACCESS_FS_MAKE_SYM
 Create (or rename or link) a symbolic link.
 .TP
-.B LANDLOCK_ACCESS_FS_REFER
+.BR LANDLOCK_ACCESS_FS_REFER "  (since Landlock ABI version 2)"
 Link or rename a file from or to a different directory
 (i.e., reparent a file hierarchy).
 .IP
-This access right is available since the second version of the Landlock ABI.
-.IP
 This is the only access right which is denied by default by any ruleset,
 even if the right is not specified as handled at ruleset creation time.
 The only way to make a ruleset grant this right
 is to explicitly allow it for a specific directory
 by adding a matching rule to the ruleset.
 .IP
-In particular, when using the first Landlock ABI version,
+In particular, when using Landlock ABI version 1,
 Landlock will always deny attempts to reparent files
 between different directories.
 .IP

@@ -245,14 +239,12 @@ error code takes precedence over
 These flags enable to restrict a sandboxed process
 to a set of network actions.
 .P
-This is supported since Landlock ABI version 4.
-.P
 The following access rights apply to TCP port numbers:
 .TP
-.B LANDLOCK_ACCESS_NET_BIND_TCP
+.BR LANDLOCK_ACCESS_NET_BIND_TCP "  (since Landlock ABI version 4)"
 Bind a TCP socket to a local port.
 .TP
-.B LANDLOCK_ACCESS_NET_CONNECT_TCP
+.BR LANDLOCK_ACCESS_NET_CONNECT_TCP "  (since Landlock ABI version 4)"
 Connect an active TCP socket to a remote port.
 .\"
 .SS Scope flags

@@ -260,16 +252,14 @@ These flags enable isolating a sandboxed process from a set of IPC actions.
 Setting a flag for a ruleset will isolate the Landlock domain
 to forbid connections to resources outside the domain.
 .P
-This is supported since Landlock ABI version 6.
-.P
 The following scopes exist:
 .TP
-.B LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
+.BR LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET "  (since Landlock ABI version 6)"
 Restrict a sandboxed process from connecting to an abstract UNIX socket
 created by a process outside the related Landlock domain
 (e.g., a parent domain or a non-sandboxed process).
 .TP
-.B LANDLOCK_SCOPE_SIGNAL
+.BR LANDLOCK_SCOPE_SIGNAL "  (since Landlock ABI version 6)"
 Restrict a sandboxed process from sending a signal
 to another process outside the domain.
 .\"

Signature · 1 line

2.54.0

Document the new LANDLOCK_ACCESS_FS_RESOLVE_UNIX filesystem access right, which controls lookups of pathname UNIX domain sockets. Restricts both connect(2) and sendmsg(2) with an explicit recipient address to UNIX sockets created outside the Landlock domain (same semantics as LANDLOCK_SCOPE_* flags). Denied attempts return EACCES.

Available since Linux 7.1 (Landlock ABI version 9).

Signed-off-by Günther Noack <[email protected]>

---
 man/man7/landlock.7 | 54 ++++++++++++++++++++++++++++++++++++---------
 1 file changed, 44 insertions(+), 10 deletions(-)

man/man7/landlock.7 +44 -10

index 60915bdd9728..55cd002d5789 100644
@@ -135,6 +135,36 @@ whose implementations are safe and return the right error codes
 .BR FICLONERANGE ,
 .BR FIDEDUPERANGE )
 .RE
+.TP
+.BR LANDLOCK_ACCESS_FS_RESOLVE_UNIX "  (since Landlock ABI version 9)"
+Look up pathname UNIX
+domain sockets
+.RB ( unix (7)).
+On UNIX domain sockets,
+this restricts both calls to
+.BR connect (2)
+and
+.BR sendmsg (2)
+with an explicit recipient address.
+.IP
+This access right applies only to connections to UNIX server sockets
+which were created outside the newly created Landlock domain
+(e.g., from within a parent domain or from an unrestricted process).
+Newly created UNIX servers
+within the same Landlock domain
+continue to be accessible.
+In this regard,
+.B LANDLOCK_ACCESS_FS_RESOLVE_UNIX
+has the same semantics as the
+.BI LANDLOCK_SCOPE_ *
+flags.
+.IP
+If a resolution attempt is denied,
+the operation returns an
+.B EACCES
+error,
+in line with other filesystem access rights
+(but different to denials for abstract UNIX domain sockets).
 .P
 Whether an opened file can be truncated with
 .BR ftruncate (2)

@@ -468,6 +498,8 @@ _	_	_
 \^	\^	LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF
 _	_	_
 8	7.0	LANDLOCK_RESTRICT_SELF_TSYNC
+_	_	_
+9	7.1	LANDLOCK_ACCESS_FS_RESOLVE_UNIX
 .TE
 .P
 Users should use the Landlock ABI version rather than the kernel version

@@ -553,7 +585,8 @@ attr.handled_access_fs =
         LANDLOCK_ACCESS_FS_MAKE_SYM |
         LANDLOCK_ACCESS_FS_REFER |
         LANDLOCK_ACCESS_FS_TRUNCATE |
-        LANDLOCK_ACCESS_FS_IOCTL_DEV;
+        LANDLOCK_ACCESS_FS_IOCTL_DEV |
+        LANDLOCK_ACCESS_FS_RESOLVE_UNIX;
 .EE
 .in
 .P

@@ -568,14 +601,15 @@ and only use the available subset of access rights:
  * numbers hardcoded to keep the example short.
  */
 __u64 landlock_fs_access_rights[] = {
-    (LANDLOCK_ACCESS_FS_MAKE_SYM  << 1) \- 1,  /* v1                  */
-    (LANDLOCK_ACCESS_FS_REFER     << 1) \- 1,  /* v2: add "refer"     */
-    (LANDLOCK_ACCESS_FS_TRUNCATE  << 1) \- 1,  /* v3: add "truncate"  */
-    (LANDLOCK_ACCESS_FS_TRUNCATE  << 1) \- 1,  /* v4: TCP support     */
-    (LANDLOCK_ACCESS_FS_IOCTL_DEV << 1) \- 1,  /* v5: add "ioctl_dev" */
-    (LANDLOCK_ACCESS_FS_IOCTL_DEV << 1) \- 1,  /* v6: same            */
-    (LANDLOCK_ACCESS_FS_IOCTL_DEV << 1) \- 1,  /* v7: same            */
-    (LANDLOCK_ACCESS_FS_IOCTL_DEV << 1) \- 1,  /* v8: same            */
+    (LANDLOCK_ACCESS_FS_MAKE_SYM     << 1) \- 1,  // v1
+    (LANDLOCK_ACCESS_FS_REFER        << 1) \- 1,  // v2: add "refer"
+    (LANDLOCK_ACCESS_FS_TRUNCATE     << 1) \- 1,  // v3: add "truncate"
+    (LANDLOCK_ACCESS_FS_TRUNCATE     << 1) \- 1,  // v4: TCP support
+    (LANDLOCK_ACCESS_FS_IOCTL_DEV    << 1) \- 1,  // v5: add "ioctl_dev"
+    (LANDLOCK_ACCESS_FS_IOCTL_DEV    << 1) \- 1,  // v6: same
+    (LANDLOCK_ACCESS_FS_IOCTL_DEV    << 1) \- 1,  // v7: same
+    (LANDLOCK_ACCESS_FS_IOCTL_DEV    << 1) \- 1,  // v8: same
+    (LANDLOCK_ACCESS_FS_RESOLVE_UNIX << 1) \- 1,  // v9: add "resolve_unix"
 };
 \&
 int abi = landlock_create_ruleset(NULL, 0,

@@ -588,7 +622,7 @@ if (abi == \-1) {
     perror("Unable to use Landlock");
     return;  /* Graceful fallback: Do nothing.  */
 }
-abi = MIN(abi, 8);
+abi = MIN(abi, 9);
 \&
 /* Only use the available rights in the ruleset.  */
 attr.handled_access_fs &= landlock_fs_access_rights[abi \- 1];

Signature · 1 line

2.54.0

Quoted 6 lines · Günther Noack

Document the new LANDLOCK_ACCESS_FS_RESOLVE_UNIX filesystem access right, which controls lookups of pathname UNIX domain sockets. Restricts both connect(2) and sendmsg(2) with an explicit recipient address to UNIX sockets created outside the Landlock domain (same semantics as LANDLOCK_SCOPE_* flags). Denied attempts return EACCES.

Quoted 3 lines

Available since Linux 7.1 (Landlock ABI version 9).

Signed-off-by Günther Noack <[email protected]>

Reviewed-by Alejandro Colomar <[email protected]>

Hello Alejandro!

Quoted 11 lines · Alejandro Colomar

Quoted 9 lines · Günther Noack

Document the new LANDLOCK_ACCESS_FS_RESOLVE_UNIX filesystem access right, which controls lookups of pathname UNIX domain sockets. Restricts both connect(2) and sendmsg(2) with an explicit recipient address to UNIX sockets created outside the Landlock domain (same semantics as LANDLOCK_SCOPE_* flags). Denied attempts return EACCES.

Available since Linux 7.1 (Landlock ABI version 9).

Signed-off-by Günther Noack <[email protected]>

Quoted 1 line

Reviewed-by Alejandro Colomar <[email protected]>

Friendly ping on this patch.

This feature had not landed in stable yet at the time we reviewed it, but now it is in Linux 7.1 and would be ready to pick up for the next man-pages release :)

Thanks,
—Günther