1.. SPDX-License-Identifier: GPL-2.0+ 2.. Copyright (C) 2020 Google LLC. 3 4================ 5LSM BPF Programs 6================ 7 8These BPF programs allow runtime instrumentation of the LSM hooks by privileged 9users to implement system-wide MAC (Mandatory Access Control) and Audit 10policies using eBPF. 11 12Structure 13--------- 14 15The example shows an eBPF program that can be attached to the ``file_mprotect`` 16LSM hook: 17 18.. c:function:: int file_mprotect(struct vm_area_struct *vma, unsigned long reqprot, unsigned long prot); 19 20Other LSM hooks which can be instrumented can be found in 21``security/security.c``. 22 23eBPF programs that use Documentation/bpf/btf.rst do not need to include kernel 24headers for accessing information from the attached eBPF program's context. 25They can simply declare the structures in the eBPF program and only specify 26the 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 43This can be further simplified (if one has access to the BTF information at 44build 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 54The ``vmlinux.h`` can then simply be included in the BPF programs without 55requiring the definition of the types. 56 57The eBPF programs can be declared using the``BPF_PROG`` 58macros defined in `tools/lib/bpf/bpf_tracing.h`_. In this 59example: 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 89The ``__attribute__((preserve_access_index))`` is a clang feature that allows 90the BPF verifier to update the offsets for the access at runtime using the 91Documentation/bpf/btf.rst information. Since the BPF verifier is aware of the 92types, it also validates all the accesses made to the various types in the 93eBPF program. 94 95Loading 96------- 97 98eBPF 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 108This 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 114and the program can be loaded by including ``my_prog.skel.h`` and using 115the generated helper, ``my_prog__open_and_load``. 116 117Attachment to LSM Hooks 118----------------------- 119 120The LSM allows attachment of eBPF programs as LSM hooks using :manpage:`bpf(2)` 121syscall's ``BPF_RAW_TRACEPOINT_OPEN`` operation or more simply by 122using the libbpf helper ``bpf_program__attach_lsm``. 123 124The program can be detached from the LSM hook by *destroying* the ``link`` 125link returned by ``bpf_program__attach_lsm`` using ``bpf_link__destroy``. 126 127One 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 130Examples 131-------- 132 133An example eBPF program can be found in 134`tools/testing/selftests/bpf/progs/lsm.c`_ and the corresponding 135userspace 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 144