From 33c97e7c0338d921c2ae0c2e54bf17121007fb94 Mon Sep 17 00:00:00 2001 From: Günther Noack Date: Thu, 11 Jul 2024 16:54:57 +0000 Subject: landlock: Clarify documentation for struct landlock_ruleset_attr MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The explanation for @handled_access_fs and @handled_access_net has significant overlap and is better explained together. * Explain the commonalities in structure-level documentation. * Clarify some wording and break up longer sentences. * Put emphasis on the word "handled" to make it clearer that "handled" is a term with special meaning in the context of Landlock. I'd like to transfer this wording into the man pages as well. Signed-off-by: Günther Noack Cc: Alejandro Colomar Cc: Konstantin Meskhidze Cc: linux-security-module@vger.kernel.org Link: https://lore.kernel.org/r/20240711165456.2148590-2-gnoack@google.com [mic: Format commit message] Signed-off-by: Mickaël Salaün --- include/uapi/linux/landlock.h | 39 +++++++++++++++++++++++---------------- 1 file changed, 23 insertions(+), 16 deletions(-) (limited to 'include/uapi') diff --git a/include/uapi/linux/landlock.h b/include/uapi/linux/landlock.h index 68625e728f43..e76186da3260 100644 --- a/include/uapi/linux/landlock.h +++ b/include/uapi/linux/landlock.h @@ -12,29 +12,36 @@ #include /** - * struct landlock_ruleset_attr - Ruleset definition + * struct landlock_ruleset_attr - Ruleset definition. * - * Argument of sys_landlock_create_ruleset(). This structure can grow in - * future versions. + * Argument of sys_landlock_create_ruleset(). + * + * This structure defines a set of *handled access rights*, a set of actions on + * different object types, which should be denied by default when the ruleset is + * enacted. Vice versa, access rights that are not specifically listed here are + * not going to be denied by this ruleset when it is enacted. + * + * For historical reasons, the %LANDLOCK_ACCESS_FS_REFER right is always denied + * by default, even when its bit is not set in @handled_access_fs. In order to + * add new rules with this access right, the bit must still be set explicitly + * (cf. `Filesystem flags`_). + * + * The explicit listing of *handled access rights* is required for backwards + * compatibility reasons. In most use cases, processes that use Landlock will + * *handle* a wide range or all access rights that they know about at build time + * (and that they have tested with a kernel that supported them all). + * + * This structure can grow in future Landlock versions. */ struct landlock_ruleset_attr { /** - * @handled_access_fs: Bitmask of actions (cf. `Filesystem flags`_) - * that is handled by this ruleset and should then be forbidden if no - * rule explicitly allow them: it is a deny-by-default list that should - * contain as much Landlock access rights as possible. Indeed, all - * Landlock filesystem access rights that are not part of - * handled_access_fs are allowed. This is needed for backward - * compatibility reasons. One exception is the - * %LANDLOCK_ACCESS_FS_REFER access right, which is always implicitly - * handled, but must still be explicitly handled to add new rules with - * this access right. + * @handled_access_fs: Bitmask of handled filesystem actions + * (cf. `Filesystem flags`_). */ __u64 handled_access_fs; /** - * @handled_access_net: Bitmask of actions (cf. `Network flags`_) - * that is handled by this ruleset and should then be forbidden if no - * rule explicitly allow them. + * @handled_access_net: Bitmask of handled network actions (cf. `Network + * flags`_). */ __u64 handled_access_net; }; -- cgit v1.2.3 From f4b89d8ce5a835afa51404977ee7e3889c2b9722 Mon Sep 17 00:00:00 2001 From: Günther Noack Date: Mon, 15 Jul 2024 16:03:29 +0000 Subject: landlock: Various documentation improvements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 Cc: Konstantin Meskhidze Link: https://lore.kernel.org/r/20240715155554.2791018-1-gnoack@google.com [1] Signed-off-by: Günther Noack 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: Mickaël Salaün --- Documentation/userspace-api/landlock.rst | 2 +- include/uapi/linux/landlock.h | 27 ++++++++++++++------------- security/landlock/syscalls.c | 17 +++++++++-------- 3 files changed, 24 insertions(+), 22 deletions(-) (limited to 'include/uapi') diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst index 07b63aec56fa..37dafce8038b 100644 --- a/Documentation/userspace-api/landlock.rst +++ b/Documentation/userspace-api/landlock.rst @@ -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 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..ccc8bc6c1584 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, -- cgit v1.2.3