landlock: Various documentation improvements
Subsystems (2)
Günther Noack
reviewerPATCH 1/1 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 (see link below).
--- include/uapi/linux/landlock.h | 27 ++++++++++++++------------- security/landlock/syscalls.c | 17 +++++++++-------- 2 files changed, 23 insertions(+), 21 deletions(-)
include/uapi/linux/landlock.h +14 -13
@@ -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
@@ -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,
Signature · 1 line
2.45.2.993.g49e7a77208-goog
Quoted 12 lines · Günther Noack
* 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. forLANDLOCK_ACCESS_FS_WRITE_FILE).
* Small semantic clarifications
* Call the ephemeral port range "ephemeral"
* Clarify reasons for EFAULT inlandlock_add_rule()
* Clarify @rule_type doc forlandlock_add_rule()
Quoted 8 lines
This is a collection of small fixes which I collected when preparing the corresponding man pages (see link below).
Cc Konstantin Meskhidze <[email protected]>Cc Mickaël Salaün <[email protected]>Cc Alejandro Colomar <[email protected]>Signed-off-by Günther Noack <[email protected]>
Thanks, applied!
Quoted 108 lines
--- include/uapi/linux/landlock.h | 27 ++++++++++++++------------- security/landlock/syscalls.c | 17 +++++++++-------- 2 files changed, 23 insertions(+), 21 deletions(-)include/uapi/linux/landlock.h +14
-13@@ -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@@ -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,Signature · 1 line
2.45.2.993.g49e7a77208-goog