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 instrumentati
9 users to implement system-wide MAC (Mandatory
10 policies using eBPF.
11
12 Structure
13 ---------
14
15 The example shows an eBPF program that can be
16 LSM hook:
17
18 .. c:function:: int file_mprotect(struct vm_ar
19
20 Other LSM hooks which can be instrumented can
21 ``security/security.c``.
22
23 eBPF programs that use Documentation/bpf/btf.r
24 headers for accessing information from the att
25 They can simply declare the structures in the
26 the fields that need to be accessed.
27
28 .. code-block:: c
29
30 struct mm_struct {
31 unsigned long start_brk, brk,
32 } __attribute__((preserve_access_index
33
34 struct vm_area_struct {
35 unsigned long start_brk, brk,
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 irrelevan
42
43 This can be further simplified (if one has acc
44 build time) by generating the ``vmlinux.h`` wi
45
46 .. code-block:: console
47
48 # bpftool btf dump file <path-to-btf-v
49
50 .. note:: ``path-to-btf-vmlinux`` can be ``/sy
51 build environment matches the enviro
52 deployed in.
53
54 The ``vmlinux.h`` can then simply be included
55 requiring the definition of the types.
56
57 The eBPF programs can be declared using the``B
58 macros defined in `tools/lib/bpf/bpf_tracing.h
59 example:
60
61 * ``"lsm/file_mprotect"`` indicates th
62 be attached to
63 * ``mprotect_audit`` is the name of th
64
65 .. code-block:: c
66
67 SEC("lsm/file_mprotect")
68 int BPF_PROG(mprotect_audit, struct vm
69 unsigned long reqprot, un
70 {
71 /* ret is the return value fro
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 >= vm
80 vma->vm_end <= vma-
81
82 /* Return an -EPERM or write i
83 * for auditing
84 */
85 if (is_heap)
86 return -EPERM;
87 }
88
89 The ``__attribute__((preserve_access_index))``
90 the BPF verifier to update the offsets for the
91 Documentation/bpf/btf.rst information. Since t
92 types, it also validates all the accesses made
93 eBPF program.
94
95 Loading
96 -------
97
98 eBPF programs can be loaded with the :manpage:
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 hea
109
110 .. code-block:: console
111
112 # bpftool gen skeleton my_prog.o > my_
113
114 and the program can be loaded by including ``m
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
121 syscall's ``BPF_RAW_TRACEPOINT_OPEN`` operatio
122 using the libbpf helper ``bpf_program__attach_
123
124 The program can be detached from the LSM hook
125 link returned by ``bpf_program__attach_lsm`` u
126
127 One can also use the helpers generated in ``my
128 ``my_prog__attach`` for attachment and ``my_pr
129
130 Examples
131 --------
132
133 An example eBPF program can be found in
134 `tools/testing/selftests/bpf/progs/lsm.c`_ and
135 userspace code in `tools/testing/selftests/bpf
136
137 .. Links
138 .. _tools/lib/bpf/bpf_tracing.h:
139 https://git.kernel.org/pub/scm/linux/kernel
140 .. _tools/testing/selftests/bpf/progs/lsm.c:
141 https://git.kernel.org/pub/scm/linux/kernel
142 .. _tools/testing/selftests/bpf/prog_tests/tes
143 https://git.kernel.org/pub/scm/linux/kernel
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.