From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Cyrus-Session-Id: sloti22d1t05-40595-1519692537-2-4876496910664460174 X-Sieve: CMU Sieve 3.0 X-Spam-known-sender: no X-Spam-score: 0.0 X-Spam-hits: BAYES_00 -1.9, HEADER_FROM_DIFFERENT_DOMAINS 0.249, ME_NOAUTH 0.01, RCVD_IN_DNSWL_HI -5, T_RP_MATCHES_RCVD -0.01, LANGUAGES en, BAYES_USED global, SA_VERSION 3.4.0 X-Spam-source: IP='209.132.180.67', Host='vger.kernel.org', Country='CN', FromHeader='net', MailFrom='org' X-Spam-charsets: from='UTF-8', cc='UTF-8', plain='UTF-8' X-Resolved-to: greg@kroah.com X-Delivered-to: greg@kroah.com X-Mail-from: linux-api-owner@vger.kernel.org ARC-Seal: i=1; a=rsa-sha256; cv=none; d=messagingengine.com; s=arctest; t=1519692536; b=ZAdHUu4Tj+SRCD7jgt/ZkfYIMYBDpv4azrWfUvWlpVDrnTq GChQ3gRFt5ixH7edRdx1D0or11mUnuXWAgBL/C2M+8gvuMpMy4evabkzvf7fohUA KzSBTg08U2joh5GHNEPKNI2T+qNHoJMCGFQAk4lb35/srxVUARcDMRNITZrgSjLn NC4FP9NjAq18aPi5fHvXfdAcbgEf8FlvwDcOOFseXKLgWCLCFijKs102KvHHaPhC 1G/Hvzr5gkrOU7BidguFmQFPggkddzft1FHOciwOQsuiVzdqhhmnqFUlaIYMDD/e 9Yz7VGXAIRIslHd5eR4jq3CaIdHSZi74EWsDnBw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-type :content-transfer-encoding:sender:list-id; s=arctest; t= 1519692536; bh=wvbFOhEKpkD34CTOSrvJpR3OIh5OvqenCfAbt8zVE6w=; b=s Rrv5L9yuh7xjO0fK6kMdlqIDbIxFPl1gV8oFzpx/s2+7LECNL7xV8Bcwc64bdcHQ ADLZZwOybOGvLzxBuiAQUxPNYoj7PgHdRq2QTJaBgcCg4KEhz9EcorMxL+jA5n57 SQrZzjSN2pSfMXNXuSmhpHCxvpTACm8QX6BuFNKJwbEKQ7JMGxaaini5vKu1/ZDN MNppVPhXZzwcViKb4fa5MZPYWUTici4q5w0rsddL+HpvivicC5ly31QqOVJVqCZ4 ys9LlbIsCmoMVs7RYlnFezC4orkAM2mf64N1eSqY5MbDv5GpRwc69zLWE17UgiRP k+KJeDkekqqCqd+FfU6eA== ARC-Authentication-Results: i=1; mx2.messagingengine.com; arc=none (no signatures found); dkim=none (no signatures found); dmarc=none (p=none,has-list-id=yes,d=none) header.from=digikod.net; iprev=pass policy.iprev=209.132.180.67 (vger.kernel.org); spf=none smtp.mailfrom=linux-api-owner@vger.kernel.org smtp.helo=vger.kernel.org; x-aligned-from=fail; x-ptr=pass x-ptr-helo=vger.kernel.org x-ptr-lookup=vger.kernel.org; x-return-mx=pass smtp.domain=vger.kernel.org smtp.result=pass smtp_org.domain=kernel.org smtp_org.result=pass smtp_is_org_domain=no header.domain=digikod.net header.result=pass header_is_org_domain=yes Authentication-Results: mx2.messagingengine.com; arc=none (no signatures found); dkim=none (no signatures found); dmarc=none (p=none,has-list-id=yes,d=none) header.from=digikod.net; iprev=pass policy.iprev=209.132.180.67 (vger.kernel.org); spf=none smtp.mailfrom=linux-api-owner@vger.kernel.org smtp.helo=vger.kernel.org; x-aligned-from=fail; x-ptr=pass x-ptr-helo=vger.kernel.org x-ptr-lookup=vger.kernel.org; x-return-mx=pass smtp.domain=vger.kernel.org smtp.result=pass smtp_org.domain=kernel.org smtp_org.result=pass smtp_is_org_domain=no header.domain=digikod.net header.result=pass header_is_org_domain=yes Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751510AbeB0Asz (ORCPT ); Mon, 26 Feb 2018 19:48:55 -0500 Received: from smtp-sh.infomaniak.ch ([128.65.195.4]:35399 "EHLO smtp-sh.infomaniak.ch" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750941AbeB0Asy (ORCPT ); Mon, 26 Feb 2018 19:48:54 -0500 From: =?UTF-8?q?Micka=C3=ABl=20Sala=C3=BCn?= To: linux-kernel@vger.kernel.org Cc: =?UTF-8?q?Micka=C3=ABl=20Sala=C3=BCn?= , Alexei Starovoitov , Andy Lutomirski , Arnaldo Carvalho de Melo , Casey Schaufler , Daniel Borkmann , David Drysdale , "David S . Miller" , "Eric W . Biederman" , James Morris , Jann Horn , Jonathan Corbet , Michael Kerrisk , Kees Cook , Paul Moore , Sargun Dhillon , "Serge E . Hallyn" , Shuah Khan , Tejun Heo , Thomas Graf , Tycho Andersen , Will Drewry , kernel-hardening@lists.openwall.com, linux-api@vger.kernel.org, linux-security-module@vger.kernel.org, netdev@vger.kernel.org Subject: [PATCH bpf-next v8 11/11] landlock: Add user and kernel documentation for Landlock Date: Tue, 27 Feb 2018 01:41:21 +0100 Message-Id: <20180227004121.3633-12-mic@digikod.net> X-Mailer: git-send-email 2.16.2 In-Reply-To: <20180227004121.3633-1-mic@digikod.net> References: <20180227004121.3633-1-mic@digikod.net> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Antivirus-Code: 0x100000 Sender: linux-api-owner@vger.kernel.org X-Mailing-List: linux-api@vger.kernel.org X-getmail-retrieved-from-mailbox: INBOX X-Mailing-List: linux-kernel@vger.kernel.org List-ID: This documentation can be built with the Sphinx framework. Signed-off-by: Mickaël Salaün Cc: Alexei Starovoitov Cc: Andy Lutomirski Cc: Daniel Borkmann Cc: David S. Miller Cc: James Morris Cc: Jonathan Corbet Cc: Kees Cook Cc: Serge E. Hallyn --- Changes since v7: * update documentation according to the Landlock revamp Changes since v6: * add a check for ctx->event * rename BPF_PROG_TYPE_LANDLOCK to BPF_PROG_TYPE_LANDLOCK_RULE * rename Landlock version to ABI to better reflect its purpose and add a dedicated changelog section * update tables * relax no_new_privs recommendations * remove ABILITY_WRITE related functions * reword rule "appending" to "prepending" and explain it * cosmetic fixes Changes since v5: * update the rule hierarchy inheritance explanation * briefly explain ctx->arg2 * add ptrace restrictions * explain EPERM * update example (subtype) * use ":manpage:" --- Documentation/security/index.rst | 1 + Documentation/security/landlock/index.rst | 19 +++ Documentation/security/landlock/kernel.rst | 100 ++++++++++++++ Documentation/security/landlock/user.rst | 206 +++++++++++++++++++++++++++++ 4 files changed, 326 insertions(+) create mode 100644 Documentation/security/landlock/index.rst create mode 100644 Documentation/security/landlock/kernel.rst create mode 100644 Documentation/security/landlock/user.rst diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst index 298a94a33f05..1db294025d0f 100644 --- a/Documentation/security/index.rst +++ b/Documentation/security/index.rst @@ -11,3 +11,4 @@ Security Documentation LSM self-protection tpm/index + landlock/index diff --git a/Documentation/security/landlock/index.rst b/Documentation/security/landlock/index.rst new file mode 100644 index 000000000000..8afde6a5805c --- /dev/null +++ b/Documentation/security/landlock/index.rst @@ -0,0 +1,19 @@ +========================================= +Landlock LSM: programmatic access control +========================================= + +Landlock is a stackable Linux Security Module (LSM) that makes it possible to +create security sandboxes. This kind of sandbox is expected to help mitigate +the security impact of bugs or unexpected/malicious behaviors in user-space +applications. The current version allows only a process with the global +CAP_SYS_ADMIN capability to create such sandboxes but the ultimate goal of +Landlock is to empower any process, including unprivileged ones, to securely +restrict themselves. Landlock is inspired by seccomp-bpf but instead of +filtering syscalls and their raw arguments, a Landlock rule can inspect the use +of kernel objects like files and hence make a decision according to the kernel +semantic. + +.. toctree:: + + user + kernel diff --git a/Documentation/security/landlock/kernel.rst b/Documentation/security/landlock/kernel.rst new file mode 100644 index 000000000000..0a52915e346c --- /dev/null +++ b/Documentation/security/landlock/kernel.rst @@ -0,0 +1,100 @@ +============================== +Landlock: kernel documentation +============================== + +eBPF properties +=============== + +To get an expressive language while still being safe and small, Landlock is +based on eBPF. Landlock should be usable by untrusted processes and must +therefore expose a minimal attack surface. The eBPF bytecode is minimal, +powerful, widely used and designed to be used by untrusted applications. Thus, +reusing the eBPF support in the kernel enables a generic approach while +minimizing new code. + +An eBPF program has access to an eBPF context containing some fields used to +inspect the current object. These arguments can be used directly (e.g. cookie) +or passed to helper functions according to their types (e.g. inode pointer). It +is then possible to do complex access checks without race conditions or +inconsistent evaluation (i.e. `incorrect mirroring of the OS code and state +`_). + +A Landlock hook describes a particular access type. For now, there is three +hooks dedicated to filesystem related operations: LANDLOCK_HOOK_FS_PICK, +LANDLOCK_HOOK_FS_WALK and LANDLOCK_HOOK_FS_GET. A Landlock program is tied to +one hook. This makes it possible to statically check context accesses, +potentially performed by such program, and hence prevents kernel address leaks +and ensure the right use of hook arguments with eBPF functions. Any user can +add multiple Landlock programs per Landlock hook. They are stacked and +evaluated one after the other, starting from the most recent program, as +seccomp-bpf does with its filters. Underneath, a hook is an abstraction over a +set of LSM hooks. + + +Guiding principles +================== + +Unprivileged use +---------------- + +* Landlock helpers and context should be usable by any unprivileged and + untrusted program while following the system security policy enforced by + other access control mechanisms (e.g. DAC, LSM). + + +Landlock hook and context +------------------------- + +* A Landlock hook shall be focused on access control on kernel objects instead + of syscall filtering (i.e. syscall arguments), which is the purpose of + seccomp-bpf. +* A Landlock context provided by a hook shall express the minimal and more + generic interface to control an access for a kernel object. +* A hook shall guaranty that all the BPF function calls from a program are + safe. Thus, the related Landlock context arguments shall always be of the + same type for a particular hook. For example, a network hook could share + helpers with a file hook because of UNIX socket. However, the same helpers + may not be compatible for a FS handle and a net handle. +* Multiple hooks may use the same context interface. + + +Landlock helpers +---------------- + +* Landlock helpers shall be as generic as possible while at the same time being + as simple as possible and following the syscall creation principles (cf. + *Documentation/adding-syscalls.txt*). +* The only behavior change allowed on a helper is to fix a (logical) bug to + match the initial semantic. +* Helpers shall be reentrant, i.e. only take inputs from arguments (e.g. from + the BPF context), to enable a hook to use a cache. Future program options + might change this cache behavior. +* It is quite easy to add new helpers to extend Landlock. The main concern + should be about the possibility to leak information from the kernel that may + not be accessible otherwise (i.e. side-channel attack). + + +Questions and answers +===================== + +Why not create a custom hook for each kind of action? +----------------------------------------------------- + +Landlock programs can handle these checks. Adding more exceptions to the +kernel code would lead to more code complexity. A decision to ignore a kind of +action can and should be done at the beginning of a Landlock program. + + +Why a program does not return an errno or a kill code? +------------------------------------------------------ + +seccomp filters can return multiple kind of code, including an errno value or a +kill signal, which may be convenient for access control. Those return codes +are hardwired in the userland ABI. Instead, Landlock's approach is to return a +boolean to allow or deny an action, which is much simpler and more generic. +Moreover, we do not really have a choice because, unlike to seccomp, Landlock +programs are not enforced at the syscall entry point but may be executed at any +point in the kernel (through LSM hooks) where an errno return code may not make +sense. However, with this simple ABI and with the ability to call helpers, +Landlock may gain features similar to seccomp-bpf in the future while being +compatible with previous programs. diff --git a/Documentation/security/landlock/user.rst b/Documentation/security/landlock/user.rst new file mode 100644 index 000000000000..3130063c9087 --- /dev/null +++ b/Documentation/security/landlock/user.rst @@ -0,0 +1,206 @@ +================================ +Landlock: userland documentation +================================ + +Landlock programs +================= + +eBPF programs are used to create security programs. They are contained and can +call only a whitelist of dedicated functions. Moreover, they cannot loop, which +protects from denial of service. More information on BPF can be found in +*Documentation/networking/filter.txt*. + + +Writing a program +----------------- + +To enforce a security policy, a thread first needs to create a Landlock program. +The easiest way to write an eBPF program depicting a security program is to write +it in the C language. As described in *samples/bpf/README.rst*, LLVM can +compile such programs. Files *samples/bpf/landlock1_kern.c* and those in +*tools/testing/selftests/landlock/* can be used as examples. + +Once the eBPF program is created, the next step is to create the metadata +describing the Landlock program. This metadata includes a subtype which +contains the hook type to which the program is tied and some options. + +.. code-block:: c + + union bpf_prog_subtype subtype = { + .landlock_hook = { + .type = LANDLOCK_HOOK_FS_PICK, + .triggers = LANDLOCK_TRIGGER_FS_PICK_OPEN, + } + }; + +A Landlock hook describes the kind of kernel object for which a program will be +triggered to allow or deny an action. For example, the hook +LANDLOCK_HOOK_FS_PICK can be triggered every time a landlocked thread performs +a set of action related to the filesystem (e.g. open, read, write, mount...). +This actions are identified by the `triggers` bitfield. + +The next step is to fill a :c:type:`union bpf_attr ` with +BPF_PROG_TYPE_LANDLOCK_HOOK, the previously created subtype and other BPF +program metadata. This bpf_attr must then be passed to the :manpage:`bpf(2)` +syscall alongside the BPF_PROG_LOAD command. If everything is deemed correct +by the kernel, the thread gets a file descriptor referring to this program. + +In the following code, the *insn* variable is an array of BPF instructions +which can be extracted from an ELF file as is done in bpf_load_file() from +*samples/bpf/bpf_load.c*. + +.. code-block:: c + + union bpf_attr attr = { + .prog_type = BPF_PROG_TYPE_LANDLOCK_HOOK, + .insn_cnt = sizeof(insn) / sizeof(struct bpf_insn), + .insns = (__u64) (unsigned long) insn, + .license = (__u64) (unsigned long) "GPL", + .prog_subtype = &subtype, + .prog_subtype_size = sizeof(subtype), + }; + int fd = bpf(BPF_PROG_LOAD, &attr, sizeof(attr)); + if (fd == -1) + exit(1); + + +Enforcing a program +------------------- + +Once the Landlock program has been created or received (e.g. through a UNIX +socket), the thread willing to sandbox itself (and its future children) should +perform the following two steps. + +The thread should first request to never be allowed to get new privileges with a +call to :manpage:`prctl(2)` and the PR_SET_NO_NEW_PRIVS option. More +information can be found in *Documentation/prctl/no_new_privs.txt*. + +.. code-block:: c + + if (prctl(PR_SET_NO_NEW_PRIVS, 1, NULL, 0, 0)) + exit(1); + +A thread can apply a program to itself by using the :manpage:`seccomp(2)` syscall. +The operation is SECCOMP_PREPEND_LANDLOCK_PROG, the flags must be empty and the +*args* argument must point to a valid Landlock program file descriptor. + +.. code-block:: c + + if (seccomp(SECCOMP_PREPEND_LANDLOCK_PROG, 0, &fd)) + exit(1); + +If the syscall succeeds, the program is now enforced on the calling thread and +will be enforced on all its subsequently created children of the thread as +well. Once a thread is landlocked, there is no way to remove this security +policy, only stacking more restrictions is allowed. The program evaluation is +performed from the newest to the oldest. + +When a syscall ask for an action on a kernel object, if this action is denied, +then an EACCES errno code is returned through the syscall. + + +.. _inherited_programs: + +Inherited programs +------------------ + +Every new thread resulting from a :manpage:`clone(2)` inherits Landlock program +restrictions from its parent. This is similar to the seccomp inheritance as +described in *Documentation/prctl/seccomp_filter.txt*. + + +Ptrace restrictions +------------------- + +A landlocked process has less privileges than a non-landlocked process and must +then be subject to additional restrictions when manipulating another process. +To be allowed to use :manpage:`ptrace(2)` and related syscalls on a target +process, a landlocked process must have a subset of the target process programs. + + +Chained programs +================ + +Landlock programs can be chained according to the hook they are tied to. This +enable to keep a state between multiple program evaluation for an object access +check (e.g. walking through a file path). The *cookie* field from the context +can be used as a temporary storage shared between a chain of programs. + +The following graph is an example of the chain of programs used in +*samples/bpf/landlock1_kern.c*. The fs_walk program evaluate if a file is +beneath a set of file hierarchy. The first fs_pick program may be called when +there is a read-like action (i.e. trigger for open, chdir, getattr...). The +second fs_pick program may be called for write-like actions. And finally, the +fs_get program is called to tag a file when it is open, receive or when the +current task changes directory. This tagging is needed to be able to keep the +state of this file evaluation for a next one involving the same opened file. + +:: + + .---------. + | fs_walk | + '---------' + | + v + .---------. + | fs_pick | open, chdir, getattr... + '---------' + | + v + .---------. + | fs_pick | create, write, link... + '---------' + | + v + .--------. + | fs_get | + '--------' + + +Landlock structures and constants +================================= + +Hook types +---------- + +.. kernel-doc:: include/uapi/linux/landlock.h + :functions: landlock_hook_type + + +Contexts +-------- + +.. kernel-doc:: include/uapi/linux/landlock.h + :functions: landlock_ctx_fs_pick landlock_ctx_fs_walk landlock_ctx_fs_get + + +Triggers for fs_pick +-------------------- + +.. kernel-doc:: include/uapi/linux/landlock.h + :functions: landlock_triggers + + +Helper functions +---------------- + +:: + + u64 bpf_inode_get_tag(inode, chain) + @inode: pointer to struct inode + @chain: pointer to struct landlock_chain + Return: tag tied to this inode and chain, or zero if none + + int bpf_landlock_set_tag(tag_obj, chain, value) + @tag_obj: pointer pointing to a taggable object (e.g. inode) + @chain: pointer to struct landlock_chain + @value: value of the tag + Return: 0 on success or negative error code + +See *include/uapi/linux/bpf.h* for other functions documentation. + + +Additional documentation +======================== + +See https://landlock.io -- 2.16.2 From mboxrd@z Thu Jan 1 00:00:00 1970 From: =?UTF-8?q?Micka=C3=ABl=20Sala=C3=BCn?= Subject: [PATCH bpf-next v8 11/11] landlock: Add user and kernel documentation for Landlock Date: Tue, 27 Feb 2018 01:41:21 +0100 Message-ID: <20180227004121.3633-12-mic@digikod.net> References: <20180227004121.3633-1-mic@digikod.net> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: =?UTF-8?q?Micka=C3=ABl=20Sala=C3=BCn?= , Alexei Starovoitov , Andy Lutomirski , Arnaldo Carvalho de Melo , Casey Schaufler , Daniel Borkmann , David Drysdale , "David S . Miller" , "Eric W . Biederman" , James Morris , Jann Horn , Jonathan Corbet , Michael Kerrisk , Kees Cook , Paul Moore , Sargun Dhillon , "Serge E . Hallyn" , Shuah Khan , Tejun Heo , Thomas Graf To: linux-kernel@vger.kernel.org Return-path: In-Reply-To: <20180227004121.3633-1-mic@digikod.net> Sender: linux-kernel-owner@vger.kernel.org List-Id: netdev.vger.kernel.org This documentation can be built with the Sphinx framework. Signed-off-by: Mickaël Salaün Cc: Alexei Starovoitov Cc: Andy Lutomirski Cc: Daniel Borkmann Cc: David S. Miller Cc: James Morris Cc: Jonathan Corbet Cc: Kees Cook Cc: Serge E. Hallyn --- Changes since v7: * update documentation according to the Landlock revamp Changes since v6: * add a check for ctx->event * rename BPF_PROG_TYPE_LANDLOCK to BPF_PROG_TYPE_LANDLOCK_RULE * rename Landlock version to ABI to better reflect its purpose and add a dedicated changelog section * update tables * relax no_new_privs recommendations * remove ABILITY_WRITE related functions * reword rule "appending" to "prepending" and explain it * cosmetic fixes Changes since v5: * update the rule hierarchy inheritance explanation * briefly explain ctx->arg2 * add ptrace restrictions * explain EPERM * update example (subtype) * use ":manpage:" --- Documentation/security/index.rst | 1 + Documentation/security/landlock/index.rst | 19 +++ Documentation/security/landlock/kernel.rst | 100 ++++++++++++++ Documentation/security/landlock/user.rst | 206 +++++++++++++++++++++++++++++ 4 files changed, 326 insertions(+) create mode 100644 Documentation/security/landlock/index.rst create mode 100644 Documentation/security/landlock/kernel.rst create mode 100644 Documentation/security/landlock/user.rst diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst index 298a94a33f05..1db294025d0f 100644 --- a/Documentation/security/index.rst +++ b/Documentation/security/index.rst @@ -11,3 +11,4 @@ Security Documentation LSM self-protection tpm/index + landlock/index diff --git a/Documentation/security/landlock/index.rst b/Documentation/security/landlock/index.rst new file mode 100644 index 000000000000..8afde6a5805c --- /dev/null +++ b/Documentation/security/landlock/index.rst @@ -0,0 +1,19 @@ +========================================= +Landlock LSM: programmatic access control +========================================= + +Landlock is a stackable Linux Security Module (LSM) that makes it possible to +create security sandboxes. This kind of sandbox is expected to help mitigate +the security impact of bugs or unexpected/malicious behaviors in user-space +applications. The current version allows only a process with the global +CAP_SYS_ADMIN capability to create such sandboxes but the ultimate goal of +Landlock is to empower any process, including unprivileged ones, to securely +restrict themselves. Landlock is inspired by seccomp-bpf but instead of +filtering syscalls and their raw arguments, a Landlock rule can inspect the use +of kernel objects like files and hence make a decision according to the kernel +semantic. + +.. toctree:: + + user + kernel diff --git a/Documentation/security/landlock/kernel.rst b/Documentation/security/landlock/kernel.rst new file mode 100644 index 000000000000..0a52915e346c --- /dev/null +++ b/Documentation/security/landlock/kernel.rst @@ -0,0 +1,100 @@ +============================== +Landlock: kernel documentation +============================== + +eBPF properties +=============== + +To get an expressive language while still being safe and small, Landlock is +based on eBPF. Landlock should be usable by untrusted processes and must +therefore expose a minimal attack surface. The eBPF bytecode is minimal, +powerful, widely used and designed to be used by untrusted applications. Thus, +reusing the eBPF support in the kernel enables a generic approach while +minimizing new code. + +An eBPF program has access to an eBPF context containing some fields used to +inspect the current object. These arguments can be used directly (e.g. cookie) +or passed to helper functions according to their types (e.g. inode pointer). It +is then possible to do complex access checks without race conditions or +inconsistent evaluation (i.e. `incorrect mirroring of the OS code and state +`_). + +A Landlock hook describes a particular access type. For now, there is three +hooks dedicated to filesystem related operations: LANDLOCK_HOOK_FS_PICK, +LANDLOCK_HOOK_FS_WALK and LANDLOCK_HOOK_FS_GET. A Landlock program is tied to +one hook. This makes it possible to statically check context accesses, +potentially performed by such program, and hence prevents kernel address leaks +and ensure the right use of hook arguments with eBPF functions. Any user can +add multiple Landlock programs per Landlock hook. They are stacked and +evaluated one after the other, starting from the most recent program, as +seccomp-bpf does with its filters. Underneath, a hook is an abstraction over a +set of LSM hooks. + + +Guiding principles +================== + +Unprivileged use +---------------- + +* Landlock helpers and context should be usable by any unprivileged and + untrusted program while following the system security policy enforced by + other access control mechanisms (e.g. DAC, LSM). + + +Landlock hook and context +------------------------- + +* A Landlock hook shall be focused on access control on kernel objects instead + of syscall filtering (i.e. syscall arguments), which is the purpose of + seccomp-bpf. +* A Landlock context provided by a hook shall express the minimal and more + generic interface to control an access for a kernel object. +* A hook shall guaranty that all the BPF function calls from a program are + safe. Thus, the related Landlock context arguments shall always be of the + same type for a particular hook. For example, a network hook could share + helpers with a file hook because of UNIX socket. However, the same helpers + may not be compatible for a FS handle and a net handle. +* Multiple hooks may use the same context interface. + + +Landlock helpers +---------------- + +* Landlock helpers shall be as generic as possible while at the same time being + as simple as possible and following the syscall creation principles (cf. + *Documentation/adding-syscalls.txt*). +* The only behavior change allowed on a helper is to fix a (logical) bug to + match the initial semantic. +* Helpers shall be reentrant, i.e. only take inputs from arguments (e.g. from + the BPF context), to enable a hook to use a cache. Future program options + might change this cache behavior. +* It is quite easy to add new helpers to extend Landlock. The main concern + should be about the possibility to leak information from the kernel that may + not be accessible otherwise (i.e. side-channel attack). + + +Questions and answers +===================== + +Why not create a custom hook for each kind of action? +----------------------------------------------------- + +Landlock programs can handle these checks. Adding more exceptions to the +kernel code would lead to more code complexity. A decision to ignore a kind of +action can and should be done at the beginning of a Landlock program. + + +Why a program does not return an errno or a kill code? +------------------------------------------------------ + +seccomp filters can return multiple kind of code, including an errno value or a +kill signal, which may be convenient for access control. Those return codes +are hardwired in the userland ABI. Instead, Landlock's approach is to return a +boolean to allow or deny an action, which is much simpler and more generic. +Moreover, we do not really have a choice because, unlike to seccomp, Landlock +programs are not enforced at the syscall entry point but may be executed at any +point in the kernel (through LSM hooks) where an errno return code may not make +sense. However, with this simple ABI and with the ability to call helpers, +Landlock may gain features similar to seccomp-bpf in the future while being +compatible with previous programs. diff --git a/Documentation/security/landlock/user.rst b/Documentation/security/landlock/user.rst new file mode 100644 index 000000000000..3130063c9087 --- /dev/null +++ b/Documentation/security/landlock/user.rst @@ -0,0 +1,206 @@ +================================ +Landlock: userland documentation +================================ + +Landlock programs +================= + +eBPF programs are used to create security programs. They are contained and can +call only a whitelist of dedicated functions. Moreover, they cannot loop, which +protects from denial of service. More information on BPF can be found in +*Documentation/networking/filter.txt*. + + +Writing a program +----------------- + +To enforce a security policy, a thread first needs to create a Landlock program. +The easiest way to write an eBPF program depicting a security program is to write +it in the C language. As described in *samples/bpf/README.rst*, LLVM can +compile such programs. Files *samples/bpf/landlock1_kern.c* and those in +*tools/testing/selftests/landlock/* can be used as examples. + +Once the eBPF program is created, the next step is to create the metadata +describing the Landlock program. This metadata includes a subtype which +contains the hook type to which the program is tied and some options. + +.. code-block:: c + + union bpf_prog_subtype subtype = { + .landlock_hook = { + .type = LANDLOCK_HOOK_FS_PICK, + .triggers = LANDLOCK_TRIGGER_FS_PICK_OPEN, + } + }; + +A Landlock hook describes the kind of kernel object for which a program will be +triggered to allow or deny an action. For example, the hook +LANDLOCK_HOOK_FS_PICK can be triggered every time a landlocked thread performs +a set of action related to the filesystem (e.g. open, read, write, mount...). +This actions are identified by the `triggers` bitfield. + +The next step is to fill a :c:type:`union bpf_attr ` with +BPF_PROG_TYPE_LANDLOCK_HOOK, the previously created subtype and other BPF +program metadata. This bpf_attr must then be passed to the :manpage:`bpf(2)` +syscall alongside the BPF_PROG_LOAD command. If everything is deemed correct +by the kernel, the thread gets a file descriptor referring to this program. + +In the following code, the *insn* variable is an array of BPF instructions +which can be extracted from an ELF file as is done in bpf_load_file() from +*samples/bpf/bpf_load.c*. + +.. code-block:: c + + union bpf_attr attr = { + .prog_type = BPF_PROG_TYPE_LANDLOCK_HOOK, + .insn_cnt = sizeof(insn) / sizeof(struct bpf_insn), + .insns = (__u64) (unsigned long) insn, + .license = (__u64) (unsigned long) "GPL", + .prog_subtype = &subtype, + .prog_subtype_size = sizeof(subtype), + }; + int fd = bpf(BPF_PROG_LOAD, &attr, sizeof(attr)); + if (fd == -1) + exit(1); + + +Enforcing a program +------------------- + +Once the Landlock program has been created or received (e.g. through a UNIX +socket), the thread willing to sandbox itself (and its future children) should +perform the following two steps. + +The thread should first request to never be allowed to get new privileges with a +call to :manpage:`prctl(2)` and the PR_SET_NO_NEW_PRIVS option. More +information can be found in *Documentation/prctl/no_new_privs.txt*. + +.. code-block:: c + + if (prctl(PR_SET_NO_NEW_PRIVS, 1, NULL, 0, 0)) + exit(1); + +A thread can apply a program to itself by using the :manpage:`seccomp(2)` syscall. +The operation is SECCOMP_PREPEND_LANDLOCK_PROG, the flags must be empty and the +*args* argument must point to a valid Landlock program file descriptor. + +.. code-block:: c + + if (seccomp(SECCOMP_PREPEND_LANDLOCK_PROG, 0, &fd)) + exit(1); + +If the syscall succeeds, the program is now enforced on the calling thread and +will be enforced on all its subsequently created children of the thread as +well. Once a thread is landlocked, there is no way to remove this security +policy, only stacking more restrictions is allowed. The program evaluation is +performed from the newest to the oldest. + +When a syscall ask for an action on a kernel object, if this action is denied, +then an EACCES errno code is returned through the syscall. + + +.. _inherited_programs: + +Inherited programs +------------------ + +Every new thread resulting from a :manpage:`clone(2)` inherits Landlock program +restrictions from its parent. This is similar to the seccomp inheritance as +described in *Documentation/prctl/seccomp_filter.txt*. + + +Ptrace restrictions +------------------- + +A landlocked process has less privileges than a non-landlocked process and must +then be subject to additional restrictions when manipulating another process. +To be allowed to use :manpage:`ptrace(2)` and related syscalls on a target +process, a landlocked process must have a subset of the target process programs. + + +Chained programs +================ + +Landlock programs can be chained according to the hook they are tied to. This +enable to keep a state between multiple program evaluation for an object access +check (e.g. walking through a file path). The *cookie* field from the context +can be used as a temporary storage shared between a chain of programs. + +The following graph is an example of the chain of programs used in +*samples/bpf/landlock1_kern.c*. The fs_walk program evaluate if a file is +beneath a set of file hierarchy. The first fs_pick program may be called when +there is a read-like action (i.e. trigger for open, chdir, getattr...). The +second fs_pick program may be called for write-like actions. And finally, the +fs_get program is called to tag a file when it is open, receive or when the +current task changes directory. This tagging is needed to be able to keep the +state of this file evaluation for a next one involving the same opened file. + +:: + + .---------. + | fs_walk | + '---------' + | + v + .---------. + | fs_pick | open, chdir, getattr... + '---------' + | + v + .---------. + | fs_pick | create, write, link... + '---------' + | + v + .--------. + | fs_get | + '--------' + + +Landlock structures and constants +================================= + +Hook types +---------- + +.. kernel-doc:: include/uapi/linux/landlock.h + :functions: landlock_hook_type + + +Contexts +-------- + +.. kernel-doc:: include/uapi/linux/landlock.h + :functions: landlock_ctx_fs_pick landlock_ctx_fs_walk landlock_ctx_fs_get + + +Triggers for fs_pick +-------------------- + +.. kernel-doc:: include/uapi/linux/landlock.h + :functions: landlock_triggers + + +Helper functions +---------------- + +:: + + u64 bpf_inode_get_tag(inode, chain) + @inode: pointer to struct inode + @chain: pointer to struct landlock_chain + Return: tag tied to this inode and chain, or zero if none + + int bpf_landlock_set_tag(tag_obj, chain, value) + @tag_obj: pointer pointing to a taggable object (e.g. inode) + @chain: pointer to struct landlock_chain + @value: value of the tag + Return: 0 on success or negative error code + +See *include/uapi/linux/bpf.h* for other functions documentation. + + +Additional documentation +======================== + +See https://landlock.io -- 2.16.2 From mboxrd@z Thu Jan 1 00:00:00 1970 From: mic@digikod.net (=?UTF-8?q?Micka=C3=ABl=20Sala=C3=BCn?=) Date: Tue, 27 Feb 2018 01:41:21 +0100 Subject: [PATCH bpf-next v8 11/11] landlock: Add user and kernel documentation for Landlock In-Reply-To: <20180227004121.3633-1-mic@digikod.net> References: <20180227004121.3633-1-mic@digikod.net> Message-ID: <20180227004121.3633-12-mic@digikod.net> To: linux-security-module@vger.kernel.org List-Id: linux-security-module.vger.kernel.org This documentation can be built with the Sphinx framework. Signed-off-by: Micka?l Sala?n Cc: Alexei Starovoitov Cc: Andy Lutomirski Cc: Daniel Borkmann Cc: David S. Miller Cc: James Morris Cc: Jonathan Corbet Cc: Kees Cook Cc: Serge E. Hallyn --- Changes since v7: * update documentation according to the Landlock revamp Changes since v6: * add a check for ctx->event * rename BPF_PROG_TYPE_LANDLOCK to BPF_PROG_TYPE_LANDLOCK_RULE * rename Landlock version to ABI to better reflect its purpose and add a dedicated changelog section * update tables * relax no_new_privs recommendations * remove ABILITY_WRITE related functions * reword rule "appending" to "prepending" and explain it * cosmetic fixes Changes since v5: * update the rule hierarchy inheritance explanation * briefly explain ctx->arg2 * add ptrace restrictions * explain EPERM * update example (subtype) * use ":manpage:" --- Documentation/security/index.rst | 1 + Documentation/security/landlock/index.rst | 19 +++ Documentation/security/landlock/kernel.rst | 100 ++++++++++++++ Documentation/security/landlock/user.rst | 206 +++++++++++++++++++++++++++++ 4 files changed, 326 insertions(+) create mode 100644 Documentation/security/landlock/index.rst create mode 100644 Documentation/security/landlock/kernel.rst create mode 100644 Documentation/security/landlock/user.rst diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst index 298a94a33f05..1db294025d0f 100644 --- a/Documentation/security/index.rst +++ b/Documentation/security/index.rst @@ -11,3 +11,4 @@ Security Documentation LSM self-protection tpm/index + landlock/index diff --git a/Documentation/security/landlock/index.rst b/Documentation/security/landlock/index.rst new file mode 100644 index 000000000000..8afde6a5805c --- /dev/null +++ b/Documentation/security/landlock/index.rst @@ -0,0 +1,19 @@ +========================================= +Landlock LSM: programmatic access control +========================================= + +Landlock is a stackable Linux Security Module (LSM) that makes it possible to +create security sandboxes. This kind of sandbox is expected to help mitigate +the security impact of bugs or unexpected/malicious behaviors in user-space +applications. The current version allows only a process with the global +CAP_SYS_ADMIN capability to create such sandboxes but the ultimate goal of +Landlock is to empower any process, including unprivileged ones, to securely +restrict themselves. Landlock is inspired by seccomp-bpf but instead of +filtering syscalls and their raw arguments, a Landlock rule can inspect the use +of kernel objects like files and hence make a decision according to the kernel +semantic. + +.. toctree:: + + user + kernel diff --git a/Documentation/security/landlock/kernel.rst b/Documentation/security/landlock/kernel.rst new file mode 100644 index 000000000000..0a52915e346c --- /dev/null +++ b/Documentation/security/landlock/kernel.rst @@ -0,0 +1,100 @@ +============================== +Landlock: kernel documentation +============================== + +eBPF properties +=============== + +To get an expressive language while still being safe and small, Landlock is +based on eBPF. Landlock should be usable by untrusted processes and must +therefore expose a minimal attack surface. The eBPF bytecode is minimal, +powerful, widely used and designed to be used by untrusted applications. Thus, +reusing the eBPF support in the kernel enables a generic approach while +minimizing new code. + +An eBPF program has access to an eBPF context containing some fields used to +inspect the current object. These arguments can be used directly (e.g. cookie) +or passed to helper functions according to their types (e.g. inode pointer). It +is then possible to do complex access checks without race conditions or +inconsistent evaluation (i.e. `incorrect mirroring of the OS code and state +`_). + +A Landlock hook describes a particular access type. For now, there is three +hooks dedicated to filesystem related operations: LANDLOCK_HOOK_FS_PICK, +LANDLOCK_HOOK_FS_WALK and LANDLOCK_HOOK_FS_GET. A Landlock program is tied to +one hook. This makes it possible to statically check context accesses, +potentially performed by such program, and hence prevents kernel address leaks +and ensure the right use of hook arguments with eBPF functions. Any user can +add multiple Landlock programs per Landlock hook. They are stacked and +evaluated one after the other, starting from the most recent program, as +seccomp-bpf does with its filters. Underneath, a hook is an abstraction over a +set of LSM hooks. + + +Guiding principles +================== + +Unprivileged use +---------------- + +* Landlock helpers and context should be usable by any unprivileged and + untrusted program while following the system security policy enforced by + other access control mechanisms (e.g. DAC, LSM). + + +Landlock hook and context +------------------------- + +* A Landlock hook shall be focused on access control on kernel objects instead + of syscall filtering (i.e. syscall arguments), which is the purpose of + seccomp-bpf. +* A Landlock context provided by a hook shall express the minimal and more + generic interface to control an access for a kernel object. +* A hook shall guaranty that all the BPF function calls from a program are + safe. Thus, the related Landlock context arguments shall always be of the + same type for a particular hook. For example, a network hook could share + helpers with a file hook because of UNIX socket. However, the same helpers + may not be compatible for a FS handle and a net handle. +* Multiple hooks may use the same context interface. + + +Landlock helpers +---------------- + +* Landlock helpers shall be as generic as possible while at the same time being + as simple as possible and following the syscall creation principles (cf. + *Documentation/adding-syscalls.txt*). +* The only behavior change allowed on a helper is to fix a (logical) bug to + match the initial semantic. +* Helpers shall be reentrant, i.e. only take inputs from arguments (e.g. from + the BPF context), to enable a hook to use a cache. Future program options + might change this cache behavior. +* It is quite easy to add new helpers to extend Landlock. The main concern + should be about the possibility to leak information from the kernel that may + not be accessible otherwise (i.e. side-channel attack). + + +Questions and answers +===================== + +Why not create a custom hook for each kind of action? +----------------------------------------------------- + +Landlock programs can handle these checks. Adding more exceptions to the +kernel code would lead to more code complexity. A decision to ignore a kind of +action can and should be done at the beginning of a Landlock program. + + +Why a program does not return an errno or a kill code? +------------------------------------------------------ + +seccomp filters can return multiple kind of code, including an errno value or a +kill signal, which may be convenient for access control. Those return codes +are hardwired in the userland ABI. Instead, Landlock's approach is to return a +boolean to allow or deny an action, which is much simpler and more generic. +Moreover, we do not really have a choice because, unlike to seccomp, Landlock +programs are not enforced at the syscall entry point but may be executed at any +point in the kernel (through LSM hooks) where an errno return code may not make +sense. However, with this simple ABI and with the ability to call helpers, +Landlock may gain features similar to seccomp-bpf in the future while being +compatible with previous programs. diff --git a/Documentation/security/landlock/user.rst b/Documentation/security/landlock/user.rst new file mode 100644 index 000000000000..3130063c9087 --- /dev/null +++ b/Documentation/security/landlock/user.rst @@ -0,0 +1,206 @@ +================================ +Landlock: userland documentation +================================ + +Landlock programs +================= + +eBPF programs are used to create security programs. They are contained and can +call only a whitelist of dedicated functions. Moreover, they cannot loop, which +protects from denial of service. More information on BPF can be found in +*Documentation/networking/filter.txt*. + + +Writing a program +----------------- + +To enforce a security policy, a thread first needs to create a Landlock program. +The easiest way to write an eBPF program depicting a security program is to write +it in the C language. As described in *samples/bpf/README.rst*, LLVM can +compile such programs. Files *samples/bpf/landlock1_kern.c* and those in +*tools/testing/selftests/landlock/* can be used as examples. + +Once the eBPF program is created, the next step is to create the metadata +describing the Landlock program. This metadata includes a subtype which +contains the hook type to which the program is tied and some options. + +.. code-block:: c + + union bpf_prog_subtype subtype = { + .landlock_hook = { + .type = LANDLOCK_HOOK_FS_PICK, + .triggers = LANDLOCK_TRIGGER_FS_PICK_OPEN, + } + }; + +A Landlock hook describes the kind of kernel object for which a program will be +triggered to allow or deny an action. For example, the hook +LANDLOCK_HOOK_FS_PICK can be triggered every time a landlocked thread performs +a set of action related to the filesystem (e.g. open, read, write, mount...). +This actions are identified by the `triggers` bitfield. + +The next step is to fill a :c:type:`union bpf_attr ` with +BPF_PROG_TYPE_LANDLOCK_HOOK, the previously created subtype and other BPF +program metadata. This bpf_attr must then be passed to the :manpage:`bpf(2)` +syscall alongside the BPF_PROG_LOAD command. If everything is deemed correct +by the kernel, the thread gets a file descriptor referring to this program. + +In the following code, the *insn* variable is an array of BPF instructions +which can be extracted from an ELF file as is done in bpf_load_file() from +*samples/bpf/bpf_load.c*. + +.. code-block:: c + + union bpf_attr attr = { + .prog_type = BPF_PROG_TYPE_LANDLOCK_HOOK, + .insn_cnt = sizeof(insn) / sizeof(struct bpf_insn), + .insns = (__u64) (unsigned long) insn, + .license = (__u64) (unsigned long) "GPL", + .prog_subtype = &subtype, + .prog_subtype_size = sizeof(subtype), + }; + int fd = bpf(BPF_PROG_LOAD, &attr, sizeof(attr)); + if (fd == -1) + exit(1); + + +Enforcing a program +------------------- + +Once the Landlock program has been created or received (e.g. through a UNIX +socket), the thread willing to sandbox itself (and its future children) should +perform the following two steps. + +The thread should first request to never be allowed to get new privileges with a +call to :manpage:`prctl(2)` and the PR_SET_NO_NEW_PRIVS option. More +information can be found in *Documentation/prctl/no_new_privs.txt*. + +.. code-block:: c + + if (prctl(PR_SET_NO_NEW_PRIVS, 1, NULL, 0, 0)) + exit(1); + +A thread can apply a program to itself by using the :manpage:`seccomp(2)` syscall. +The operation is SECCOMP_PREPEND_LANDLOCK_PROG, the flags must be empty and the +*args* argument must point to a valid Landlock program file descriptor. + +.. code-block:: c + + if (seccomp(SECCOMP_PREPEND_LANDLOCK_PROG, 0, &fd)) + exit(1); + +If the syscall succeeds, the program is now enforced on the calling thread and +will be enforced on all its subsequently created children of the thread as +well. Once a thread is landlocked, there is no way to remove this security +policy, only stacking more restrictions is allowed. The program evaluation is +performed from the newest to the oldest. + +When a syscall ask for an action on a kernel object, if this action is denied, +then an EACCES errno code is returned through the syscall. + + +.. _inherited_programs: + +Inherited programs +------------------ + +Every new thread resulting from a :manpage:`clone(2)` inherits Landlock program +restrictions from its parent. This is similar to the seccomp inheritance as +described in *Documentation/prctl/seccomp_filter.txt*. + + +Ptrace restrictions +------------------- + +A landlocked process has less privileges than a non-landlocked process and must +then be subject to additional restrictions when manipulating another process. +To be allowed to use :manpage:`ptrace(2)` and related syscalls on a target +process, a landlocked process must have a subset of the target process programs. + + +Chained programs +================ + +Landlock programs can be chained according to the hook they are tied to. This +enable to keep a state between multiple program evaluation for an object access +check (e.g. walking through a file path). The *cookie* field from the context +can be used as a temporary storage shared between a chain of programs. + +The following graph is an example of the chain of programs used in +*samples/bpf/landlock1_kern.c*. The fs_walk program evaluate if a file is +beneath a set of file hierarchy. The first fs_pick program may be called when +there is a read-like action (i.e. trigger for open, chdir, getattr...). The +second fs_pick program may be called for write-like actions. And finally, the +fs_get program is called to tag a file when it is open, receive or when the +current task changes directory. This tagging is needed to be able to keep the +state of this file evaluation for a next one involving the same opened file. + +:: + + .---------. + | fs_walk | + '---------' + | + v + .---------. + | fs_pick | open, chdir, getattr... + '---------' + | + v + .---------. + | fs_pick | create, write, link... + '---------' + | + v + .--------. + | fs_get | + '--------' + + +Landlock structures and constants +================================= + +Hook types +---------- + +.. kernel-doc:: include/uapi/linux/landlock.h + :functions: landlock_hook_type + + +Contexts +-------- + +.. kernel-doc:: include/uapi/linux/landlock.h + :functions: landlock_ctx_fs_pick landlock_ctx_fs_walk landlock_ctx_fs_get + + +Triggers for fs_pick +-------------------- + +.. kernel-doc:: include/uapi/linux/landlock.h + :functions: landlock_triggers + + +Helper functions +---------------- + +:: + + u64 bpf_inode_get_tag(inode, chain) + @inode: pointer to struct inode + @chain: pointer to struct landlock_chain + Return: tag tied to this inode and chain, or zero if none + + int bpf_landlock_set_tag(tag_obj, chain, value) + @tag_obj: pointer pointing to a taggable object (e.g. inode) + @chain: pointer to struct landlock_chain + @value: value of the tag + Return: 0 on success or negative error code + +See *include/uapi/linux/bpf.h* for other functions documentation. + + +Additional documentation +======================== + +See https://landlock.io -- 2.16.2 -- To unsubscribe from this list: send the line "unsubscribe linux-security-module" in the body of a message to majordomo at vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html