On 29/10/2020 02:07, Jann Horn wrote: > On Tue, Oct 27, 2020 at 9:04 PM Mickaël Salaün <mic@xxxxxxxxxxx> wrote: >> This documentation can be built with the Sphinx framework. >> >> Cc: James Morris <jmorris@xxxxxxxxx> >> Cc: Jann Horn <jannh@xxxxxxxxxx> >> Cc: Kees Cook <keescook@xxxxxxxxxxxx> >> Cc: Serge E. Hallyn <serge@xxxxxxxxxx> >> Signed-off-by: Mickaël Salaün <mic@xxxxxxxxxxxxxxxxxxx> >> Reviewed-by: Vincent Dagonneau <vincent.dagonneau@xxxxxxxxxxx> > [...] >> 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/ OK. > >> +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? Right, it dates from the landlock_get_features(2), which is now gone but may be replaced by something else in the future. I'll remove that. > > 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? Yes, but I would prefer clear syscall which don't read and write from/to the same argument. I'm working on a more generic solution. It should not be an issue for now. > > [...] >> +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/ OK. > >> +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/ OK. > >> +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/ OK. > > >> +automatically be composed between themselves according to their runtime parent >> +policies.
