[PATCH v2 0/5] landlock*: Bring documentation up to date

[PATCH v2 0/5] landlock*: Bring documentation up to date

[Günther Noack]

This cleans up a variety of wording issues and small mistakes,
and brings the man page documentation up to date with Landlock
ABI v4 (networking support) and v5 (IOCTL support).

V2: Addressed the small issues brought up in review
    by Mickaël Salaün and Alejandro Colomar:
 * various small wording and git-merging issues
 * small commit message formatting issues

Günther Noack (5):
  landlock.7, landlock_*.2: wfix
  landlock_create_ruleset.2: Update docs for landlock_ruleset_attr
  landlock_add_rule.2: Document missing reason for EINVAL
  landlock.7, landlock_*.2: Document Landlock ABI version 4
  landlock.7: Document Landlock ABI version 5 (IOCTL)

 man/man2/landlock_add_rule.2       | 93 ++++++++++++++++++++++++++----
 man/man2/landlock_create_ruleset.2 | 52 ++++++++++++++---
 man/man2/landlock_restrict_self.2  | 11 ++--
 man/man7/landlock.7                | 80 ++++++++++++++++++++++---
 4 files changed, 205 insertions(+), 31 deletions(-)

-- 
2.45.2.1089.g2a221341d9-goog

[PATCH v2 1/5] landlock.7, landlock_*.2: wfix

[Günther Noack]

* Various wording fixes
* List the same error code multiple times,
  if it can happen for multiple reasons.

Reviewed-by: Mickaël Salaün <mic@digikod.net>
Signed-off-by: Günther Noack <gnoack@google.com>
---
 man/man2/landlock_add_rule.2       |  9 +++++++--
 man/man2/landlock_create_ruleset.2 |  6 +++---
 man/man2/landlock_restrict_self.2  | 11 ++++++-----
 man/man7/landlock.7                |  6 ++++--
 4 files changed, 20 insertions(+), 12 deletions(-)

diff --git a/man/man2/landlock_add_rule.2 b/man/man2/landlock_add_rule.2
index d4ae8f2f6..fa0b1f109 100644
--- a/man/man2/landlock_add_rule.2
+++ b/man/man2/landlock_add_rule.2
@@ -60,7 +60,9 @@ struct landlock_path_beneath_attr {
 .in
 .IP
 .I allowed_access
-contains a bitmask of allowed filesystem actions for this file hierarchy
+contains a bitmask of allowed filesystem actions,
+which can be applied on the given
+.I parent_fd
 (see
 .B Filesystem actions
 in
@@ -92,7 +94,10 @@ Landlock is supported by the kernel but disabled at boot time.
 .TP
 .B EINVAL
 .I flags
-is not 0, or the rule accesses are inconsistent (i.e.,
+is not 0.
+.TP
+.B EINVAL
+The rule accesses are inconsistent (i.e.,
 .I rule_attr\->allowed_access
 is not a subset of the ruleset handled accesses).
 .TP
diff --git a/man/man2/landlock_create_ruleset.2 b/man/man2/landlock_create_ruleset.2
index 618d54f37..871b91dcb 100644
--- a/man/man2/landlock_create_ruleset.2
+++ b/man/man2/landlock_create_ruleset.2
@@ -23,7 +23,8 @@ Standard C library
 A Landlock ruleset identifies a set of rules (i.e., actions on objects).
 This
 .BR landlock_create_ruleset ()
-system call enables creating a new file descriptor identifying a ruleset.
+system call creates a new file descriptor
+which identifies a ruleset.
 This file descriptor can then be used by
 .BR landlock_add_rule (2)
 and
@@ -45,8 +46,7 @@ struct landlock_ruleset_attr {
 .in
 .IP
 .I handled_access_fs
-is a bitmask of actions that is handled by this ruleset and
-should then be forbidden if no rule explicitly allows them
+is a bitmask of handled filesystem actions
 (see
 .B Filesystem actions
 in
diff --git a/man/man2/landlock_restrict_self.2 b/man/man2/landlock_restrict_self.2
index d4e5e753c..f044c6b31 100644
--- a/man/man2/landlock_restrict_self.2
+++ b/man/man2/landlock_restrict_self.2
@@ -20,7 +20,7 @@ Standard C library
 .SH DESCRIPTION
 Once a Landlock ruleset is populated with the desired rules, the
 .BR landlock_restrict_self ()
-system call enables enforcing this ruleset on the calling thread.
+system call enforces this ruleset on the calling thread.
 See
 .BR landlock (7)
 for a global overview.
@@ -38,10 +38,11 @@ with multiple independent rulesets coming from different sources
 built-in application policy).
 However, most applications should only need one call to
 .BR landlock_restrict_self ()
-and they should avoid arbitrary numbers of such calls because of the
-composed rulesets limit.
-Instead, developers are encouraged to build a tailored ruleset thanks to
-multiple calls to
+and they should avoid arbitrary numbers of such calls
+because of the composed rulesets limit.
+Instead,
+developers are encouraged to build a single tailored ruleset
+with multiple calls to
 .BR landlock_add_rule (2).
 .P
 In order to enforce a ruleset, either the caller must have the
diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
index 4a98f6549..652054f15 100644
--- a/man/man7/landlock.7
+++ b/man/man7/landlock.7
@@ -58,7 +58,7 @@ and
 .BR landlock_create_ruleset (2)
 for more context.
 .P
-A file can only receive these access rights:
+The following access rights apply only to files:
 .TP
 .B LANDLOCK_ACCESS_FS_EXECUTE
 Execute a file.
@@ -87,6 +87,9 @@ or
 .BR open (2)
 with
 .BR O_TRUNC .
+.IP
+This access right is available since the third version of the Landlock ABI.
+.IP
 Whether an opened file can be truncated with
 .BR ftruncate (2)
 is determined during
@@ -97,7 +100,6 @@ using
 .B LANDLOCK_ACCESS_FS_READ_FILE
 and
 .BR LANDLOCK_ACCESS_FS_WRITE_FILE .
-This access right is available since the third version of the Landlock ABI.
 .P
 A directory can receive access rights related to files or directories.
 The following access right is applied to the directory itself,
-- 
2.45.2.1089.g2a221341d9-goog

[PATCH v2 2/5] landlock_create_ruleset.2: Update docs for landlock_ruleset_attr

[Günther Noack]

This updates the documentation for struct landlock_ruleset_attr
in line with the changed kernel documentation (see link below).

Cc: Alejandro Colomar <alx@kernel.org>
Link: https://lore.kernel.org/all/20240711165456.2148590-2-gnoack@google.com/
Reviewed-by: Mickaël Salaün <mic@digikod.net>
Signed-off-by: Günther Noack <gnoack@google.com>
---
 man/man2/landlock_create_ruleset.2 | 34 ++++++++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

diff --git a/man/man2/landlock_create_ruleset.2 b/man/man2/landlock_create_ruleset.2
index 871b91dcb..105e9b062 100644
--- a/man/man2/landlock_create_ruleset.2
+++ b/man/man2/landlock_create_ruleset.2
@@ -51,8 +51,38 @@ is a bitmask of handled filesystem actions
 .B Filesystem actions
 in
 .BR landlock (7)).
-This enables simply restricting ambient rights
-(e.g., global filesystem access) and is needed for compatibility reasons.
+.IP
+This structure defines a set of
+.IR "handled access rights" ,
+a set of actions on different object types,
+which should be denied by default
+when the ruleset is enacted.
+Vice versa,
+access rights that are not specifically listed here
+are not going to be denied by this ruleset when it is enacted.
+.IP
+For historical reasons, the
+.B LANDLOCK_ACCESS_FS_REFER
+right is always denied by default,
+even when its bit is not set in
+.IR handled_access_fs .
+In order to add new rules with this access right,
+the bit must still be set explicitly
+(see
+.B Filesystem actions
+in
+.BR landlock (7)).
+.IP
+The explicit listing of
+.I handled access rights
+is required for backwards compatibility reasons.
+In most use cases,
+processes that use Landlock will
+.I handle
+a wide range or all access rights that they know about at build time
+(and that they have tested with a kernel that supported them all).
+.IP
+This structure can grow in future Landlock versions.
 .P
 .I size
 must be specified as
-- 
2.45.2.1089.g2a221341d9-goog

[PATCH v2 3/5] landlock_add_rule.2: Document missing reason for EINVAL

[Günther Noack]

This documents a missing reason for why EINVAL might be returned.
The documented behavior exists since the first version of Landlock.

Reviewed-by: Mickaël Salaün <mic@digikod.net>
Signed-off-by: Günther Noack <gnoack@google.com>
---
 man/man2/landlock_add_rule.2 | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/man/man2/landlock_add_rule.2 b/man/man2/landlock_add_rule.2
index fa0b1f109..530b45947 100644
--- a/man/man2/landlock_add_rule.2
+++ b/man/man2/landlock_add_rule.2
@@ -101,6 +101,16 @@ The rule accesses are inconsistent (i.e.,
 .I rule_attr\->allowed_access
 is not a subset of the ruleset handled accesses).
 .TP
+.B EINVAL
+In
+.IR "struct landlock_path_beneath_attr" ,
+the rule accesses are not applicable to the file
+(i.e., some access rights in
+.I rule_attr\->allowed_access
+are only applicable to directories, but
+.I rule_attr\->parent_fd
+does not refer to a directory).
+.TP
 .B ENOMSG
 Empty accesses (i.e.,
 .I rule_attr\->allowed_access
-- 
2.45.2.1089.g2a221341d9-goog

[PATCH v2 4/5] landlock.7, landlock_*.2: Document Landlock ABI version 4

[Günther Noack]

Landlock ABI 4 restricts bind(2) and connect(2) on TCP port numbers.

The intent is to bring the man pages mostly in line with the kernel
documentation again.  I intentionally did not add networking support to the
usage example in landlock.7 - I feel that in the long run, we would be better
advised to maintain longer example code in the kernel samples.

Closes: https://github.com/landlock-lsm/linux/issues/32
Cc: Konstantin Meskhidze <konstantin.meskhidze@huawei.com>
Reviewed-by: Mickaël Salaün <mic@digikod.net>
Signed-off-by: Günther Noack <gnoack@google.com>
---
 man/man2/landlock_add_rule.2       | 74 ++++++++++++++++++++++++++----
 man/man2/landlock_create_ruleset.2 | 12 ++++-
 man/man7/landlock.7                | 23 ++++++++--
 3 files changed, 94 insertions(+), 15 deletions(-)

diff --git a/man/man2/landlock_add_rule.2 b/man/man2/landlock_add_rule.2
index 530b45947..a0ab13419 100644
--- a/man/man2/landlock_add_rule.2
+++ b/man/man2/landlock_add_rule.2
@@ -20,15 +20,14 @@ Standard C library
 .BI "            const void *" rule_attr ", uint32_t " flags );
 .fi
 .SH DESCRIPTION
-A Landlock rule describes an action on an object.
-An object is currently a file hierarchy,
-and the related filesystem actions
-are defined with a set of access rights.
-This
+A Landlock rule describes an action on an object
+which the process intends to perform.
+A set of rules is aggregated in a ruleset,
+which can then restrict the thread enforcing it, and its future children.
+.P
+The
 .BR landlock_add_rule ()
-system call enables adding a new Landlock rule to an existing ruleset
-created with
-.BR landlock_create_ruleset (2).
+system call adds a new Landlock rule to an existing ruleset.
 See
 .BR landlock (7)
 for a global overview.
@@ -42,10 +41,15 @@ identifies the structure type pointed to by
 .IR rule_attr .
 Currently, Linux supports the following
 .I rule_type
-value:
+values:
 .TP
 .B LANDLOCK_RULE_PATH_BENEATH
-This defines the object type as a file hierarchy.
+For these rules,
+the object is a file hierarchy,
+and the related filesystem actions
+are defined with
+.IR "filesystem access rights" .
+.IP
 In this case,
 .I rule_attr
 points to the following structure:
@@ -74,6 +78,45 @@ is an opened file descriptor, preferably with the
 flag,
 which identifies the parent directory of the file hierarchy or
 just a file.
+.TP
+.B LANDLOCK_RULE_NET_PORT
+For these rules,
+the object is a TCP port,
+and the related actions are defined with
+.IR "network access rights" .
+.IP
+In this case,
+.I rule_attr
+points to the following structure:
+.IP
+.in +4n
+.EX
+struct landlock_net_port_attr {
+    __u64 allowed_access;
+    __u64 port;
+};
+.EE
+.in
+.IP
+.i allowed_access
+contains a bitmask of allowed network actions,
+which can be applied on the given port.
+.IP
+.i port
+is the network port in host endianness.
+.IP
+It should be noted that port 0 passed to
+.BR bind (2)
+will bind to an available port from the ephemeral port range.
+This can be configured in the
+.I /proc/sys/net/ipv4/ip_local_port_range
+sysctl (also used for IPv6).
+.IP
+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.
 .P
 .I flags
 must be 0.
@@ -89,6 +132,12 @@ is set to indicate the error.
 .BR landlock_add_rule ()
 can fail for the following reasons:
 .TP
+.B EAFNOSUPPORT
+.I rule_type
+is
+.BR LANDLOCK_RULE_NET_PORT ,
+but TCP is not supported by the running kernel.
+.TP
 .B EOPNOTSUPP
 Landlock is supported by the kernel but disabled at boot time.
 .TP
@@ -111,6 +160,11 @@ are only applicable to directories, but
 .I rule_attr\->parent_fd
 does not refer to a directory).
 .TP
+.B EINVAL
+In
+.IR "struct landlock_net_port_attr" ,
+the port number is greater than 65535.
+.TP
 .B ENOMSG
 Empty accesses (i.e.,
 .I rule_attr\->allowed_access
diff --git a/man/man2/landlock_create_ruleset.2 b/man/man2/landlock_create_ruleset.2
index 105e9b062..ca635ddbc 100644
--- a/man/man2/landlock_create_ruleset.2
+++ b/man/man2/landlock_create_ruleset.2
@@ -41,6 +41,7 @@ It points to the following structure:
 .EX
 struct landlock_ruleset_attr {
     __u64 handled_access_fs;
+    __u64 handled_access_net;
 };
 .EE
 .in
@@ -52,6 +53,13 @@ is a bitmask of handled filesystem actions
 in
 .BR landlock (7)).
 .IP
+.I handled_access_net
+is a bitmask of handled network actions
+(see
+.B Network actions
+in
+.BR landlock (7)).
+.IP
 This structure defines a set of
 .IR "handled access rights" ,
 a set of actions on different object types,
@@ -143,8 +151,8 @@ was not a valid address.
 .TP
 .B ENOMSG
 Empty accesses (i.e.,
-.I attr\->handled_access_fs
-is 0).
+.I attr
+did not specify any access rights to restrict).
 .SH STANDARDS
 Linux.
 .SH HISTORY
diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
index 652054f15..52876a3de 100644
--- a/man/man7/landlock.7
+++ b/man/man7/landlock.7
@@ -189,6 +189,19 @@ If multiple requirements are not met, the
 error code takes precedence over
 .BR EXDEV .
 .\"
+.SS Network flags
+These flags enable to restrict a sandboxed process
+to a set of network actions.
+This is supported since the Landlock ABI version 4.
+.P
+The following access rights apply to TCP port numbers:
+.TP
+.B LANDLOCK_ACCESS_NET_BIND_TCP
+Bind a TCP socket to a local port.
+.TP
+.B LANDLOCK_ACCESS_NET_CONNECT_TCP
+Connect an active TCP socket to a remote port.
+.\"
 .SS Layers of file path access rights
 Each time a thread enforces a ruleset on itself,
 it updates its Landlock domain with a new layer of policy.
@@ -339,6 +352,9 @@ _	_	_
 2	5.19	LANDLOCK_ACCESS_FS_REFER
 _	_	_
 3	6.2	LANDLOCK_ACCESS_FS_TRUNCATE
+_	_	_
+4	6.7	LANDLOCK_ACCESS_NET_BIND_TCP
+\^	\^	LANDLOCK_ACCESS_NET_CONNECT_TCP
 .TE
 .P
 Users should use the Landlock ABI version rather than the kernel version
@@ -439,9 +455,10 @@ 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_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     */
 };
 \&
 int abi = landlock_create_ruleset(NULL, 0,
-- 
2.45.2.1089.g2a221341d9-goog

[PATCH v2 5/5] landlock.7: Document Landlock ABI version 5 (IOCTL)

[Günther Noack]

Landlock ABI 5 restricts ioctl(2) on device files.

Closes: https://github.com/landlock-lsm/linux/issues/39
Reviewed-by: Mickaël Salaün <mic@digikod.net>
Signed-off-by: Günther Noack <gnoack@google.com>
---
 man/man7/landlock.7 | 53 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 50 insertions(+), 3 deletions(-)

diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
index 52876a3de..c6b7272ea 100644
--- a/man/man7/landlock.7
+++ b/man/man7/landlock.7
@@ -89,9 +89,11 @@ with
 .BR O_TRUNC .
 .IP
 This access right is available since the third version of the Landlock ABI.
-.IP
+.P
 Whether an opened file can be truncated with
 .BR ftruncate (2)
+or used with
+.BR ioctl (2)
 is determined during
 .BR open (2),
 in the same way as read and write permissions are checked during
@@ -188,6 +190,48 @@ If multiple requirements are not met, the
 .B EACCES
 error code takes precedence over
 .BR EXDEV .
+.P
+The following access right
+applies to both files and directories:
+.TP
+.B LANDLOCK_ACCESS_FS_IOCTL_DEV
+Invoke
+.BR ioctl (2)
+commands on an opened character or block device.
+.IP
+This access right applies to all
+.BR ioctl (2)
+commands implemented by device drivers.
+However, the following common IOCTL commands continue to be invokable
+independent of the
+.B LANDLOCK_ACCESS_FS_IOCTL_DEV
+right:
+.RS
+.IP \[bu] 3
+IOCTL commands targeting file descriptors
+.RB ( FIOCLEX ,
+.BR FIONCLEX ),
+.IP \[bu]
+IOCTL commands targeting file descriptions
+.RB ( FIONBIO ,
+.BR FIOASYNC ),
+.IP \[bu]
+IOCTL commands targeting file systems
+.RB ( FIFREEZE ,
+.BR FITHAW ,
+.BR FIGETBSZ ,
+.BR FS_IOC_GETFSUUID ,
+.BR FS_IOC_GETFSSYSFSPATH )
+.IP \[bu]
+Some IOCTL commands which do not make sense when used with devices, but
+whose implementations are safe and return the right error codes
+.RB ( FS_IOC_FIEMAP ,
+.BR FICLONE ,
+.BR FICLONERANGE ,
+.BR FIDEDUPERANGE )
+.RE
+.IP
+This access right is available since the fifth version of the Landlock ABI.
 .\"
 .SS Network flags
 These flags enable to restrict a sandboxed process
@@ -355,6 +399,8 @@ _	_	_
 _	_	_
 4	6.7	LANDLOCK_ACCESS_NET_BIND_TCP
 \^	\^	LANDLOCK_ACCESS_NET_CONNECT_TCP
+_	_	_
+5	6.10	LANDLOCK_ACCESS_FS_IOCTL_DEV
 .TE
 .P
 Users should use the Landlock ABI version rather than the kernel version
@@ -405,7 +451,6 @@ accessible through these system call families:
 .BR chown (2),
 .BR setxattr (2),
 .BR utime (2),
-.BR ioctl (2),
 .BR fcntl (2),
 .BR access (2).
 Future Landlock evolutions will enable to restrict them.
@@ -440,7 +485,8 @@ attr.handled_access_fs =
         LANDLOCK_ACCESS_FS_MAKE_BLOCK |
         LANDLOCK_ACCESS_FS_MAKE_SYM |
         LANDLOCK_ACCESS_FS_REFER |
-        LANDLOCK_ACCESS_FS_TRUNCATE;
+        LANDLOCK_ACCESS_FS_TRUNCATE |
+        LANDLOCK_ACCESS_FS_IOCTL_DEV;
 .EE
 .in
 .P
@@ -459,6 +505,7 @@ __u64 landlock_fs_access_rights[] = {
     (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" */
 };
 \&
 int abi = landlock_create_ruleset(NULL, 0,
-- 
2.45.2.1089.g2a221341d9-goog

Re: [PATCH v2 2/5] landlock_create_ruleset.2: Update docs for landlock_ruleset_attr

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2366 bytes --]

Hi Günther,

On Fri, Jul 19, 2024 at 01:37:59PM GMT, Günther Noack wrote:
> This updates the documentation for struct landlock_ruleset_attr
> in line with the changed kernel documentation (see link below).
> 
> Cc: Alejandro Colomar <alx@kernel.org>
> Link: https://lore.kernel.org/all/20240711165456.2148590-2-gnoack@google.com/

I prefer links enclosed in <>, as recommended in uri(7).  (I've amended
the commit myself.)

> Reviewed-by: Mickaël Salaün <mic@digikod.net>
> Signed-off-by: Günther Noack <gnoack@google.com>

Cheers,
Alex

> ---
>  man/man2/landlock_create_ruleset.2 | 34 ++++++++++++++++++++++++++++--
>  1 file changed, 32 insertions(+), 2 deletions(-)
> 
> diff --git a/man/man2/landlock_create_ruleset.2 b/man/man2/landlock_create_ruleset.2
> index 871b91dcb..105e9b062 100644
> --- a/man/man2/landlock_create_ruleset.2
> +++ b/man/man2/landlock_create_ruleset.2
> @@ -51,8 +51,38 @@ is a bitmask of handled filesystem actions
>  .B Filesystem actions
>  in
>  .BR landlock (7)).
> -This enables simply restricting ambient rights
> -(e.g., global filesystem access) and is needed for compatibility reasons.
> +.IP
> +This structure defines a set of
> +.IR "handled access rights" ,
> +a set of actions on different object types,
> +which should be denied by default
> +when the ruleset is enacted.
> +Vice versa,
> +access rights that are not specifically listed here
> +are not going to be denied by this ruleset when it is enacted.
> +.IP
> +For historical reasons, the
> +.B LANDLOCK_ACCESS_FS_REFER
> +right is always denied by default,
> +even when its bit is not set in
> +.IR handled_access_fs .
> +In order to add new rules with this access right,
> +the bit must still be set explicitly
> +(see
> +.B Filesystem actions
> +in
> +.BR landlock (7)).
> +.IP
> +The explicit listing of
> +.I handled access rights
> +is required for backwards compatibility reasons.
> +In most use cases,
> +processes that use Landlock will
> +.I handle
> +a wide range or all access rights that they know about at build time
> +(and that they have tested with a kernel that supported them all).
> +.IP
> +This structure can grow in future Landlock versions.
>  .P
>  .I size
>  must be specified as
> -- 
> 2.45.2.1089.g2a221341d9-goog
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 1/5] landlock.7, landlock_*.2: wfix

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 4933 bytes --]

Hi Günther,

On Fri, Jul 19, 2024 at 01:37:58PM GMT, Günther Noack wrote:
> * Various wording fixes
> * List the same error code multiple times,
>   if it can happen for multiple reasons.
> 
> Reviewed-by: Mickaël Salaün <mic@digikod.net>
> Signed-off-by: Günther Noack <gnoack@google.com>
> ---
>  man/man2/landlock_add_rule.2       |  9 +++++++--
>  man/man2/landlock_create_ruleset.2 |  6 +++---
>  man/man2/landlock_restrict_self.2  | 11 ++++++-----
>  man/man7/landlock.7                |  6 ++++--
>  4 files changed, 20 insertions(+), 12 deletions(-)
> 
> diff --git a/man/man2/landlock_add_rule.2 b/man/man2/landlock_add_rule.2
> index d4ae8f2f6..fa0b1f109 100644
> --- a/man/man2/landlock_add_rule.2
> +++ b/man/man2/landlock_add_rule.2
> @@ -60,7 +60,9 @@ struct landlock_path_beneath_attr {
>  .in
>  .IP
>  .I allowed_access
> -contains a bitmask of allowed filesystem actions for this file hierarchy
> +contains a bitmask of allowed filesystem actions,
> +which can be applied on the given
> +.I parent_fd
>  (see
>  .B Filesystem actions
>  in
> @@ -92,7 +94,10 @@ Landlock is supported by the kernel but disabled at boot time.
>  .TP
>  .B EINVAL
>  .I flags
> -is not 0, or the rule accesses are inconsistent (i.e.,
> +is not 0.
> +.TP
> +.B EINVAL
> +The rule accesses are inconsistent (i.e.,
>  .I rule_attr\->allowed_access
>  is not a subset of the ruleset handled accesses).
>  .TP
> diff --git a/man/man2/landlock_create_ruleset.2 b/man/man2/landlock_create_ruleset.2
> index 618d54f37..871b91dcb 100644
> --- a/man/man2/landlock_create_ruleset.2
> +++ b/man/man2/landlock_create_ruleset.2
> @@ -23,7 +23,8 @@ Standard C library
>  A Landlock ruleset identifies a set of rules (i.e., actions on objects).
>  This
>  .BR landlock_create_ruleset ()
> -system call enables creating a new file descriptor identifying a ruleset.
> +system call creates a new file descriptor
> +which identifies a ruleset.
>  This file descriptor can then be used by
>  .BR landlock_add_rule (2)
>  and
> @@ -45,8 +46,7 @@ struct landlock_ruleset_attr {
>  .in
>  .IP
>  .I handled_access_fs
> -is a bitmask of actions that is handled by this ruleset and
> -should then be forbidden if no rule explicitly allows them
> +is a bitmask of handled filesystem actions
>  (see
>  .B Filesystem actions
>  in
> diff --git a/man/man2/landlock_restrict_self.2 b/man/man2/landlock_restrict_self.2
> index d4e5e753c..f044c6b31 100644
> --- a/man/man2/landlock_restrict_self.2
> +++ b/man/man2/landlock_restrict_self.2
> @@ -20,7 +20,7 @@ Standard C library
>  .SH DESCRIPTION
>  Once a Landlock ruleset is populated with the desired rules, the
>  .BR landlock_restrict_self ()
> -system call enables enforcing this ruleset on the calling thread.
> +system call enforces this ruleset on the calling thread.
>  See
>  .BR landlock (7)
>  for a global overview.
> @@ -38,10 +38,11 @@ with multiple independent rulesets coming from different sources
>  built-in application policy).
>  However, most applications should only need one call to
>  .BR landlock_restrict_self ()
> -and they should avoid arbitrary numbers of such calls because of the
> -composed rulesets limit.
> -Instead, developers are encouraged to build a tailored ruleset thanks to
> -multiple calls to
> +and they should avoid arbitrary numbers of such calls
> +because of the composed rulesets limit.
> +Instead,
> +developers are encouraged to build a single tailored ruleset
> +with multiple calls to
>  .BR landlock_add_rule (2).
>  .P
>  In order to enforce a ruleset, either the caller must have the
> diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
> index 4a98f6549..652054f15 100644
> --- a/man/man7/landlock.7
> +++ b/man/man7/landlock.7
> @@ -58,7 +58,7 @@ and
>  .BR landlock_create_ruleset (2)
>  for more context.
>  .P
> -A file can only receive these access rights:
> +The following access rights apply only to files:
>  .TP
>  .B LANDLOCK_ACCESS_FS_EXECUTE
>  Execute a file.
> @@ -87,6 +87,9 @@ or
>  .BR open (2)
>  with
>  .BR O_TRUNC .
> +.IP
> +This access right is available since the third version of the Landlock ABI.
> +.IP
>  Whether an opened file can be truncated with
>  .BR ftruncate (2)
>  is determined during
> @@ -97,7 +100,6 @@ using
>  .B LANDLOCK_ACCESS_FS_READ_FILE
>  and
>  .BR LANDLOCK_ACCESS_FS_WRITE_FILE .
> -This access right is available since the third version of the Landlock ABI.

I think this would be better as a ` "(since Landlock ABI v3)"` in the
TP.  Feel free to send some patches for doing that consistently, if you
feel like.

Cheers,
Alex

>  .P
>  A directory can receive access rights related to files or directories.
>  The following access right is applied to the directory itself,
> -- 
> 2.45.2.1089.g2a221341d9-goog
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 4/5] landlock.7, landlock_*.2: Document Landlock ABI version 4

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 7621 bytes --]

Hi Günther,

On Fri, Jul 19, 2024 at 01:38:01PM GMT, Günther Noack wrote:
> Landlock ABI 4 restricts bind(2) and connect(2) on TCP port numbers.
> 
> The intent is to bring the man pages mostly in line with the kernel
> documentation again.  I intentionally did not add networking support to the
> usage example in landlock.7 - I feel that in the long run, we would be better
> advised to maintain longer example code in the kernel samples.
> 
> Closes: https://github.com/landlock-lsm/linux/issues/32
> Cc: Konstantin Meskhidze <konstantin.meskhidze@huawei.com>
> Reviewed-by: Mickaël Salaün <mic@digikod.net>
> Signed-off-by: Günther Noack <gnoack@google.com>
> ---

I've applied patches 1, 2, and 3.  I applied some tweaks to 3, which
might be the reason why this doesn't apply.  Would you mind rebasing
4 and 5?  Thanks!

Have a lovely night!
Alex

>  man/man2/landlock_add_rule.2       | 74 ++++++++++++++++++++++++++----
>  man/man2/landlock_create_ruleset.2 | 12 ++++-
>  man/man7/landlock.7                | 23 ++++++++--
>  3 files changed, 94 insertions(+), 15 deletions(-)
> 
> diff --git a/man/man2/landlock_add_rule.2 b/man/man2/landlock_add_rule.2
> index 530b45947..a0ab13419 100644
> --- a/man/man2/landlock_add_rule.2
> +++ b/man/man2/landlock_add_rule.2
> @@ -20,15 +20,14 @@ Standard C library
>  .BI "            const void *" rule_attr ", uint32_t " flags );
>  .fi
>  .SH DESCRIPTION
> -A Landlock rule describes an action on an object.
> -An object is currently a file hierarchy,
> -and the related filesystem actions
> -are defined with a set of access rights.
> -This
> +A Landlock rule describes an action on an object
> +which the process intends to perform.
> +A set of rules is aggregated in a ruleset,
> +which can then restrict the thread enforcing it, and its future children.
> +.P
> +The
>  .BR landlock_add_rule ()
> -system call enables adding a new Landlock rule to an existing ruleset
> -created with
> -.BR landlock_create_ruleset (2).
> +system call adds a new Landlock rule to an existing ruleset.
>  See
>  .BR landlock (7)
>  for a global overview.
> @@ -42,10 +41,15 @@ identifies the structure type pointed to by
>  .IR rule_attr .
>  Currently, Linux supports the following
>  .I rule_type
> -value:
> +values:
>  .TP
>  .B LANDLOCK_RULE_PATH_BENEATH
> -This defines the object type as a file hierarchy.
> +For these rules,
> +the object is a file hierarchy,
> +and the related filesystem actions
> +are defined with
> +.IR "filesystem access rights" .
> +.IP
>  In this case,
>  .I rule_attr
>  points to the following structure:
> @@ -74,6 +78,45 @@ is an opened file descriptor, preferably with the
>  flag,
>  which identifies the parent directory of the file hierarchy or
>  just a file.
> +.TP
> +.B LANDLOCK_RULE_NET_PORT
> +For these rules,
> +the object is a TCP port,
> +and the related actions are defined with
> +.IR "network access rights" .
> +.IP
> +In this case,
> +.I rule_attr
> +points to the following structure:
> +.IP
> +.in +4n
> +.EX
> +struct landlock_net_port_attr {
> +    __u64 allowed_access;
> +    __u64 port;
> +};
> +.EE
> +.in
> +.IP
> +.i allowed_access
> +contains a bitmask of allowed network actions,
> +which can be applied on the given port.
> +.IP
> +.i port
> +is the network port in host endianness.
> +.IP
> +It should be noted that port 0 passed to
> +.BR bind (2)
> +will bind to an available port from the ephemeral port range.
> +This can be configured in the
> +.I /proc/sys/net/ipv4/ip_local_port_range
> +sysctl (also used for IPv6).
> +.IP
> +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.
>  .P
>  .I flags
>  must be 0.
> @@ -89,6 +132,12 @@ is set to indicate the error.
>  .BR landlock_add_rule ()
>  can fail for the following reasons:
>  .TP
> +.B EAFNOSUPPORT
> +.I rule_type
> +is
> +.BR LANDLOCK_RULE_NET_PORT ,
> +but TCP is not supported by the running kernel.
> +.TP
>  .B EOPNOTSUPP
>  Landlock is supported by the kernel but disabled at boot time.
>  .TP
> @@ -111,6 +160,11 @@ are only applicable to directories, but
>  .I rule_attr\->parent_fd
>  does not refer to a directory).
>  .TP
> +.B EINVAL
> +In
> +.IR "struct landlock_net_port_attr" ,
> +the port number is greater than 65535.
> +.TP
>  .B ENOMSG
>  Empty accesses (i.e.,
>  .I rule_attr\->allowed_access
> diff --git a/man/man2/landlock_create_ruleset.2 b/man/man2/landlock_create_ruleset.2
> index 105e9b062..ca635ddbc 100644
> --- a/man/man2/landlock_create_ruleset.2
> +++ b/man/man2/landlock_create_ruleset.2
> @@ -41,6 +41,7 @@ It points to the following structure:
>  .EX
>  struct landlock_ruleset_attr {
>      __u64 handled_access_fs;
> +    __u64 handled_access_net;
>  };
>  .EE
>  .in
> @@ -52,6 +53,13 @@ is a bitmask of handled filesystem actions
>  in
>  .BR landlock (7)).
>  .IP
> +.I handled_access_net
> +is a bitmask of handled network actions
> +(see
> +.B Network actions
> +in
> +.BR landlock (7)).
> +.IP
>  This structure defines a set of
>  .IR "handled access rights" ,
>  a set of actions on different object types,
> @@ -143,8 +151,8 @@ was not a valid address.
>  .TP
>  .B ENOMSG
>  Empty accesses (i.e.,
> -.I attr\->handled_access_fs
> -is 0).
> +.I attr
> +did not specify any access rights to restrict).
>  .SH STANDARDS
>  Linux.
>  .SH HISTORY
> diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
> index 652054f15..52876a3de 100644
> --- a/man/man7/landlock.7
> +++ b/man/man7/landlock.7
> @@ -189,6 +189,19 @@ If multiple requirements are not met, the
>  error code takes precedence over
>  .BR EXDEV .
>  .\"
> +.SS Network flags
> +These flags enable to restrict a sandboxed process
> +to a set of network actions.
> +This is supported since the Landlock ABI version 4.
> +.P
> +The following access rights apply to TCP port numbers:
> +.TP
> +.B LANDLOCK_ACCESS_NET_BIND_TCP
> +Bind a TCP socket to a local port.
> +.TP
> +.B LANDLOCK_ACCESS_NET_CONNECT_TCP
> +Connect an active TCP socket to a remote port.
> +.\"
>  .SS Layers of file path access rights
>  Each time a thread enforces a ruleset on itself,
>  it updates its Landlock domain with a new layer of policy.
> @@ -339,6 +352,9 @@ _	_	_
>  2	5.19	LANDLOCK_ACCESS_FS_REFER
>  _	_	_
>  3	6.2	LANDLOCK_ACCESS_FS_TRUNCATE
> +_	_	_
> +4	6.7	LANDLOCK_ACCESS_NET_BIND_TCP
> +\^	\^	LANDLOCK_ACCESS_NET_CONNECT_TCP
>  .TE
>  .P
>  Users should use the Landlock ABI version rather than the kernel version
> @@ -439,9 +455,10 @@ 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_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     */
>  };
>  \&
>  int abi = landlock_create_ruleset(NULL, 0,
> -- 
> 2.45.2.1089.g2a221341d9-goog
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 4/5] landlock.7, landlock_*.2: Document Landlock ABI version 4

[Günther Noack]

On Mon, Jul 22, 2024 at 11:00:13PM +0200, Alejandro Colomar wrote:
> I've applied patches 1, 2, and 3.  I applied some tweaks to 3, which
> might be the reason why this doesn't apply.  Would you mind rebasing
> 4 and 5?  Thanks!

Thanks for the fixes with \% and \~, I did't know I could do this.

I re-sent it as V3 with patches 4/5 and 5/5,
it merged cleanly using:

  git rebase --onto master HEAD^^ my-branch

Thank you for the review at such a late hour! ;-)
—Günther