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

[PATCH 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).

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(-)

-- 
2.45.2.993.g49e7a77208-goog

[PATCH 1/5] landlock.7, landlock_*.2: Wording improvements

[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 <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..f7bb37cba 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.
+.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,
-- 
2.45.2.993.g49e7a77208-goog

Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements

[Alejandro Colomar]

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

Hi Günther,

> Subject: Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements

s/Wording improvements/wfix/

On Mon, Jul 15, 2024 at 03:55:50PM GMT, Günther Noack wrote:
> * Various wording fixes
> * List the same error code multiple times,
>   if it can happen for multiple reasons.
> 
> Cc: 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..f7bb37cba 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.
> +.P

Did you really want a P here?  Or maybe an 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.993.g49e7a77208-goog

Other than that, LGTM.

Cheers,
Alex

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

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

Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements

[Günther Noack]

On Mon, Jul 15, 2024 at 06:13:24PM +0200, Alejandro Colomar wrote:
> Hi Günther,
> 
> > Subject: Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements
> 
> s/Wording improvements/wfix/

Done.

> On Mon, Jul 15, 2024 at 03:55:50PM GMT, Günther Noack wrote:
> > +.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?

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.

> >  Whether an opened file can be truncated with
> >  .BR ftruncate (2)
> >  is determined during
> > @@ -97,7 +100,6 @@ using

Thanks,
—Günther

Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements

[Alejandro Colomar]

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

Hi Günther,

On Fri, Jul 19, 2024 at 03:17:45PM GMT, Günther Noack wrote:
> On Mon, Jul 15, 2024 at 06:13:24PM +0200, Alejandro Colomar wrote:
> > Hi Günther,
> > 
> > > Subject: Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements
> > 
> > s/Wording improvements/wfix/
> 
> Done.
> 
> > On Mon, Jul 15, 2024 at 03:55:50PM GMT, Günther Noack wrote:
> > > +.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?
> 
> 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.

Would you mind resending, with the minor fixes and the RB tags?  Thanks!

Have a lovely day!
Alex

> 
> > >  Whether an opened file can be truncated with
> > >  .BR ftruncate (2)
> > >  is determined during
> > > @@ -97,7 +100,6 @@ using
> 
> Thanks,
> —Günther
> 

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

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

Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements

[Mickaël Salaün]

On Mon, Jul 15, 2024 at 03:55:50PM +0000, Günther Noack wrote:
> * Various wording fixes
> * List the same error code multiple times,
>   if it can happen for multiple reasons.
> 
> Cc: Mickaël Salaün <mic@digikod.net>
> Signed-off-by: Günther Noack <gnoack@google.com>

Reviewed-by: Mickaël Salaün <mic@digikod.net>

> ---
>  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..f7bb37cba 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.
> +.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,
> -- 
> 2.45.2.993.g49e7a77208-goog
> 

[PATCH 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>
Cc: Mickaël Salaün <mic@digikod.net>
Link: https://lore.kernel.org/all/20240711165456.2148590-2-gnoack@google.com/
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.993.g49e7a77208-goog

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

[Mickaël Salaün]

On Mon, Jul 15, 2024 at 03:55:51PM +0000, 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>
> Cc: Mickaël Salaün <mic@digikod.net>
> Link: https://lore.kernel.org/all/20240711165456.2148590-2-gnoack@google.com/
> Signed-off-by: Günther Noack <gnoack@google.com>

Reviewed-by: Mickaël Salaün <mic@digikod.net>

> ---
>  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.993.g49e7a77208-goog
> 

[PATCH 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.

Cc: 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.993.g49e7a77208-goog

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

[Mickaël Salaün]

On Mon, Jul 15, 2024 at 03:55:52PM +0000, Günther Noack wrote:
> 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 <mic@digikod.net>
> Signed-off-by: Günther Noack <gnoack@google.com>

Reviewed-by: Mickaël Salaün <mic@digikod.net>

> ---
>  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.993.g49e7a77208-goog
> 

[PATCH 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.

Link: https://github.com/landlock-lsm/linux/issues/32
Cc: Konstantin Meskhidze <konstantin.meskhidze@huawei.com>
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 f7bb37cba..d452b93b2 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.993.g49e7a77208-goog

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

[Mickaël Salaün]

On Mon, Jul 15, 2024 at 03:55:53PM +0000, 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.
> 
> Link: https://github.com/landlock-lsm/linux/issues/32

In this case, we should use "Closes" instead of "Link".

Closes: https://github.com/landlock-lsm/linux/issues/32

> Cc: Konstantin Meskhidze <konstantin.meskhidze@huawei.com>
> Signed-off-by: Günther Noack <gnoack@google.com>

Reviewed-by: Mickaël Salaün <mic@digikod.net>

Thanks!

> ---
>  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 f7bb37cba..d452b93b2 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.993.g49e7a77208-goog
> 

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

[Günther Noack]

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

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

diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
index d452b93b2..044f57208 100644
--- a/man/man7/landlock.7
+++ b/man/man7/landlock.7
@@ -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,
-- 
2.45.2.993.g49e7a77208-goog

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

[Alejandro Colomar]

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

Hi Günther,

On Mon, Jul 15, 2024 at 03:55:54PM GMT, Günther Noack wrote:
> Landlock ABI 5 restricts ioctl(2) on device files.
> 
> Link: https://github.com/landlock-lsm/linux/issues/39
> Cc: Mickaël Salaün <mic@digikod.net>
> Signed-off-by: Günther Noack <gnoack@google.com>
> ---
>  man/man7/landlock.7 | 51 +++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 49 insertions(+), 2 deletions(-)
> 
> diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
> index d452b93b2..044f57208 100644
> --- a/man/man7/landlock.7
> +++ b/man/man7/landlock.7
> @@ -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

Maybe s/IOCTL/ioctl(2)/ ?

> +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 |;

s/;//

right?

> +        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.993.g49e7a77208-goog
> 
> 

Have a lovely day!
Alex

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

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

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

[Mickaël Salaün]

On Mon, Jul 15, 2024 at 06:20:53PM +0200, Alejandro Colomar wrote:
> Hi Günther,
> 
> On Mon, Jul 15, 2024 at 03:55:54PM GMT, Günther Noack wrote:
> > Landlock ABI 5 restricts ioctl(2) on device files.
> > 
> > Link: https://github.com/landlock-lsm/linux/issues/39

s/Link:/Closes:/

Closes: https://github.com/landlock-lsm/linux/issues/39


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

Reviewed-by: Mickaël Salaün <mic@digikod.net>

> > ---
> >  man/man7/landlock.7 | 51 +++++++++++++++++++++++++++++++++++++++++++--
> >  1 file changed, 49 insertions(+), 2 deletions(-)
> > 
> > diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
> > index d452b93b2..044f57208 100644
> > --- a/man/man7/landlock.7
> > +++ b/man/man7/landlock.7
> > @@ -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
> 
> Maybe s/IOCTL/ioctl(2)/ ?

ioctl(2) is already used in the previous sentence, so it might be too
much?

> 
> > +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 |;
> 
> s/;//
> 
> right?

Correct

> 
> > +        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.993.g49e7a77208-goog
> > 
> > 
> 
> Have a lovely day!
> Alex
> 
> -- 
> <https://www.alejandro-colomar.es/>

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

[Günther Noack]

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!


On Tue, Jul 16, 2024 at 04:39:17PM +0200, Mickaël Salaün wrote:
> On Mon, Jul 15, 2024 at 06:20:53PM +0200, Alejandro Colomar wrote:
> > On Mon, Jul 15, 2024 at 03:55:54PM GMT, Günther Noack wrote:
> > > ---
> > >  man/man7/landlock.7 | 51 +++++++++++++++++++++++++++++++++++++++++++--
> > >  1 file changed, 49 insertions(+), 2 deletions(-)
> > > 
> > > diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
> > > index d452b93b2..044f57208 100644
> > > --- a/man/man7/landlock.7
> > > +++ b/man/man7/landlock.7
> > > @@ -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
> > 
> > Maybe s/IOCTL/ioctl(2)/ ?
> 
> 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.


> > > @@ -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?
> 
> Correct

Well spotted, thanks for the attention to detail!  Done.

—Günther