[PATCH v2 0/2]: Documentation/admin-guide: introduce perf-security.rst file and extend perf_event_paranoid documentation

[PATCH v2 0/2]: Documentation/admin-guide: introduce perf-security.rst file and extend perf_event_paranoid documentation

[Alexey Budankov]

To facilitate informed decision making by system administrators [1]
to permit and manage access to Perf Events (PE) / Perf tool (Perf) [2],[3] 
performance monitoring for multiple users perf-security.rst document 
suggested by Thomas Gleixner is introduced [4] that:

a) states PE/Perf access security concerns for multi user environment
b) refers to base Linux access control and management principles
c) extends documentation of possible perf_event_paranoid knob settings 

The file serves as single knowledge source for PE/Perf security and 
access control related matter according to decisions, discussion and  
PoC prototype previously made here [5],[6].

The file can later be extended with information describing:

a) PE/Perf usage models and its security implications
b) PE/Perf user interface, its changes and related security implications
c) security related implications of monitoring by a specific PE PMU [2]

---
Alexey Budankov (2):
  Documentation/admin-guide: introduce perf-security.rst file
  Documentation/admin-guide: update admin-guide index.rst

 Documentation/admin-guide/index.rst         |  1 +
 Documentation/admin-guide/perf-security.rst | 76 +++++++++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 Documentation/admin-guide/perf-security.rst

---
Changes in v2:
- reverted patches order in the set to avoid CI issue
- replaced old PCL referencing by PE (Perf Events)
- skipped >=3 setting documentation at the moment

---
[1] https://marc.info/?l=linux-kernel&m=153815883923913&w=2
[2] http://man7.org/linux/man-pages/man2/perf_event_open.2.html
[3] https://perf.wiki.kernel.org/index.php/Main_Page
[4] https://marc.info/?l=linux-kernel&m=153837512226838&w=2
[5] https://marc.info/?l=linux-kernel&m=153736008310781&w=2
[6] https://lkml.org/lkml/2018/5/21/156

[PATCH v2 1/2] Documentation/admin-guide: introduce perf-security.rst file

[Alexey Budankov]

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@linutronix.de>
Signed-off-by: Alexey Budankov <alexey.budankov@linux.intel.com>
---
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>`_
+

[PATCH v2 2/2] Documentation/admin-guide: update admin-guide index.rst

[Alexey Budankov]

Extend index.rst index file at admin-guide root directory with
the reference to perf-security.rst file being introduced.

Signed-off-by: Alexey Budankov <alexey.budankov@linux.intel.com>
---
 Documentation/admin-guide/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 965745d5fb9a..0a491676685e 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -76,6 +76,7 @@ configure specific aspects of kernel behavior to your liking.
    thunderbolt
    LSM/index
    mm/index
+   perf-security
 
 .. only::  subproject and html

[PATCH v2 2/2] Documentation/admin-guide: update admin-guide index.rst

[Alexey Budankov]

Extend index.rst index file at admin-guide root directory with
the reference to perf-security.rst file being introduced.

Signed-off-by: Alexey Budankov <alexey.budankov@linux.intel.com>
---
 Documentation/admin-guide/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 965745d5fb9a..0a491676685e 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -76,6 +76,7 @@ configure specific aspects of kernel behavior to your liking.
    thunderbolt
    LSM/index
    mm/index
+   perf-security
 
 .. only::  subproject and html