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

landlock: Clarify documentation for struct landlock_ruleset_attr 



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: default avatarGünther Noack <gnoack@google.com>
Cc: Alejandro Colomar <alx@kernel.org>
Cc: Konstantin Meskhidze <konstantin.meskhidze@huawei.com>
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: default avatarMickaël Salaün <mic@digikod.net>
parent 395a02d0

include/uapi/linux/landlock.h

+23 −16
Original line number Diff line number Diff line
@@ -12,29 +12,36 @@ 
#include <linux/types.h>



/**

 * 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;

};