Implement initial version of perf-security.rst documentation file initially covering security concerns related to PE/Perf performance monitoring in multiuser environments. Suggested-by: Thomas Gleixner <tglx@xxxxxxxxxxxxx> Signed-off-by: Alexey Budankov <alexey.budankov@xxxxxxxxxxxxxxx> --- Changes in v2: - replaced old PCL referencing by PE (Perf Events) - skipped >=3 setting documentation at the moment --- Documentation/admin-guide/perf-security.rst | 76 +++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 Documentation/admin-guide/perf-security.rst diff --git a/Documentation/admin-guide/perf-security.rst b/Documentation/admin-guide/perf-security.rst new file mode 100644 index 000000000000..d9dcea61ed87 --- /dev/null +++ b/Documentation/admin-guide/perf-security.rst @@ -0,0 +1,76 @@ +.. _perf_security: + +Perf Events and tool security +============================= + +Overview +-------- + +Usage of Perf Events (PE) [1]_ , [2]_ , [3]_ can impose a considerable risk of +leaking sensitive data accessed by monitored processes. The data leakage is +possible both in scenarios of direct usage of PE system call API [2]_ and over +data files generated by Perf tool user mode utility (Perf) [3]_ , [4]_ . The risk +depends on the nature of data that PE performance monitoring units (PMU) [2]_ +collect and expose for performance analysis. Having that said PE/Perf performance +monitoring is the subject for security access control management [5]_ . + +PE/Perf access control +---------------------- + +For the purpose of performing security checks Linux implementation splits +processes into two categories [6]_ : a) privileged processes (whose effective +user ID is 0, referred to as superuser or root), and b) unprivileged processes +(whose effective UID is nonzero). Privileged processes bypass all kernel +security permission checks so PE performance monitoring is fully available to +privileged processes without *access*, *scope* and *resource* restrictions. +Unprivileged processes are subject to full security permission check based +on the process's credentials [5]_ (usually: effective UID, effective GID, +and supplementary group list). + +PE/Perf unprivileged users +-------------------------- + +PE/Perf *scope* and *access* control for unprivileged processes is governed by +perf_event_paranoid [2]_ setting: + +-1: + Impose no *scope* and *access* restrictions on using PE performance + monitoring. Per-user per-cpu perf_event_mlock_kb [2]_ locking limit is + ignored when allocating memory buffers for storing performance data. + This is the least secure mode since allowed monitored *scope* is + maximized and no PE specific limits are imposed on *resources* + allocated for performance monitoring. + +>=0: + *scope* includes per-process and system wide performance monitoring + but excludes raw tracepoints and ftrace function tracepoints monitoring. + CPU and system events happened when executing either in user or + in kernel space can be monitored and captured for later analysis. + Per-user per-cpu perf_event_mlock_kb locking limit is imposed but + ignored for unprivileged processes with CAP_IPC_LOCK [6]_ capability. + +>=1: + *scope* includes per-process performance monitoring only and excludes + system wide performance monitoring. CPU and system events happened when + executing either in user or in kernel space can be monitored and + captured for later analysis. Per-user per-cpu perf_event_mlock_kb + locking limit is imposed but ignored for unprivileged processes with + CAP_IPC_LOCK capability. + +>=2: + *scope* includes per-process performance monitoring only. CPU and system + events happened when executing in user space only can be monitored and + captured for later analysis. Per-user per-cpu perf_event_mlock_kb + locking limit is imposed but ignored for unprivileged processes with + CAP_IPC_LOCK capability. + +Bibliography +------------ + +.. [1] `<https://lwn.net/Articles/337493/>`_ +.. [2] `<http://man7.org/linux/man-pages/man2/perf_event_open.2.html>`_ +.. [3] `<http://web.eece.maine.edu/~vweaver/projects/perf_events/>`_ +.. [4] `<https://perf.wiki.kernel.org/index.php/Main_Page>`_ +.. [5] `<https://www.kernel.org/doc/html/latest/security/credentials.html>`_ +.. [6] `<http://man7.org/linux/man-pages/man7/capabilities.7.html>`_ +
