On 22/02/2017 06:21, Andy Lutomirski wrote:
On Tue, Feb 21, 2017 at 5:26 PM, Mickaël Salaün [off-list ref] wrote:
quoted
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 <redacted>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Kees Cook <redacted>
Cc: Serge E. Hallyn <serge@hallyn.com>
quoted
+
+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.
quoted
+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.
quoted
+
+
+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).
quoted
+
+Helper functions
+----------------
+
+See *include/uapi/linux/bpf.h* for functions documentation.
+
+.. flat-table:: Generic functions availability
+
quoted
+
+ * - 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?
quoted
+ * - 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