Re: [PATCH v27 12/12] landlock: Add user and kernel documentation
On 22/01/2021 09:33, Michael Kerrisk (man-pages) wrote: > Hello Mickaël, Hi Michael, > > It would be great to have some manual pages for these system calls > before release... Can you prepare something? Yes, I will start some pages based on the current documentation, but it will be some time before seeing Landlock in a (stable) release. Could you please take a look at the UAPI (patch 8/12)? > > Thanks, > > Michael > > On Thu, 21 Jan 2021 at 21:51, Mickaël Salaün wrote: >> >> From: Mickaël Salaün >> >> This documentation can be built with the Sphinx framework. >> >> Cc: James Morris >> Cc: Jann Horn >> Cc: Kees Cook >> Cc: Serge E. Hallyn >> Signed-off-by: Mickaël Salaün >> Reviewed-by: Vincent Dagonneau >> --- >> >> Changes since v25: >> * Explain the behavior of layered access rights. >> * Explain how bind mounts and overayfs mounts are handled by Landlock: >> merged overlayfs mount points have their own inodes, which makes these >> hierarchies independent from its upper and lower layers, unlike bind >> mounts which share the same inodes between the source hierarchy and >> the mount point hierarchy. >> New overlayfs mount and bind mount tests check these behaviors. >> * Synchronize with the new syscalls.c file and update syscall names. >> * Fix spelling. >> * Remove Reviewed-by Jann Horn because of the above changes. >> >> Changes since v24: >> * Add Reviewed-by Jann Horn. >> * Add a paragraph to explain how the ruleset layers work. >> * Bump date. >> >> Changes since v23: >> * Explain limitations for the maximum number of stacked ruleset, and the >> memory usage restrictions. >> >> Changes since v22: >> * Fix spelling and remove obsolete sentence (spotted by Jann Horn). >> * Bump date. >> >> Changes since v21: >> * Move the user space documentation to userspace-api/landlock.rst and >> the kernel documentation to security/landlock.rst . >> * Add license headers. >> * Add last update dates. >> * Update MAINTAINERS file. >> * Add (back) links to git.kernel.org . >> * Fix spelling. >> >> Changes since v20: >> * Update examples and documentation with the new syscalls. >> >> Changes since v19: >> * Update examples and documentation with the new syscalls. >> >> Changes since v15: >> * Add current limitations. >> >> Changes since v14: >> * Fix spelling (contributed by Randy Dunlap). >> * Extend documentation about inheritance and explain layer levels. >> * Remove the use of now-removed access rights. >> * Use GitHub links. >> * Improve kernel documentation. >> * Add section for tests. >> * Update example. >> >> Changes since v13: >> * Rewrote the documentation according to the major revamp. >> >> Previous changes: >> https://lore.kernel.org/lkml/20191104172146.30797-8-...@digikod.net/ >> --- >> Documentation/security/index.rst | 1 + >> Documentation/security/landlock.rst | 79 ++ >> Documentation/userspace-api/index.rst| 1 + >> Documentation/userspace-api/landlock.rst | 306 +++ >> MAINTAINERS | 2 + >> 5 files changed, 389 insertions(+) >> create mode 100644 Documentation/security/landlock.rst >> create mode 100644 Documentation/userspace-api/landlock.rst >> >> diff --git a/Documentation/security/index.rst >> b/Documentation/security/index.rst >> index 8129405eb2cc..16335de04e8c 100644 >> --- a/Documentation/security/index.rst >> +++ b/Documentation/security/index.rst >> @@ -16,3 +16,4 @@ Security Documentation >> siphash >> tpm/index >> digsig >> + landlock >> diff --git a/Documentation/security/landlock.rst >> b/Documentation/security/landlock.rst >> new file mode 100644 >> index ..244e616d3d7a >> --- /dev/null >> +++ b/Documentation/security/landlock.rst >> @@ -0,0 +1,79 @@ >> +.. SPDX-License-Identifier: GPL-2.0 >> +.. Copyright © 2017-2020 Mickaël Salaün >> +.. Copyright © 2019-2020 ANSSI >> + >> +== >> +Landlock LSM: kernel documentation >> +== >> + >> +:Author: Mickaël Salaün >> +:Date: January 2021 >> + >> +Landlock's goal is to create scoped access-control (i.e. sandboxing). To >> +harden a whole system, this feature should be available to any process, >> +including unprivileged ones. Because such process may be compromised or >> +backdoored (i.e. untrusted), Landlock's features must be safe to use from >> the >> +kernel and other processes point of view. Landlock's interface must >> therefore >> +expose a minimal attack surface. >> + >> +Landlock is designed to be usable by unprivileged processes while following >> the >> +system security policy enforced by other access control mechanisms (e.g. >> DAC, >> +LSM). Indeed, a Landlock rule shall not interfere with other >> access-controls >> +enforced on the system, only add more restrictions. >> + >> +Any user can enforce Landlock rulesets on their processes. They are merged >> and >> +evaluated according to the inherited ones in a way
Re: [PATCH v27 12/12] landlock: Add user and kernel documentation
Hello Mickaël, It would be great to have some manual pages for these system calls before release... Can you prepare something? Thanks, Michael On Thu, 21 Jan 2021 at 21:51, Mickaël Salaün wrote: > > From: Mickaël Salaün > > This documentation can be built with the Sphinx framework. > > Cc: James Morris > Cc: Jann Horn > Cc: Kees Cook > Cc: Serge E. Hallyn > Signed-off-by: Mickaël Salaün > Reviewed-by: Vincent Dagonneau > --- > > Changes since v25: > * Explain the behavior of layered access rights. > * Explain how bind mounts and overayfs mounts are handled by Landlock: > merged overlayfs mount points have their own inodes, which makes these > hierarchies independent from its upper and lower layers, unlike bind > mounts which share the same inodes between the source hierarchy and > the mount point hierarchy. > New overlayfs mount and bind mount tests check these behaviors. > * Synchronize with the new syscalls.c file and update syscall names. > * Fix spelling. > * Remove Reviewed-by Jann Horn because of the above changes. > > Changes since v24: > * Add Reviewed-by Jann Horn. > * Add a paragraph to explain how the ruleset layers work. > * Bump date. > > Changes since v23: > * Explain limitations for the maximum number of stacked ruleset, and the > memory usage restrictions. > > Changes since v22: > * Fix spelling and remove obsolete sentence (spotted by Jann Horn). > * Bump date. > > Changes since v21: > * Move the user space documentation to userspace-api/landlock.rst and > the kernel documentation to security/landlock.rst . > * Add license headers. > * Add last update dates. > * Update MAINTAINERS file. > * Add (back) links to git.kernel.org . > * Fix spelling. > > Changes since v20: > * Update examples and documentation with the new syscalls. > > Changes since v19: > * Update examples and documentation with the new syscalls. > > Changes since v15: > * Add current limitations. > > Changes since v14: > * Fix spelling (contributed by Randy Dunlap). > * Extend documentation about inheritance and explain layer levels. > * Remove the use of now-removed access rights. > * Use GitHub links. > * Improve kernel documentation. > * Add section for tests. > * Update example. > > Changes since v13: > * Rewrote the documentation according to the major revamp. > > Previous changes: > https://lore.kernel.org/lkml/20191104172146.30797-8-...@digikod.net/ > --- > Documentation/security/index.rst | 1 + > Documentation/security/landlock.rst | 79 ++ > Documentation/userspace-api/index.rst| 1 + > Documentation/userspace-api/landlock.rst | 306 +++ > MAINTAINERS | 2 + > 5 files changed, 389 insertions(+) > create mode 100644 Documentation/security/landlock.rst > create mode 100644 Documentation/userspace-api/landlock.rst > > diff --git a/Documentation/security/index.rst > b/Documentation/security/index.rst > index 8129405eb2cc..16335de04e8c 100644 > --- a/Documentation/security/index.rst > +++ b/Documentation/security/index.rst > @@ -16,3 +16,4 @@ Security Documentation > siphash > tpm/index > digsig > + landlock > diff --git a/Documentation/security/landlock.rst > b/Documentation/security/landlock.rst > new file mode 100644 > index ..244e616d3d7a > --- /dev/null > +++ b/Documentation/security/landlock.rst > @@ -0,0 +1,79 @@ > +.. SPDX-License-Identifier: GPL-2.0 > +.. Copyright © 2017-2020 Mickaël Salaün > +.. Copyright © 2019-2020 ANSSI > + > +== > +Landlock LSM: kernel documentation > +== > + > +:Author: Mickaël Salaün > +:Date: January 2021 > + > +Landlock's goal is to create scoped access-control (i.e. sandboxing). To > +harden a whole system, this feature should be available to any process, > +including unprivileged ones. Because such process may be compromised or > +backdoored (i.e. untrusted), Landlock's features must be safe to use from the > +kernel and other processes point of view. Landlock's interface must > therefore > +expose a minimal attack surface. > + > +Landlock is designed to be usable by unprivileged processes while following > the > +system security policy enforced by other access control mechanisms (e.g. DAC, > +LSM). Indeed, a Landlock rule shall not interfere with other access-controls > +enforced on the system, only add more restrictions. > + > +Any user can enforce Landlock rulesets on their processes. They are merged > and > +evaluated according to the inherited ones in a way that ensures that only > more > +constraints can be added. > + > +User space documentation can be found here: :doc:`/userspace-api/landlock`. > + > +Guiding principles for safe access controls > +=== > + > +* A Landlock rule shall be focused on access control on kernel objects > instead > + of syscall filtering (i.e. syscall arguments), which is the purpose of > + seccomp-bpf. >
