[PATCH] landlock: Various documentation improvements

[Mickaël Salaün]

On Mon, Jul 15, 2024 at 04:03:29PM +0000, Günther Noack wrote:
> * Fix some typos, incomplete or confusing phrases.
> * Split paragraphs where appropriate.
> * List the same error code multiple times,
>   if it has multiple possible causes.
> * Bring wording closer to the man page wording,
>   which has undergone more thorough review
>   (esp. for LANDLOCK_ACCESS_FS_WRITE_FILE).
> * Small semantic clarifications
>   * Call the ephemeral port range "ephemeral"
>   * Clarify reasons for EFAULT in landlock_add_rule()
>   * Clarify @rule_type doc for landlock_add_rule()
> 
> This is a collection of small fixes which I collected when preparing the
> corresponding man pages (see link below).
> 
> Link: https://lore.kernel.org/all/20240715155554.2791018-1-gnoack@google.com/
> Cc: Konstantin Meskhidze <konstantin.meskhidze at huawei.com>
> Cc: Mickaël Salaün <mic at digikod.net>
> Cc: Alejandro Colomar <alx at kernel.org>
> Signed-off-by: Günther Noack <gnoack at google.com>

Thanks, applied!

> ---
>  include/uapi/linux/landlock.h | 27 ++++++++++++++-------------
>  security/landlock/syscalls.c  | 17 +++++++++--------
>  2 files changed, 23 insertions(+), 21 deletions(-)
> 
> diff --git a/include/uapi/linux/landlock.h b/include/uapi/linux/landlock.h
> index e76186da3260..2c8dbc74b955 100644
> --- a/include/uapi/linux/landlock.h
> +++ b/include/uapi/linux/landlock.h
> @@ -104,20 +104,21 @@ struct landlock_path_beneath_attr {
>   */
>  struct landlock_net_port_attr {
>  	/**
> -	 * @allowed_access: Bitmask of allowed access network for a port
> +	 * @allowed_access: Bitmask of allowed network actions for a port
>  	 * (cf. `Network flags`_).
>  	 */
>  	__u64 allowed_access;
>  	/**
>  	 * @port: Network port in host endianness.
>  	 *
> -	 * It should be noted that port 0 passed to :manpage:`bind(2)` will
> -	 * bind to an available port from a specific port range. This can be
> -	 * configured thanks to the ``/proc/sys/net/ipv4/ip_local_port_range``
> -	 * sysctl (also used for IPv6). A Landlock rule with port 0 and the
> -	 * ``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.
> +	 * It should be noted that port 0 passed to :manpage:`bind(2)` will bind
> +	 * to an available port from the ephemeral port range.  This can be
> +	 * configured with the ``/proc/sys/net/ipv4/ip_local_port_range`` sysctl
> +	 * (also used for IPv6).
> +	 *
> +	 * A Landlock rule with port 0 and the ``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.
>  	 */
>  	__u64 port;
>  };
> @@ -138,10 +139,10 @@ struct landlock_net_port_attr {
>   * The following access rights apply only to files:
>   *
>   * - %LANDLOCK_ACCESS_FS_EXECUTE: Execute a file.
> - * - %LANDLOCK_ACCESS_FS_WRITE_FILE: Open a file with write access. Note that
> - *   you might additionally need the %LANDLOCK_ACCESS_FS_TRUNCATE right in order
> - *   to overwrite files with :manpage:`open(2)` using ``O_TRUNC`` or
> - *   :manpage:`creat(2)`.
> + * - %LANDLOCK_ACCESS_FS_WRITE_FILE: Open a file with write access.  When
> + *   opening files for writing, you will often additionally need the
> + *   %LANDLOCK_ACCESS_FS_TRUNCATE right.  In many cases, these system calls
> + *   truncate existing files when overwriting them (e.g., :manpage:`creat(2)`).
>   * - %LANDLOCK_ACCESS_FS_READ_FILE: Open a file with read access.
>   * - %LANDLOCK_ACCESS_FS_TRUNCATE: Truncate a file with :manpage:`truncate(2)`,
>   *   :manpage:`ftruncate(2)`, :manpage:`creat(2)`, or :manpage:`open(2)` with
> @@ -263,7 +264,7 @@ struct landlock_net_port_attr {
>   * These flags enable to restrict a sandboxed process to a set of network
>   * actions. This is supported since the Landlock ABI version 4.
>   *
> - * TCP sockets with allowed actions:
> + * The following access rights apply to TCP port numbers:
>   *
>   * - %LANDLOCK_ACCESS_NET_BIND_TCP: Bind a TCP socket to a local port.
>   * - %LANDLOCK_ACCESS_NET_CONNECT_TCP: Connect an active TCP socket to
> diff --git a/security/landlock/syscalls.c b/security/landlock/syscalls.c
> index 03b470f5a85a..352c34b327d3 100644
> --- a/security/landlock/syscalls.c
> +++ b/security/landlock/syscalls.c
> @@ -378,8 +378,7 @@ static int add_rule_net_port(struct landlock_ruleset *ruleset,
>   *		with the new rule.
>   * @rule_type: Identify the structure type pointed to by @rule_attr:
>   *             %LANDLOCK_RULE_PATH_BENEATH or %LANDLOCK_RULE_NET_PORT.
> - * @rule_attr: Pointer to a rule (only of type &struct
> - *             landlock_path_beneath_attr for now).
> + * @rule_attr: Pointer to a rule (matching the @rule_type).
>   * @flags: Must be 0.
>   *
>   * This system call enables to define a new rule and add it to an existing
> @@ -390,18 +389,20 @@ static int add_rule_net_port(struct landlock_ruleset *ruleset,
>   * - %EOPNOTSUPP: Landlock is supported by the kernel but disabled at boot time;
>   * - %EAFNOSUPPORT: @rule_type is %LANDLOCK_RULE_NET_PORT but TCP/IP is not
>   *   supported by the running kernel;
> - * - %EINVAL: @flags is not 0, or inconsistent access in the rule (i.e.
> + * - %EINVAL: @flags is not 0;
> + * - %EINVAL: The rule accesses are inconsistent (i.e.
>   *   &landlock_path_beneath_attr.allowed_access or
> - *   &landlock_net_port_attr.allowed_access is not a subset of the
> - *   ruleset handled accesses), or &landlock_net_port_attr.port is
> - *   greater than 65535;
> - * - %ENOMSG: Empty accesses (e.g. &landlock_path_beneath_attr.allowed_access);
> + *   &landlock_net_port_attr.allowed_access is not a subset of the ruleset
> + *   handled accesses)
> + * - %EINVAL: &landlock_net_port_attr.port is greater than 65535;
> + * - %ENOMSG: Empty accesses (e.g. &landlock_path_beneath_attr.allowed_access is
> +      0);
>   * - %EBADF: @ruleset_fd is not a file descriptor for the current thread, or a
>   *   member of @rule_attr is not a file descriptor as expected;
>   * - %EBADFD: @ruleset_fd is not a ruleset file descriptor, or a member of
>   *   @rule_attr is not the expected file descriptor type;
>   * - %EPERM: @ruleset_fd has no write access to the underlying ruleset;
> - * - %EFAULT: @rule_attr inconsistency.
> + * - %EFAULT: @rule_attr was not a valid address.
>   */
>  SYSCALL_DEFINE4(landlock_add_rule, const int, ruleset_fd,
>  		const enum landlock_rule_type, rule_type,
> -- 
> 2.45.2.993.g49e7a77208-goog
> 
>