doc: user mode overview documentation

The existing docs immediately dive into the details without providing
the user with any kind of high level overview or description of the
threat model.

Signed-off-by: Andrew Boie <[email protected]>

Author: Andrew Boie

doc/kernel/usermode/usermode.rst

@@ -9,6 +9,179 @@ are defined, and how memory may be managed to support user mode threads.
 For details on creating threads that run in user mode, please see
 :ref:`lifecycle_v2`.
 
+Threat Model
+============
+
+User mode threads are considered to be untrusted by Zephyr and are therefore
+isolated from other user mode threads and from the kernel. A flawed or
+malicious user mode thread cannot leak or modify the private data/resources
+of another thread or the kernel, and cannot interfere with or
+control another user mode thread or the kernel.
+
+Example use-cases of Zephyr's user mode features:
+
+- The kernel can protect against many unintentional programming errors which
+  could otherwise silently or spectacularly corrupt the system.
+
+- The kernel can sandbox complex data parsers such as interpreters, network
+  protocols, and filesystems such that malicious third-party code or data
+  cannot compromise the kernel or other threads.
+
+- The kernel can support the notion of multiple logical "applications", each
+  with their own group of threads and private data structures, which are
+  isolated from each other if one crashes or is otherwise compromised.
+
+Design Goals
+------------
+
+For threads running in a non-privileged CPU state (hereafter referred to as
+'user mode') we aim to protect against the following:
+
+- We prevent access to memory not specifically granted, or incorrect access to
+  memory that has an incompatible policy, such as attempting to write to a
+  read-only area.
+
+  - Threads are automatically granted access to their own stack memory
+    region, and all other stacks are inaccessible.
+
+  - By default, program text and read-only data are accessible to all threads
+    on read-only basis, kernel-wide. This policy may be adjusted.
+
+  - If the optional "application memory" feature is enabled, then all
+    non-kernel globals defined in the application and libraries will be
+    accessible.
+
+- We prevent use of device drivers or kernel objects not specifically granted,
+  with the permission granularity on a per object or per driver instance
+  basis.
+
+- We validate kernel or driver API calls with incorrect parameters that would
+  otherwise cause a crash or corruption of data structures private to the
+  kernel. This includes:
+
+  - Using the wrong kernel object type.
+
+  - Using parameters outside of proper bounds or with nonsensical values.
+
+  - Passing memory buffers that the calling thread does not have sufficient
+    access to read or write, depending on the semantics of the API.
+
+  - Use of kernel objects that are not in a proper initialization state.
+
+- We ensure the detection and safe handling of user mode stack overflows.
+
+- We prevent invoking system calls to functions excluded by the kernel
+  configuration.
+
+- We prevent disabling of or tampering with kernel-defined and hardware-
+  enforced memory protections.
+
+- We prevent re-entry from user to supervisor mode except through the kernel-
+  defined system calls and interrupt handlers.
+
+- We prevent the introduction of new executable code by user mode threads,
+  except to the extent to which this is supported by kernel system calls.
+
+We are specifically not protecting against the following attacks:
+
+- The kernel itself, and any threads that are executing in supervisor mode,
+  are assumed to be trusted.
+
+- The toolchain and any supplemental programs used by the build system are
+  assumed to be trusted.
+
+- The kernel build is assumed to be trusted. There is considerable build-time
+  logic for creating the tables of valid kernel objects, defining system calls,
+  and configuring interrupts. The .elf binary files that are worked with
+  during this process are all assumed to be trusted code.
+
+- We can't protect against mistakes made in memory domain configuration done in
+  kernel mode that exposes private kernel data structures to a user thread. RAM
+  for kernel objects should always be configured as supervisor-only.
+
+- It is possible to make top-level declarations of user mode threads and
+  assign them permissions to kernel objects. In general, all C and header
+  files that are part of the kernel build producing zephyr.elf are assumed to
+  be trusted.
+
+- We do not protect against denial of service attacks through thread CPU
+  starvation. Zephyr has no thread priority aging and a user thread of a
+  particular priority can starve all threads of lower priority, and also other
+  threads of the same priority if time-slicing is not enabled.
+
+- There are build-time defined limits on how many threads can be active
+  simultaneously, after which creation of new user threads will fail.
+
+- Stack overflows for threads running in supervisor mode may be caught,
+  but the integrity of the system cannot be guaranteed.
+
+High-level Policy Details
+=========================
+
+Broadly speaking, we accomplish these thread-level memory protection goals
+through the following mechanisms:
+
+- Any user thread will only have access to its own stack memory by default.
+  Access to any other RAM will need to be done on the thread's behalf through
+  system calls, or specifically granted by a supervisor thread using the
+  :ref:`memory_domain` APIs. Newly created threads inherit the memory domain
+  configuration of the parent. Threads may communicate with each other
+  by having shared membership of the same memory domains, or via kernel objects
+  such as semaphores and pipes.
+
+- If the optional :option:`CONFIG_APPLICATION_MEMORY` feature is enabled, all
+  threads will have read/write access to non-kernel globals.
+
+- User threads cannot directly access memory belonging to kernel objects.
+  Although pointers to kernel objects are used to reference them, actual
+  manipulation of kernel objects is done through system call interfaces. Device
+  drivers and threads stacks are also considered kernel objects. This ensures
+  that any data inside a kernel object that is private to the kernel cannot be
+  tampered with.
+
+- User threads by default have no permission to access any kernel object or
+  driver other than their own thread object. Such access must be granted by
+  another thread that is either in supervisor mode or has permission on both
+  the receiving thread object and the kernel object being granted access to.
+  The creation of new threads has an option to automatically inherit
+  permissions of all kernel objects granted to the parent, except the parent
+  thread itself.
+
+- For performance and footprint reasons Zephyr normally does little or no
+  parameter error checking for kernel object or device driver APIs. Access from
+  user mode through system calls involves an extra layer of handler functions,
+  which are expected to rigorously validate access permissions and type of
+  the object, check the validity of other parameters through bounds checking or
+  other means, and verify proper read/write access to any memory buffers
+  involved.
+
+- Thread stacks are defined in such a way that exceeding the specified stack
+  space will generate a hardware fault. The way this is done specifically
+  varies per architecture.
+
+Constraints
+===========
+
+All kernel objects, thread stacks, and device driver instances must be defined
+at build time if they are to be used from user mode. Dynamic use-cases for
+kernel objects will need to go through pre-defined pools of available objects.
+
+There are some constraints if additional application binary data is loaded
+for execution after the kernel starts:
+
+- Loaded object code will not be able to define any kernel objects that will be
+  recognized by the kernel. This code will instead need to use APIs for
+  requesting kernel objects from pools.
+
+- Similarly, since the loaded object code will not be part of the kernel build
+  process, this code will not be able to install interrupt handlers,
+  instantiate device drivers, or define system calls, regardless of what
+  mode it runs in.
+
+- Loaded object code that does not come from a verified source should always
+  be entered with the CPU already in user mode.
+
+
 .. toctree::
     :maxdepth: 2