1 .. SPDX-License-Identifier: GPL-2.0+
2 .. Copyright (C) 2020 Google LLC.
3
4 ================
5 LSM BPF Programs
6 ================
7
8 These BPF programs allow runtime instrumentation of the LSM hooks by privileged
9 users to implement system-wide MAC (Mandatory Access Control) and Audit
10 policies using eBPF.
11
12 Structure
13 ---------
14
15 The example shows an eBPF program that can be attached to the ``file_mprotect``
16 LSM hook:
17
18 .. c:function:: int file_mprotect(struct vm_area_struct *vma, unsigned long reqprot, unsigned long prot);
19
20 Other LSM hooks which can be instrumented can be found in
21 ``security/security.c``.
22
23 eBPF programs that use Documentation/bpf/btf.rst do not need to include kernel
24 headers for accessing information from the attached eBPF program's context.
25 They can simply declare the structures in the eBPF program and only specify
26 the fields that need to be accessed.
27
28 .. code-block:: c
29
30 struct mm_struct {
31 unsigned long start_brk, brk, start_stack;
32 } __attribute__((preserve_access_index));
33
34 struct vm_area_struct {
35 unsigned long start_brk, brk, start_stack;
36 unsigned long vm_start, vm_end;
37 struct mm_struct *vm_mm;
38 } __attribute__((preserve_access_index));
39
40
41 .. note:: The order of the fields is irrelevant.
42
43 This can be further simplified (if one has access to the BTF information at
44 build time) by generating the ``vmlinux.h`` with:
45
46 .. code-block:: console
47
48 # bpftool btf dump file <path-to-btf-vmlinux> format c > vmlinux.h
49
50 .. note:: ``path-to-btf-vmlinux`` can be ``/sys/kernel/btf/vmlinux`` if the
51 build environment matches the environment the BPF programs are
52 deployed in.
53
54 The ``vmlinux.h`` can then simply be included in the BPF programs without
55 requiring the definition of the types.
56
57 The eBPF programs can be declared using the``BPF_PROG``
58 macros defined in `tools/lib/bpf/bpf_tracing.h`_. In this
59 example:
60
61 * ``"lsm/file_mprotect"`` indicates the LSM hook that the program must
62 be attached to
63 * ``mprotect_audit`` is the name of the eBPF program
64
65 .. code-block:: c
66
67 SEC("lsm/file_mprotect")
68 int BPF_PROG(mprotect_audit, struct vm_area_struct *vma,
69 unsigned long reqprot, unsigned long prot, int ret)
70 {
71 /* ret is the return value from the previous BPF program
72 * or 0 if it's the first hook.
73 */
74 if (ret != 0)
75 return ret;
76
77 int is_heap;
78
79 is_heap = (vma->vm_start >= vma->vm_mm->start_brk &&
80 vma->vm_end <= vma->vm_mm->brk);
81
82 /* Return an -EPERM or write information to the perf events buffer
83 * for auditing
84 */
85 if (is_heap)
86 return -EPERM;
87 }
88
89 The ``__attribute__((preserve_access_index))`` is a clang feature that allows
90 the BPF verifier to update the offsets for the access at runtime using the
91 Documentation/bpf/btf.rst information. Since the BPF verifier is aware of the
92 types, it also validates all the accesses made to the various types in the
93 eBPF program.
94
95 Loading
96 -------
97
98 eBPF programs can be loaded with the :manpage:`bpf(2)` syscall's
99 ``BPF_PROG_LOAD`` operation:
100
101 .. code-block:: c
102
103 struct bpf_object *obj;
104
105 obj = bpf_object__open("./my_prog.o");
106 bpf_object__load(obj);
107
108 This can be simplified by using a skeleton header generated by ``bpftool``:
109
110 .. code-block:: console
111
112 # bpftool gen skeleton my_prog.o > my_prog.skel.h
113
114 and the program can be loaded by including ``my_prog.skel.h`` and using
115 the generated helper, ``my_prog__open_and_load``.
116
117 Attachment to LSM Hooks
118 -----------------------
119
120 The LSM allows attachment of eBPF programs as LSM hooks using :manpage:`bpf(2)`
121 syscall's ``BPF_RAW_TRACEPOINT_OPEN`` operation or more simply by
122 using the libbpf helper ``bpf_program__attach_lsm``.
123
124 The program can be detached from the LSM hook by *destroying* the ``link``
125 link returned by ``bpf_program__attach_lsm`` using ``bpf_link__destroy``.
126
127 One can also use the helpers generated in ``my_prog.skel.h`` i.e.
128 ``my_prog__attach`` for attachment and ``my_prog__destroy`` for cleaning up.
129
130 Examples
131 --------
132
133 An example eBPF program can be found in
134 `tools/testing/selftests/bpf/progs/lsm.c`_ and the corresponding
135 userspace code in `tools/testing/selftests/bpf/prog_tests/test_lsm.c`_
136
137 .. Links
138 .. _tools/lib/bpf/bpf_tracing.h:
139 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/lib/bpf/bpf_tracing.h
140 .. _tools/testing/selftests/bpf/progs/lsm.c:
141 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/bpf/progs/lsm.c
142 .. _tools/testing/selftests/bpf/prog_tests/test_lsm.c:
143 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/bpf/prog_tests/test_lsm.c
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.