Unverified Commit f4b89d8c authored by Günther Noack's avatar Günther Noack Committed by Mickaël Salaün
Browse files

landlock: Various documentation improvements 

* 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 [1].

Cc: Alejandro Colomar <alx@kernel.org>
Cc: Konstantin Meskhidze <konstantin.meskhidze@huawei.com>
Link: https://lore.kernel.org/r/20240715155554.2791018-1-gnoack@google.com

 [1]
Signed-off-by: default avatarGünther Noack <gnoack@google.com>
Link: https://lore.kernel.org/r/20240715160328.2792835-2-gnoack@google.com


[mic: Add label to link, fix formatting spotted by make htmldocs,
synchronize userspace-api documentation's date]
Signed-off-by: default avatarMickaël Salaün <mic@digikod.net>
parent 33c97e7c

Documentation/userspace-api/landlock.rst

+1 −1
Original line number Diff line number Diff line
@@ -8,7 +8,7 @@ Landlock: unprivileged access control 
=====================================



:Author: Mickaël Salaün

:Date: April 2024

:Date: July 2024



The goal of Landlock is to enable to restrict ambient rights (e.g. global

filesystem or network access) for a set of processes.  Because Landlock

include/uapi/linux/landlock.h

+14 −13
Original line number Diff line number Diff line
@@ -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

security/landlock/syscalls.c

+9 −8
Original line number Diff line number Diff line
@@ -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,