LKML Archive on lore.kernel.org
 help / color / Atom feed
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 --]

      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