[PATCH v22 12/12] landlock: Add user and kernel documentation

[Jann Horn]

On Tue, Oct 27, 2020 at 9:04 PM Mickaël Salaün <mic at digikod.net> wrote:
> This documentation can be built with the Sphinx framework.
>
> Cc: James Morris <jmorris at namei.org>
> Cc: Jann Horn <jannh at google.com>
> Cc: Kees Cook <keescook at chromium.org>
> Cc: Serge E. Hallyn <serge at hallyn.com>
> Signed-off-by: Mickaël Salaün <mic at linux.microsoft.com>
> Reviewed-by: Vincent Dagonneau <vincent.dagonneau at ssi.gouv.fr>
[...]
> diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
[...]
> +Landlock rules
> +==============
> +
> +A Landlock rule enables to describe an action on an object.  An object is

s/enables to describe/describes/

> +currently a file hierarchy, and the related filesystem actions are defined in
> +`Access rights`_.  A set of rules is aggregated in a ruleset, which can then
> +restrict the thread enforcing it, and its future children.
> +
> +Defining and enforcing a security policy
> +----------------------------------------
> +
> +We first need to create the ruleset that will contain our rules.  For this
> +example, the ruleset will contain rules which only allow read actions, but
> +write actions will be denied.  The ruleset then needs to handle both of these
> +kind of actions.  To have a backward compatibility, these actions should be
> +ANDed with the supported ones.

This sounds as if there is a way for userspace to discover which
actions are supported by the running kernel; but we don't have
anything like that, right?

If we want to make that possible, we could maybe change
sys_landlock_create_ruleset() so that if
ruleset_attr.handled_access_fs contains bits we don't know, we clear
those bits and then copy the struct back to userspace? And then
userspace can retry the syscall with the cleared bits? Or something
along those lines?

[...]
> +We can now add a new rule to this ruleset thanks to the returned file
> +descriptor referring to this ruleset.  The rule will only enable to read the

s/enable to read/allow reading/

> +file hierarchy ``/usr``.  Without another rule, write actions would then be
> +denied by the ruleset.  To add ``/usr`` to the ruleset, we open it with the
> +``O_PATH`` flag and fill the &struct landlock_path_beneath_attr with this file
> +descriptor.
[...]
> +Inheritance
> +-----------
> +
> +Every new thread resulting from a :manpage:`clone(2)` inherits Landlock domain
> +restrictions from its parent.  This is similar to the seccomp inheritance (cf.
> +:doc:`/userspace-api/seccomp_filter`) or any other LSM dealing with task's
> +:manpage:`credentials(7)`.  For instance, one process's thread may apply
> +Landlock rules to itself, but they will not be automatically applied to other
> +sibling threads (unlike POSIX thread credential changes, cf.
> +:manpage:`nptl(7)`).
> +
> +When a thread sandbox itself, we have the grantee that the related security

s/sandbox/sandboxes/
s/grantee/guarantee/

> +policy will stay enforced on all this thread's descendants.  This enables to
> +create standalone and modular security policies per application, which will

s/enables to create/allows creating/


> +automatically be composed between themselves according to their runtime parent
> +policies.