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

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

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

Hi Günther,

On 2/21/23 21:50, Günther Noack wrote:
> https://lore.kernel.org/all/20221018182216.301684-1-gnoack3000@gmail.com/

Please see some comments below.

Cheers,

Alex

> ---
>   man7/landlock.7 | 80 +++++++++++++++++++++++++++++++++++++++++++++++--
>   1 file changed, 77 insertions(+), 3 deletions(-)
> 
> diff --git a/man7/landlock.7 b/man7/landlock.7
> index 6321b56ab..b5b356642 100644
> --- a/man7/landlock.7
> +++ b/man7/landlock.7
> @@ -63,10 +63,38 @@ A file can only receive these access rights:
>   Execute a file.
>   .TP
>   .B LANDLOCK_ACCESS_FS_WRITE_FILE
> -Open a file with write access.
> +Open a file with write access. Note that you might additionally need the

Again,
please use semantic newlines.

Also,
roff(7) requires two spaces after period in source code,
to detect sentence endings.
I say this as a curiosity,
since due to the requirement of semantic newlines,
we always write a newline after period.

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

Maybe it's simpler to say Landlock ABI v3?  That's usual convention in 
software, so not using formal English for that is not a crime :).

>   .PP
>   A directory can receive access rights related to files or directories.
>   The following access right is applied to the directory itself,
> @@ -228,6 +256,50 @@ 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" .
> +.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
> @@ -254,6 +326,8 @@ _	_	_
>   \^	\^	LANDLOCK_ACCESS_FS_MAKE_SYM
>   _	_	_
>   2	5.19	LANDLOCK_ACCESS_FS_REFER
> +_	_	_
> +3	6.2	LANDLOCK_ACCESS_FS_TRUNCATE
>   .TE
>   .PP
>   To query the running kernel's Landlock ABI level, programs may pass
> @@ -290,7 +364,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),
> @@ -328,7 +401,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 --]