linux-kernel - Re: [PATCH v5 10/10] landlock: Add user and kernel documentation for Landlock

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <CALCETrXzL0VH_=QYHGXk1Y5P_yLyXdyTD-JVHVKTFf8F-AhYnw@mail.gmail.com>
Date:   Tue, 21 Feb 2017 21:21:21 -0800
From:   Andy Lutomirski <luto@...capital.net>
To:     Mickaël Salaün <mic@...ikod.net>
Cc:     "linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
        Alexei Starovoitov <ast@...nel.org>,
        Arnaldo Carvalho de Melo <acme@...nel.org>,
        Casey Schaufler <casey@...aufler-ca.com>,
        Daniel Borkmann <daniel@...earbox.net>,
        David Drysdale <drysdale@...gle.com>,
        "David S . Miller" <davem@...emloft.net>,
        "Eric W . Biederman" <ebiederm@...ssion.com>,
        James Morris <james.l.morris@...cle.com>,
        Jann Horn <jann@...jh.net>, Jonathan Corbet <corbet@....net>,
        Matthew Garrett <mjg59@...f.ucam.org>,
        Michael Kerrisk <mtk.manpages@...il.com>,
        Kees Cook <keescook@...omium.org>,
        Paul Moore <paul@...l-moore.com>,
        Sargun Dhillon <sargun@...gun.me>,
        "Serge E . Hallyn" <serge@...lyn.com>,
        Shuah Khan <shuah@...nel.org>, Tejun Heo <tj@...nel.org>,
        Thomas Graf <tgraf@...g.ch>, Will Drewry <wad@...omium.org>,
        "kernel-hardening@...ts.openwall.com" 
        <kernel-hardening@...ts.openwall.com>,
        Linux API <linux-api@...r.kernel.org>,
        LSM List <linux-security-module@...r.kernel.org>,
        Network Development <netdev@...r.kernel.org>
Subject: Re: [PATCH v5 10/10] landlock: Add user and kernel documentation for Landlock

On Tue, Feb 21, 2017 at 5:26 PM, Mickaël Salaün <mic@...ikod.net> wrote:
> This documentation can be built with the Sphinx framework.
>
> Signed-off-by: Mickaël Salaün <mic@...ikod.net>
> Cc: Alexei Starovoitov <ast@...nel.org>
> Cc: Andy Lutomirski <luto@...capital.net>
> Cc: Daniel Borkmann <daniel@...earbox.net>
> Cc: David S. Miller <davem@...emloft.net>
> Cc: James Morris <james.l.morris@...cle.com>
> Cc: Jonathan Corbet <corbet@....net>
> Cc: Kees Cook <keescook@...omium.org>
> Cc: Serge E. Hallyn <serge@...lyn.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