OrgACRN
/
acrn-kernel
mirror of https://github.com/projectacrn/acrn-kernel.git
1
0
Fork 0
Code Issues Releases Wiki Activity

landlock: Document LANDLOCK_ACCESS_FS_REFER and ABI versioning 

Add LANDLOCK_ACCESS_FS_REFER in the example and properly check to only
use it if the current kernel support it thanks to the Landlock ABI
version.

Move the file renaming and linking limitation to a new "Previous
limitations" section.

Improve documentation about the backward and forward compatibility,
including the rational for ruleset's handled_access_fs.

Update the document date.

Reviewed-by: Paul Moore <paul@paul-moore.com>
Signed-off-by: Mickaël Salaün <mic@digikod.net>
Link: https://lore.kernel.org/r/20220506161102.525323-11-mic@digikod.net
This commit is contained in:
Mickaël Salaün 2022-05-06 18:11:00 +02:00
parent 76b902f874
commit 6f59abfae3
No known key found for this signature in database
GPG Key ID: E5E3D0E88C82F6D2
1 changed files with 106 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
Documentation/userspace-api/landlock.rst
View File

@ -8,7 +8,7 @@ Landlock: unprivileged access control
=====================================
:Author: Mickaël Salaün
:Date: March 2021
:Date: May 2022
The goal of Landlock is to enable to restrict ambient rights (e.g. global
filesystem access) for a set of processes. Because Landlock is a stackable
@ -29,14 +29,15 @@ 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
We first need to define the ruleset that will contain our rules. For this
example, the ruleset will contain rules that only allow read actions, but write
actions will be denied. The ruleset then needs to handle both of these kind of
actions.
actions. This is required for backward and forward compatibility (i.e. the
kernel and user space may not know each other's supported restrictions), hence
the need to be explicit about the denied-by-default access rights.
.. code-block:: c
int ruleset_fd;
struct landlock_ruleset_attr ruleset_attr = {
.handled_access_fs =
LANDLOCK_ACCESS_FS_EXECUTE |
@ -51,9 +52,34 @@ actions.
LANDLOCK_ACCESS_FS_MAKE_SOCK |
LANDLOCK_ACCESS_FS_MAKE_FIFO |
LANDLOCK_ACCESS_FS_MAKE_BLOCK |
LANDLOCK_ACCESS_FS_MAKE_SYM,
LANDLOCK_ACCESS_FS_MAKE_SYM |
LANDLOCK_ACCESS_FS_REFER,
};
Because we may not know on which kernel version an application will be
executed, it is safer to follow a best-effort security approach. Indeed, we
should try to protect users as much as possible whatever the kernel they are
using. To avoid binary enforcement (i.e. either all security features or
none), we can leverage a dedicated Landlock command to get the current version
of the Landlock ABI and adapt the handled accesses. Let's check if we should
remove the `LANDLOCK_ACCESS_FS_REFER` access right which is only supported
starting with the second version of the ABI.
.. code-block:: c
int abi;
abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION);
if (abi < 2) {
ruleset_attr.handled_access_fs &= ~LANDLOCK_ACCESS_FS_REFER;
}
This enables to create an inclusive ruleset that will contain our rules.
.. code-block:: c
int ruleset_fd;
ruleset_fd = landlock_create_ruleset(&ruleset_attr, sizeof(ruleset_attr), 0);
if (ruleset_fd < 0) {
perror("Failed to create a ruleset");
@ -92,6 +118,11 @@ descriptor.
return 1;
}
It may also be required to create rules following the same logic as explained
for the ruleset creation, by filtering access rights according to the Landlock
ABI version. In this example, this is not required because
`LANDLOCK_ACCESS_FS_REFER` is not allowed by any rule.
We now have a ruleset with one rule allowing read access to ``/usr`` while
denying all other handled accesses for the filesystem. The next step is to
restrict the current thread from gaining more privileges (e.g. thanks to a SUID
@ -192,6 +223,56 @@ To be allowed to use :manpage:`ptrace(2)` and related syscalls on a target
process, a sandboxed process should have a subset of the target process rules,
which means the tracee must be in a sub-domain of the tracer.
Compatibility
=============
Backward and forward compatibility
----------------------------------
Landlock is designed to be compatible with past and future versions of the
kernel. This is achieved thanks to the system call attributes and the
associated bitflags, particularly the ruleset's `handled_access_fs`. Making
handled access right explicit enables the kernel and user space to have a clear
contract with each other. This is required to make sure sandboxing will not
get stricter with a system update, which could break applications.
Developers can subscribe to the `Landlock mailing list
<https://subspace.kernel.org/lists.linux.dev.html>`_ to knowingly update and
test their applications with the latest available features. In the interest of
users, and because they may use different kernel versions, it is strongly
encouraged to follow a best-effort security approach by checking the Landlock
ABI version at runtime and only enforcing the supported features.
Landlock ABI versions
---------------------
The Landlock ABI version can be read with the sys_landlock_create_ruleset()
system call:
.. code-block:: c
int abi;
abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION);
if (abi < 0) {
switch (errno) {
case ENOSYS:
printf("Landlock is not supported by the current kernel.\n");
break;
case EOPNOTSUPP:
printf("Landlock is currently disabled.\n");
break;
}
return 0;
}
if (abi >= 2) {
printf("Landlock supports LANDLOCK_ACCESS_FS_REFER.\n");
}
The following kernel interfaces are implicitly supported by the first ABI
version. Features only supported from a specific version are explicitly marked
as such.
Kernel interface
================
@ -228,21 +309,6 @@ Enforcing a ruleset
Current limitations
===================
File renaming and linking
-------------------------
Because Landlock targets unprivileged access controls, it is needed to properly
handle composition of rules. Such property also implies rules nesting.
Properly handling multiple layers of ruleset, each one of them able to restrict
access to files, also implies to inherit the ruleset restrictions from a parent
to its hierarchy. Because files are identified and restricted by their
hierarchy, moving or linking a file from one directory to another implies to
propagate the hierarchy constraints. To protect against privilege escalations
through renaming or linking, and for the sake of simplicity, Landlock currently
limits linking and renaming to the same directory. Future Landlock evolutions
will enable more flexibility for renaming and linking, with dedicated ruleset
flags.
Filesystem topology modification
--------------------------------
@ -281,6 +347,26 @@ Memory usage
Kernel memory allocated to create rulesets is accounted and can be restricted
by the Documentation/admin-guide/cgroup-v1/memory.rst.
Previous limitations
====================
File renaming and linking (ABI 1)
---------------------------------
Because Landlock targets unprivileged access controls, it needs to properly
handle composition of rules. Such property also implies rules nesting.
Properly handling multiple layers of rulesets, each one of them able to
restrict access to files, also implies inheritance of the ruleset restrictions
from a parent to its hierarchy. Because files are identified and restricted by
their hierarchy, moving or linking a file from one directory to another implies
propagation of the hierarchy constraints, or restriction of these actions
according to the potentially lost constraints. To protect against privilege
escalations through renaming or linking, and for the sake of simplicity,
Landlock previously limited linking and renaming to the same directory.
Starting with the Landlock ABI version 2, it is now possible to securely
control renaming and linking thanks to the new `LANDLOCK_ACCESS_FS_REFER`
access right.
Questions and answers
=====================