| Message ID | 20240711165456.2148590-2-gnoack@google.com (mailing list archive) |
|---|---|
| State | Handled Elsewhere |
| Headers | show |
| Series | [v2] landlock: Clarify documentation for struct landlock_ruleset_attr | expand |
On Thu, Jul 11, 2024 at 04:54:57PM +0000, Günther Noack wrote: > 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 <gnoack@google.com> > Cc: Alejandro Colomar <alx@kernel.org> > Cc: Mickaël Salaün <mic@digikod.net> > Cc: Konstantin Meskhidze <konstantin.meskhidze@huawei.com> > Cc: linux-security-module@vger.kernel.org Thanks, applied! > --- > include/uapi/linux/landlock.h | 39 +++++++++++++++++++++-------------- > 1 file changed, 23 insertions(+), 16 deletions(-) > > 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 <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; > }; > -- > 2.45.2.993.g49e7a77208-goog > >
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 <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; };
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 <gnoack@google.com> Cc: Alejandro Colomar <alx@kernel.org> Cc: Mickaël Salaün <mic@digikod.net> Cc: Konstantin Meskhidze <konstantin.meskhidze@huawei.com> Cc: linux-security-module@vger.kernel.org --- include/uapi/linux/landlock.h | 39 +++++++++++++++++++++-------------- 1 file changed, 23 insertions(+), 16 deletions(-)