From: Andy Lutomirski <luto@amacapital.net>
To: "Mickaël Salaün" <mic@digikod.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: Tue, 21 Feb 2017 21:21:21 -0800 [thread overview]
Message-ID: <CALCETrXzL0VH_=QYHGXk1Y5P_yLyXdyTD-JVHVKTFf8F-AhYnw@mail.gmail.com> (raw)
In-Reply-To: <20170222012632.4196-11-mic@digikod.net>
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?
Can you specify what the return value means? Are 0 and 1 the only
choices? Would "KILL" be useful? How about "COREDUMP"?
> +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?
> +
> +
> +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?
> +
> +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?
> + * - 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.
--Andy
next prev parent reply other threads:[~2017-02-22 5:21 UTC|newest]
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 [this message]
2017-02-22 7:43 ` Mickaël Salaün
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='CALCETrXzL0VH_=QYHGXk1Y5P_yLyXdyTD-JVHVKTFf8F-AhYnw@mail.gmail.com' \
--to=luto@amacapital.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=mic@digikod.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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).