Re: [PATCH v2 2/2] landlock.7: Document Landlock ABI v3 (file truncation; kernel 6.2)

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 5109 bytes --]

In the subject it's not so important, but for consistency with the
language used within the pages, I'd ask you to rewrite it as Linux 6.2
(and similarly for patch 1/2).

On 2/28/23 21:52, Günther Noack wrote:
> https://git.kernel.org/torvalds/c/299e2b1967578b1442128ba8b3e86ed3427d3651
> ---
>  man7/landlock.7 | 82 +++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 80 insertions(+), 2 deletions(-)
> 
> diff --git a/man7/landlock.7 b/man7/landlock.7
> index f70a01484..9ddb17ae8 100644
> --- a/man7/landlock.7
> +++ b/man7/landlock.7
> @@ -64,9 +64,38 @@ Execute a file.
>  .TP
>  .B LANDLOCK_ACCESS_FS_WRITE_FILE
>  Open a file with write access.
> +Note that you might additionally need the

"Note that" is usually redundant.
See:
<https://lore.kernel.org/linux-man/20210729223535.qvyomfqvvahzmu5w@localhost.localdomain/>
<https://lore.kernel.org/linux-man/20230105225235.6cjtz6orjzxzvo6v@illithid/>

> +.B LANDLOCK_ACCESS_FS_TRUNCATE
> +right in order to overwrite files with
> +.BR open (2)
> +using
> +.B O_TRUNC
> +or
> +.BR creat (2).
>  .TP
>  .B LANDLOCK_ACCESS_FS_READ_FILE
>  Open a file with read access.
> +.TP
> +.B LANDLOCK_ACCESS_FS_TRUNCATE
> +Truncate a file with
> +.BR truncate (2),
> +.BR ftruncate (2),
> +.BR creat (2),
> +or
> +.BR open (2)
> +with
> +.BR O_TRUNC .
> +Whether an opened file can be truncated with
> +.BR ftruncate (2)
> +is determined during
> +.BR open (2),
> +in the same way as read and write permissions are checked during
> +.BR open (2)
> +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.
>  .PP
>  A directory can receive access rights related to files or directories.
>  The following access right is applied to the directory itself,
> @@ -231,6 +260,53 @@ To be allowed to use
>  and related syscalls on a target process,
>  a sandboxed process should have a subset of the target process rules,
>  which means the tracee must be in a sub-domain of the tracer.
> +.\"
> +.SS Truncating files
> +The operations covered by
> +.B LANDLOCK_ACCESS_FS_WRITE_FILE
> +and
> +.B LANDLOCK_ACCESS_FS_TRUNCATE
> +both change the contents of a file and sometimes overlap in
> +non-intuitive ways.
> +It is recommended to always specify both of these together.
> +.PP
> +A particularly surprising example is
> +.BR creat (2).
> +The name suggests that this system call requires
> +the rights to create and write files.
> +However, it also requires the truncate right
> +if an existing file under the same name is already present.
> +.PP
> +It should also be noted that truncating files does not require the
> +.B LANDLOCK_ACCESS_FS_WRITE_FILE
> +right.
> +Apart from the
> +.BR truncate (2)
> +system call, this can also be done through
> +.BR open (2)
> +with the flags
> +.BR "O_RDONLY | O_TRUNC" .

Expressions should go in italics.  See man-pages(7):

       Expressions, if not written on a separate indented line, should
       be  specified in italics.  Again, the use of nonbreaking spaces
       may be appropriate if the expression  is  inlined  with  normal
       text.

Cheers,

Alex

> +.PP
> +When opening a file, the availability of the
> +.B LANDLOCK_ACCESS_FS_TRUNCATE
> +right is associated with the newly created file descriptor
> +and will be used for subsequent truncation attempts using
> +.BR ftruncate (2).
> +The behavior is similar to opening a file for reading or writing,
> +where permissions are checked during
> +.BR open (2),
> +but not during the subsequent
> +.BR read (2)
> +and
> +.BR write (2)
> +calls.
> +.PP
> +As a consequence,
> +it is possible to have multiple open file descriptors for the same file,
> +where one grants the right to truncate the file and the other does not.
> +It is also possible to pass such file descriptors between processes,
> +keeping their Landlock properties,
> +even when these processes do not have an enforced Landlock ruleset.
>  .SH VERSIONS
>  Landlock was introduced in Linux 5.13.
>  .PP
> @@ -257,6 +333,8 @@ _	_	_
>  \^	\^	LANDLOCK_ACCESS_FS_MAKE_SYM
>  _	_	_
>  2	5.19	LANDLOCK_ACCESS_FS_REFER
> +_	_	_
> +3	6.2	LANDLOCK_ACCESS_FS_TRUNCATE
>  .TE
>  .sp 1
>  .PP
> @@ -302,7 +380,6 @@ in kernel logs.
>  It is currently not possible to restrict some file-related actions
>  accessible through these system call families:
>  .BR chdir (2),
> -.BR truncate (2),
>  .BR stat (2),
>  .BR flock (2),
>  .BR chmod (2),
> @@ -340,7 +417,8 @@ attr.handled_access_fs =
>          LANDLOCK_ACCESS_FS_MAKE_FIFO |
>          LANDLOCK_ACCESS_FS_MAKE_BLOCK |
>          LANDLOCK_ACCESS_FS_MAKE_SYM |
> -        LANDLOCK_ACCESS_FS_REFER;
> +        LANDLOCK_ACCESS_FS_REFER |
> +        LANDLOCK_ACCESS_FS_TRUNCATE;
>  
>  ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0);
>  if (ruleset_fd == -1) {

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

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