From: "Mickaël Salaün" <mic@digikod.net> To: Andy Lutomirski <luto@amacapital.net> Cc: "linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>, Alexei Starovoitov <ast@kernel.org>, Arnaldo Carvalho de Melo <acme@kernel.org>, Casey Schaufler <casey@schaufler-ca.com>, Daniel Borkmann <daniel@iogearbox.net>, David Drysdale <drysdale@google.com>, "David S . Miller" <davem@davemloft.net>, "Eric W . Biederman" <ebiederm@xmission.com>, James Morris <james.l.morris@oracle.com>, Jann Horn <jann@thejh.net>, Jonathan Corbet <corbet@lwn.net>, Matthew Garrett <mjg59@srcf.ucam.org>, Michael Kerrisk <mtk.manpages@gmail.com>, Kees Cook <keescook@chromium.org>, Paul Moore <paul@paul-moore.com>, Sargun Dhillon <sargun@sargun.me>, "Serge E . Hallyn" <serge@hallyn.com>, Shuah Khan <shuah@kernel.org>, Tejun Heo <tj@kernel.org>, Thomas Graf <tgraf@suug.ch>, Will Drewry <wad@chromium.org>, "kernel-hardening@lists.openwall.com" <kernel-hardening@lists.openwall.com>, Linux API <linux-api@vger.kernel.org>, LSM List <linux-security-module@vger.kernel.org>, Network Development <netdev@vger.kernel.org> Subject: Re: [PATCH v5 10/10] landlock: Add user and kernel documentation for Landlock Date: Wed, 22 Feb 2017 08:43:36 +0100 Message-ID: <b56c6abf-c8a5-d926-dcf7-0f0a6aa1334f@digikod.net> (raw) In-Reply-To: <CALCETrXzL0VH_=QYHGXk1Y5P_yLyXdyTD-JVHVKTFf8F-AhYnw@mail.gmail.com> [-- Attachment #1.1: Type: text/plain, Size: 4995 bytes --] On 22/02/2017 06:21, Andy Lutomirski wrote: > On Tue, Feb 21, 2017 at 5:26 PM, Mickaël Salaün <mic@digikod.net> wrote: >> This documentation can be built with the Sphinx framework. >> >> Signed-off-by: Mickaël Salaün <mic@digikod.net> >> Cc: Alexei Starovoitov <ast@kernel.org> >> Cc: Andy Lutomirski <luto@amacapital.net> >> Cc: Daniel Borkmann <daniel@iogearbox.net> >> Cc: David S. Miller <davem@davemloft.net> >> Cc: James Morris <james.l.morris@oracle.com> >> Cc: Jonathan Corbet <corbet@lwn.net> >> Cc: Kees Cook <keescook@chromium.org> >> Cc: Serge E. Hallyn <serge@hallyn.com> > > >> + >> +Writing a rule >> +-------------- >> + >> +To enforce a security policy, a thread first needs to create a Landlock rule. >> +The easiest way to write an eBPF program depicting a security rule 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/rules/* can be used as examples. The >> +following example is a simple rule to forbid file creation, whatever syscall >> +may be used (e.g. open, mkdir, link...). >> + >> +.. code-block:: c >> + >> + static int deny_file_creation(struct landlock_context *ctx) >> + { >> + if (ctx->arg2 & LANDLOCK_ACTION_FS_NEW) >> + return 1; >> + return 0; >> + } >> + > > Would it make sense to define landlock_context (or at least a prefix > thereof) in here? Also, can't "arg2" have a better name? arg2 is a generic name. Its meaning depends on the Landlock event, here it is an action bitfield (FS event). > > Can you specify what the return value means? Are 0 and 1 the only > choices? Would "KILL" be useful? How about "COREDUMP"? This is explained thereafter and in the kernel Q&A section. I need to briefly introduce that here. > >> +File system action types >> +------------------------ >> + >> +Flags are used to express actions. This makes it possible to compose actions >> +and leaves room for future improvements to add more fine-grained action types. >> + >> +.. kernel-doc:: include/uapi/linux/bpf.h >> + :doc: landlock_action_fs >> + >> +.. flat-table:: FS action types availability >> + >> + * - flags >> + - since >> + >> + * - LANDLOCK_ACTION_FS_EXEC >> + - v1 >> + >> + * - LANDLOCK_ACTION_FS_WRITE >> + - v1 >> + >> + * - LANDLOCK_ACTION_FS_READ >> + - v1 >> + >> + * - LANDLOCK_ACTION_FS_NEW >> + - v1 >> + >> + * - LANDLOCK_ACTION_FS_GET >> + - v1 >> + >> + * - LANDLOCK_ACTION_FS_REMOVE >> + - v1 >> + >> + * - LANDLOCK_ACTION_FS_IOCTL >> + - v1 >> + >> + * - LANDLOCK_ACTION_FS_LOCK >> + - v1 >> + >> + * - LANDLOCK_ACTION_FS_FCNTL >> + - v1 > > What happens if you run an old program on a new kernel? Can you get > unexpected action types? The old flags will still make sense, the new ones should be ignored by the rule. > >> + >> + >> +Ability types >> +------------- >> + >> +The ability of a Landlock rule describes the available features (i.e. context >> +fields and helpers). This is useful to abstract user-space privileges for >> +Landlock rules, which may not need all abilities (e.g. debug). Only the >> +minimal set of abilities should be used (e.g. disable debug once in >> +production). >> + >> + >> +.. kernel-doc:: include/uapi/linux/bpf.h >> + :doc: landlock_subtype_ability >> + >> +.. flat-table:: Ability types availability >> + >> + * - flags >> + - since >> + - capability >> + >> + * - LANDLOCK_SUBTYPE_ABILITY_WRITE >> + - v1 >> + - CAP_SYS_ADMIN >> + >> + * - LANDLOCK_SUBTYPE_ABILITY_DEBUG >> + - v1 >> + - CAP_SYS_ADMIN >> + > > What do "WRITE" and "DEBUG" mean in this context? I'm totally lost. > > Hmm. Reading below, "WRITE" seems to mean "modify state". Would that > be accurate? That is correct, but handling a state in a safe way imply more than only the ability to "write" outside bpfland (e.g. sequential execution). > >> + >> +Helper functions >> +---------------- >> + >> +See *include/uapi/linux/bpf.h* for functions documentation. >> + >> +.. flat-table:: Generic functions availability >> + > >> + >> + * - bpf_get_current_comm >> + - v1 >> + - LANDLOCK_SUBTYPE_ABILITY_DEBUG > > What would this be used for? To get more information about the process which trigger an action? > >> + * - bpf_get_trace_printk >> + - v1 >> + - LANDLOCK_SUBTYPE_ABILITY_DEBUG >> + > > This is different from the other DEBUG stuff in that it has side > effects. I wonder if it should have a different flag. I think the debug flag is a clear warning to not ship a rule using this ability. Maybe a sub-flag LANDLOCK_SUBTYPE_ABILITY_DEBUG_PRINT would fit here? Mickaël [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 488 bytes --]
prev parent reply index Thread overview: 26+ messages / expand[flat|nested] mbox.gz Atom feed top 2017-02-22 1:26 [PATCH v5 00/10] Landlock LSM: Toward unprivileged sandboxing Mickaël Salaün 2017-02-22 1:26 ` [PATCH v5 01/10] bpf: Add eBPF program subtype and is_valid_subtype() verifier Mickaël Salaün 2017-02-22 1:26 ` [PATCH v5 02/10] bpf,landlock: Define an eBPF program type for Landlock Mickaël Salaün 2017-02-22 1:26 ` [PATCH v5 03/10] bpf: Define handle_fs and add a new helper bpf_handle_fs_get_mode() Mickaël Salaün 2017-03-01 9:32 ` James Morris 2017-03-01 22:20 ` Mickaël Salaün 2017-02-22 1:26 ` [PATCH v5 04/10] landlock: Add LSM hooks related to filesystem Mickaël Salaün 2017-02-22 1:26 ` [PATCH v5 05/10] seccomp: Split put_seccomp_filter() with put_seccomp() Mickaël Salaün 2017-02-22 1:26 ` [PATCH v5 06/10] seccomp,landlock: Handle Landlock events per process hierarchy Mickaël Salaün 2017-02-28 20:01 ` Andy Lutomirski 2017-03-01 22:14 ` Mickaël Salaün 2017-03-01 22:20 ` Andy Lutomirski 2017-03-01 23:28 ` Mickaël Salaün 2017-03-02 16:36 ` Andy Lutomirski 2017-03-03 0:48 ` Mickaël Salaün 2017-03-03 0:55 ` Andy Lutomirski 2017-03-03 1:05 ` Mickaël Salaün 2017-03-02 10:22 ` [kernel-hardening] " Djalal Harouni 2017-03-03 0:54 ` Mickaël Salaün 2017-02-22 1:26 ` [PATCH v5 07/10] bpf: Add a Landlock sandbox example Mickaël Salaün 2017-02-23 22:13 ` Mickaël Salaün 2017-02-22 1:26 ` [PATCH v5 08/10] seccomp: Enhance test_harness with an assert step mechanism Mickaël Salaün 2017-02-22 1:26 ` [PATCH v5 09/10] bpf,landlock: Add tests for Landlock Mickaël Salaün 2017-02-22 1:26 ` [PATCH v5 10/10] landlock: Add user and kernel documentation " Mickaël Salaün 2017-02-22 5:21 ` Andy Lutomirski 2017-02-22 7:43 ` Mickaël Salaün [this message]
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=b56c6abf-c8a5-d926-dcf7-0f0a6aa1334f@digikod.net \ --to=mic@digikod.net \ --cc=acme@kernel.org \ --cc=ast@kernel.org \ --cc=casey@schaufler-ca.com \ --cc=corbet@lwn.net \ --cc=daniel@iogearbox.net \ --cc=davem@davemloft.net \ --cc=drysdale@google.com \ --cc=ebiederm@xmission.com \ --cc=james.l.morris@oracle.com \ --cc=jann@thejh.net \ --cc=keescook@chromium.org \ --cc=kernel-hardening@lists.openwall.com \ --cc=linux-api@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=linux-security-module@vger.kernel.org \ --cc=luto@amacapital.net \ --cc=mjg59@srcf.ucam.org \ --cc=mtk.manpages@gmail.com \ --cc=netdev@vger.kernel.org \ --cc=paul@paul-moore.com \ --cc=sargun@sargun.me \ --cc=serge@hallyn.com \ --cc=shuah@kernel.org \ --cc=tgraf@suug.ch \ --cc=tj@kernel.org \ --cc=wad@chromium.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
LKML Archive on lore.kernel.org Archives are clonable: git clone --mirror https://lore.kernel.org/lkml/0 lkml/git/0.git git clone --mirror https://lore.kernel.org/lkml/1 lkml/git/1.git git clone --mirror https://lore.kernel.org/lkml/2 lkml/git/2.git git clone --mirror https://lore.kernel.org/lkml/3 lkml/git/3.git git clone --mirror https://lore.kernel.org/lkml/4 lkml/git/4.git git clone --mirror https://lore.kernel.org/lkml/5 lkml/git/5.git git clone --mirror https://lore.kernel.org/lkml/6 lkml/git/6.git git clone --mirror https://lore.kernel.org/lkml/7 lkml/git/7.git git clone --mirror https://lore.kernel.org/lkml/8 lkml/git/8.git git clone --mirror https://lore.kernel.org/lkml/9 lkml/git/9.git # If you have public-inbox 1.1+ installed, you may # initialize and index your mirror using the following commands: public-inbox-init -V2 lkml lkml/ https://lore.kernel.org/lkml \ linux-kernel@vger.kernel.org public-inbox-index lkml Example config snippet for mirrors Newsgroup available over NNTP: nntp://nntp.lore.kernel.org/org.kernel.vger.linux-kernel AGPL code for this site: git clone https://public-inbox.org/public-inbox.git