landlock*: Bring documentation up to date
cover landlock*: Bring documentation up to date
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).
Günther Noack (5):
landlock.7, landlock_*.2: Wording improvements 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(-)
Signature · 1 line
2.45.2.993.g49e7a77208-goog
PATCH 1/5 landlock.7, landlock_*.2: Wording improvements
* Various wording fixes
* List the same error code multiple times,
if it can happen for multiple reasons.
--- 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(-)
man/man2/landlock_add_rule.2 +7 -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
man/man2/landlock_create_ruleset.2 +3 -3
@@ -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
man/man2/landlock_restrict_self.2 +6 -5
@@ -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
man/man7/landlock.7 +4 -2
@@ -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. +.P 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,
Signature · 1 line
2.45.2.993.g49e7a77208-goog
Alejandro Colomar
maintainerRe: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements
Hi Günther,
Quoted 1 line
Subject: Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements
s/Wording improvements/wfix/
Quoted 107 lines · Günther Noack
* Various wording fixes
* List the same error code multiple times,
if it can happen for multiple reasons.Cc Mickaël Salaün <[email protected]>Signed-off-by Günther Noack <[email protected]>--- 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(-)man/man2/landlock_add_rule.2 +7
-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). .TPman/man2/landlock_create_ruleset.2 +3
-3@@ -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 inman/man2/landlock_restrict_self.2 +6
-5@@ -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 theman/man7/landlock.7 +1
-1@@ -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.
man/man7/landlock.7 or · line 92
Quoted 6 lines
man/man7/landlock.7 +3
-0@@ -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. +.P
Did you really want a P here? Or maybe an IP?
Quoted 13 lines
man/man7/landlock.7 +0
-1Whether 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,Signature · 1 line
2.45.2.993.g49e7a77208-goog
Other than that, LGTM.
Cheers,
Alex
Signature · 1 line
<https://www.alejandro-colomar.es/>
Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements
Quoted 5 lines · Alejandro Colomar
Hi Günther,
Quoted 1 line
Subject: Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements
s/Wording improvements/wfix/
Done.
Quoted 6 lines · Günther Noack
Quoted 3 lines
+.IP
+This access right is available since the third version of the Landlock ABI. +.PDid you really want a P here? Or maybe an IP?
Well spotted, thanks! Done.
The de-dentation is only needed once the paragraph talks about both truncate and ioctl operations (patch 5/5). Must have happened when I reshuffled the patch set. In patch 5/5 it becomes .P again.
Quoted 4 lines
Review using
Quoted 4 lines
Whether an opened file can be truncated with
.BR ftruncate (2)
is determined during(quoted diff) +0
-0@@ -97,7 +100,6 @@ using
Thanks,
—Günther
Alejandro Colomar
maintainerRe: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements
Hi Günther,
Quoted 9 lines · Günther Noack
Quoted 5 lines · Alejandro Colomar
Hi Günther,
Quoted 1 line
Subject: Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements
s/Wording improvements/wfix/
Done.
Quoted 8 lines
Quoted 6 lines · Günther Noack
Quoted 3 lines
+.IP
+This access right is available since the third version of the Landlock ABI. +.PDid you really want a P here? Or maybe an IP?
Well spotted, thanks! Done.
:)
Quoted 4 lines
The de-dentation is only needed once the paragraph talks about both truncate and ioctl operations (patch 5/5). Must have happened when I reshuffled the patch set. In patch 5/5 it becomes .P again.
Would you mind resending, with the minor fixes and the RB tags? Thanks!
Have a lovely day!
Alex
Quoted 9 lines
Quoted 5 lines
Review using
Quoted 5 lines
Whether an opened file can be truncated with
.BR ftruncate (2)
is determined during(quoted diff) +0
-0@@ -97,7 +100,6 @@ usingThanks,
—Günther
Signature · 1 line
<https://www.alejandro-colomar.es/>
Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements
In reply to Günther NoackQuoted 6 lines · Günther Noack
* Various wording fixes
* List the same error code multiple times,
if it can happen for multiple reasons.Cc Mickaël Salaün <[email protected]>Signed-off-by Günther Noack <[email protected]>
Quoted 121 lines
--- 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(-)man/man2/landlock_add_rule.2 +7
-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). .TPman/man2/landlock_create_ruleset.2 +3
-3@@ -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 inman/man2/landlock_restrict_self.2 +6
-5@@ -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 theman/man7/landlock.7 +4
-2@@ -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. +.P 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,Signature · 1 line
2.45.2.993.g49e7a77208-goog
PATCH 2/5 landlock_create_ruleset.2: Update docs for landlock_ruleset_attr
In reply to Günther NoackThis updates the documentation for struct landlock_ruleset_attr in line with the changed kernel documentation (see link below).
--- man/man2/landlock_create_ruleset.2 | 34 ++++++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-)
man/man2/landlock_create_ruleset.2 +32 -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
Signature · 1 line
2.45.2.993.g49e7a77208-goog
Re: [PATCH 2/5] landlock_create_ruleset.2: Update docs for landlock_ruleset_attr
Quoted 7 lines · Günther Noack
This updates the documentation for struct
landlock_ruleset_attrin line with the changed kernel documentation (see link below).Cc Alejandro Colomar <[email protected]>Cc Mickaël Salaün <[email protected]>Signed-off-by Günther Noack <[email protected]>
Quoted 52 lines
--- man/man2/landlock_create_ruleset.2 | 34 ++++++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-)man/man2/landlock_create_ruleset.2 +32
-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 asSignature · 1 line
2.45.2.993.g49e7a77208-goog
PATCH 3/5 landlock_add_rule.2: Document missing reason for EINVAL
In reply to Günther NoackThis documents a missing reason for why EINVAL might be returned. The documented behavior exists since the first version of Landlock.
--- man/man2/landlock_add_rule.2 | 10 ++++++++++ 1 file changed, 10 insertions(+)
man/man2/landlock_add_rule.2 +10 -0
@@ -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
Signature · 1 line
2.45.2.993.g49e7a77208-goog
Re: [PATCH 3/5] landlock_add_rule.2: Document missing reason for EINVAL
Quoted 5 lines · Günther Noack
This documents a missing reason for why EINVAL might be returned. The documented behavior exists since the first version of Landlock.
Cc Mickaël Salaün <[email protected]>Signed-off-by Günther Noack <[email protected]>
Quoted 28 lines
--- man/man2/landlock_add_rule.2 | 10 ++++++++++ 1 file changed, 10 insertions(+)man/man2/landlock_add_rule.2 +10
-0@@ -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_accessSignature · 1 line
2.45.2.993.g49e7a77208-goog
PATCH 4/5 landlock.7, landlock_*.2: Document Landlock ABI version 4
In reply to Günther NoackLandlock 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.
--- 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(-)
man/man2/landlock_add_rule.2 +64 -10
@@ -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
man/man2/landlock_create_ruleset.2 +10 -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
man/man7/landlock.7 +20 -3
@@ -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,
Signature · 1 line
2.45.2.993.g49e7a77208-goog
Re: [PATCH 4/5] landlock.7, landlock_*.2: Document Landlock ABI version 4
Quoted 8 lines · 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.
In this case, we should use "Closes" instead of "Link".
Quoted 2 lines
Cc Konstantin Meskhidze <[email protected]>Signed-off-by Günther Noack <[email protected]>
Thanks!
Quoted 210 lines
--- 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(-)man/man2/landlock_add_rule.2 +64
-10@@ -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_accessman/man2/landlock_create_ruleset.2 +10
-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 HISTORYman/man7/landlock.7 +20
-3@@ -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,Signature · 1 line
2.45.2.993.g49e7a77208-goog
PATCH 5/5 landlock.7: Document Landlock ABI version 5 (IOCTL)
In reply to Günther NoackLandlock ABI 5 restricts ioctl(2) on device files.
--- man/man7/landlock.7 | 51 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 2 deletions(-)
man/man7/landlock.7 +49 -2
@@ -92,6 +92,8 @@ This access right is available since the third version of the Landlock ABI. .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,
Signature · 1 line
2.45.2.993.g49e7a77208-goog
Alejandro Colomar
maintainerRe: [PATCH 5/5] landlock.7: Document Landlock ABI version 5 (IOCTL)
Hi Günther,
Quoted 29 lines · Günther Noack
Landlock ABI 5 restricts ioctl(2) on device files.
Cc Mickaël Salaün <[email protected]>Signed-off-by Günther Noack <[email protected]>--- man/man7/landlock.7 | 51 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 2 deletions(-)man/man7/landlock.7 +5
-0@@ -92,6 +92,8 @@ This access right is available since the third version of the Landlock ABI. .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:
man/man7/landlock.7 If multiple requirements are not met, the · line 205
Quoted 10 lines
man/man7/landlock.7 +10
-0+.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
Maybe s/IOCTL/ioctl(2)/ ?
Quoted 50 lines
man/man7/landlock.7 +31
-1+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.
man/man7/landlock.7 attr.handled_access_fs = · line 488
Quoted 5 lines
man/man7/landlock.7 +1
-1@@ -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 |;
s/;//
right?
Quoted 16 lines
man/man7/landlock.7 +2
-0+ 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,Signature · 1 line
2.45.2.993.g49e7a77208-goog
Have a lovely day!
Alex
Signature · 1 line
<https://www.alejandro-colomar.es/>
Mickaël Salaün
Reviewed-byRe: [PATCH 5/5] landlock.7: Document Landlock ABI version 5 (IOCTL)
Quoted 6 lines · Alejandro Colomar
Hi Günther,
Quoted 3 lines · Günther Noack
Landlock ABI 5 restricts ioctl(2) on device files.
s/Link:/Closes:/
Quoted 2 lines
Quoted 2 lines
Cc Mickaël Salaün <[email protected]>Signed-off-by Günther Noack <[email protected]>
Quoted 28 lines
Quoted 28 lines
--- man/man7/landlock.7 | 51 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 2 deletions(-)man/man7/landlock.7 +9
-0@@ -92,6 +92,8 @@ This access right is available since the third version of the Landlock ABI. .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)
Quoted 8 lines
man/man7/landlock.7 If multiple requirements are not met, the · line 205
Quoted 6 lines
man/man7/landlock.7 +6
-0+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 invokableMaybe s/IOCTL/ioctl(2)/ ?
ioctl(2) is already used in the previous sentence, so it might be too much?
Quoted 59 lines
Quoted 51 lines
man/man7/landlock.7 +31
-1+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.man/man7/landlock.7 attr.handled_access_fs = · line 488
Quoted 5 lines
man/man7/landlock.7 +1
-1@@ -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 |;s/;//
Quoted 1 line
right?
Correct
Quoted 23 lines
Quoted 17 lines
man/man7/landlock.7 +2
-0+ 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,Signature · 1 line
2.45.2.993.g49e7a77208-googHave a lovely day!
AlexSignature · 1 line
<https://www.alejandro-colomar.es/>
Re: [PATCH 5/5] landlock.7: Document Landlock ABI version 5 (IOCTL)
Thank you both for the reviews!
I sent out a second version.
Konstantin: Please also do have a look if you are around, since this also covers the documentation for your networking connect/bind feature. Thank you!
Quoted 39 lines · Mickaël Salaün
Quoted 29 lines · Alejandro Colomar
Quoted 28 lines · Günther Noack
--- man/man7/landlock.7 | 51 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 2 deletions(-)man/man7/landlock.7 +9
-0@@ -92,6 +92,8 @@ This access right is available since the third version of the Landlock ABI. .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)Quoted 8 lines
man/man7/landlock.7 If multiple requirements are not met, the · line 205
Quoted 6 lines
man/man7/landlock.7 +6
-0+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 invokableMaybe s/IOCTL/ioctl(2)/ ?
Quoted 2 lines
ioctl(2) is already used in the previous sentence, so it might be too much?
I agree with Mickaël here, I feel that IOCTL might be more appropriate.
We've been using the uppercase spelling throughout the kernel docs to refer to IOCTL (the concept and the overall feature), as opposed to ioctl(2) (the specific system call).
This is the only remark which I left unaddressed in v2 of this patch set. We can change it though if you feel strongly about it, Alejandro. Otherwise I'd prefer to keep it in sync with the kernel documentation, to keep the delta between the kernel doc and man pages smaller.
Quoted 9 lines
Quoted 9 lines
man/man7/landlock.7 attr.handled_access_fs = · line 488
Quoted 6 lines
man/man7/landlock.7 +1
-1@@ -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 |;s/;//
Quoted 3 lines
Quoted 1 line
right?
Correct
Well spotted, thanks for the attention to detail! Done.
—Günther