linux/Documentation/bpf/prog_lsm.rst
Randy Dunlap 6d2ed65318 lsm: move hook comments docs to security/security.c
Fix one kernel-doc warning, but invesigating that led to other
kernel-doc movement (lsm_hooks.h to security.c) that needs to be
fixed also.

include/linux/lsm_hooks.h:1: warning: no structured comments found

Fixes: e261301c85 ("lsm: move the remaining LSM hook comments to security/security.c")
Fixes: 1cd2aca64a ("lsm: move the io_uring hook comments to security/security.c")
Fixes: 452b670c72 ("lsm: move the perf hook comments to security/security.c")
Fixes: 55e853201a ("lsm: move the bpf hook comments to security/security.c")
Fixes: b14faf9c94 ("lsm: move the audit hook comments to security/security.c")
Fixes: 1427ddbe5c ("lsm: move the binder hook comments to security/security.c")
Fixes: 43fad28218 ("lsm: move the sysv hook comments to security/security.c")
Fixes: ecc419a445 ("lsm: move the key hook comments to security/security.c")
Fixes: 742b99456e ("lsm: move the xfrm hook comments to security/security.c")
Fixes: ac318aed54 ("lsm: move the Infiniband hook comments to security/security.c")
Fixes: 4a49f592e9 ("lsm: move the SCTP hook comments to security/security.c")
Fixes: 6b6bbe8c02 ("lsm: move the socket hook comments to security/security.c")
Fixes: 2c2442fd46 ("lsm: move the AF_UNIX hook comments to security/security.c")
Fixes: 2bcf51bf2f ("lsm: move the netlink hook comments to security/security.c")
Fixes: 130c53bfee ("lsm: move the task hook comments to security/security.c")
Fixes: a0fd6480de ("lsm: move the file hook comments to security/security.c")
Fixes: 9348944b77 ("lsm: move the kernfs hook comments to security/security.c")
Fixes: 916e32584d ("lsm: move the inode hook comments to security/security.c")
Fixes: 08526a902c ("lsm: move the filesystem hook comments to security/security.c")
Fixes: 36819f1855 ("lsm: move the fs_context hook comments to security/security.c")
Fixes: 1661372c91 ("lsm: move the program execution hook comments to security/security.c")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Paul Moore <paul@paul-moore.com>
Cc: James Morris <jmorris@namei.org>
Cc: "Serge E. Hallyn" <serge@hallyn.com>
Cc: linux-security-module@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: KP Singh <kpsingh@kernel.org>
Cc: bpf@vger.kernel.org
Signed-off-by: Paul Moore <paul@paul-moore.com>
2023-04-28 11:58:34 -04:00

144 lines
4.5 KiB
ReStructuredText

.. SPDX-License-Identifier: GPL-2.0+
.. Copyright (C) 2020 Google LLC.
================
LSM BPF Programs
================
These BPF programs allow runtime instrumentation of the LSM hooks by privileged
users to implement system-wide MAC (Mandatory Access Control) and Audit
policies using eBPF.
Structure
---------
The example shows an eBPF program that can be attached to the ``file_mprotect``
LSM hook:
.. c:function:: int file_mprotect(struct vm_area_struct *vma, unsigned long reqprot, unsigned long prot);
Other LSM hooks which can be instrumented can be found in
``security/security.c``.
eBPF programs that use Documentation/bpf/btf.rst do not need to include kernel
headers for accessing information from the attached eBPF program's context.
They can simply declare the structures in the eBPF program and only specify
the fields that need to be accessed.
.. code-block:: c
struct mm_struct {
unsigned long start_brk, brk, start_stack;
} __attribute__((preserve_access_index));
struct vm_area_struct {
unsigned long start_brk, brk, start_stack;
unsigned long vm_start, vm_end;
struct mm_struct *vm_mm;
} __attribute__((preserve_access_index));
.. note:: The order of the fields is irrelevant.
This can be further simplified (if one has access to the BTF information at
build time) by generating the ``vmlinux.h`` with:
.. code-block:: console
# bpftool btf dump file <path-to-btf-vmlinux> format c > vmlinux.h
.. note:: ``path-to-btf-vmlinux`` can be ``/sys/kernel/btf/vmlinux`` if the
build environment matches the environment the BPF programs are
deployed in.
The ``vmlinux.h`` can then simply be included in the BPF programs without
requiring the definition of the types.
The eBPF programs can be declared using the``BPF_PROG``
macros defined in `tools/lib/bpf/bpf_tracing.h`_. In this
example:
* ``"lsm/file_mprotect"`` indicates the LSM hook that the program must
be attached to
* ``mprotect_audit`` is the name of the eBPF program
.. code-block:: c
SEC("lsm/file_mprotect")
int BPF_PROG(mprotect_audit, struct vm_area_struct *vma,
unsigned long reqprot, unsigned long prot, int ret)
{
/* ret is the return value from the previous BPF program
* or 0 if it's the first hook.
*/
if (ret != 0)
return ret;
int is_heap;
is_heap = (vma->vm_start >= vma->vm_mm->start_brk &&
vma->vm_end <= vma->vm_mm->brk);
/* Return an -EPERM or write information to the perf events buffer
* for auditing
*/
if (is_heap)
return -EPERM;
}
The ``__attribute__((preserve_access_index))`` is a clang feature that allows
the BPF verifier to update the offsets for the access at runtime using the
Documentation/bpf/btf.rst information. Since the BPF verifier is aware of the
types, it also validates all the accesses made to the various types in the
eBPF program.
Loading
-------
eBPF programs can be loaded with the :manpage:`bpf(2)` syscall's
``BPF_PROG_LOAD`` operation:
.. code-block:: c
struct bpf_object *obj;
obj = bpf_object__open("./my_prog.o");
bpf_object__load(obj);
This can be simplified by using a skeleton header generated by ``bpftool``:
.. code-block:: console
# bpftool gen skeleton my_prog.o > my_prog.skel.h
and the program can be loaded by including ``my_prog.skel.h`` and using
the generated helper, ``my_prog__open_and_load``.
Attachment to LSM Hooks
-----------------------
The LSM allows attachment of eBPF programs as LSM hooks using :manpage:`bpf(2)`
syscall's ``BPF_RAW_TRACEPOINT_OPEN`` operation or more simply by
using the libbpf helper ``bpf_program__attach_lsm``.
The program can be detached from the LSM hook by *destroying* the ``link``
link returned by ``bpf_program__attach_lsm`` using ``bpf_link__destroy``.
One can also use the helpers generated in ``my_prog.skel.h`` i.e.
``my_prog__attach`` for attachment and ``my_prog__destroy`` for cleaning up.
Examples
--------
An example eBPF program can be found in
`tools/testing/selftests/bpf/progs/lsm.c`_ and the corresponding
userspace code in `tools/testing/selftests/bpf/prog_tests/test_lsm.c`_
.. Links
.. _tools/lib/bpf/bpf_tracing.h:
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/lib/bpf/bpf_tracing.h
.. _tools/testing/selftests/bpf/progs/lsm.c:
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/bpf/progs/lsm.c
.. _tools/testing/selftests/bpf/prog_tests/test_lsm.c:
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/bpf/prog_tests/test_lsm.c