On 22/02/2017 06:21, Andy Lutomirski wrote:
> On Tue, Feb 21, 2017 at 5:26 PM, Mickaël Salaün <m...@digikod.net> wrote:
>> This documentation can be built with the Sphinx framework.
>>
>> Signed-off-by: Mickaël Salaün <m...@digikod.net>
>> Cc: Alexei Starovoitov <a...@kernel.org>
>> Cc: Andy Lutomirski <l...@amacapital.net>
>> Cc: Daniel Borkmann <dan...@iogearbox.net>
>> Cc: David S. Miller <da...@davemloft.net>
>> Cc: James Morris <james.l.mor...@oracle.com>
>> Cc: Jonathan Corbet <cor...@lwn.net>
>> Cc: Kees Cook <keesc...@chromium.org>
>> Cc: Serge E. Hallyn <se...@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
signature.asc
Description: OpenPGP digital signature
