On Tue, Feb 21, 2017 at 5:26 PM, Mickaël Salaün <mic@xxxxxxxxxxx> wrote:
> This documentation can be built with the Sphinx framework.
>
> Signed-off-by: Mickaël Salaün <mic@xxxxxxxxxxx>
> Cc: Alexei Starovoitov <ast@xxxxxxxxxx>
> Cc: Andy Lutomirski <luto@xxxxxxxxxxxxxx>
> Cc: Daniel Borkmann <daniel@xxxxxxxxxxxxx>
> Cc: David S. Miller <davem@xxxxxxxxxxxxx>
> Cc: James Morris <james.l.morris@xxxxxxxxxx>
> Cc: Jonathan Corbet <corbet@xxxxxxx>
> Cc: Kees Cook <keescook@xxxxxxxxxxxx>
> Cc: Serge E. Hallyn <serge@xxxxxxxxxx>
> +
> +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
--
To unsubscribe from this list: send the line "unsubscribe linux-api" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
