1.. _usermode_overview:
2
3Overview
4########
5
6Threat Model
7************
8
9User mode threads are considered to be untrusted by Zephyr and are therefore
10isolated from other user mode threads and from the kernel. A flawed or
11malicious user mode thread cannot leak or modify the private data/resources
12of another thread or the kernel, and cannot interfere with or
13control another user mode thread or the kernel.
14
15Example use-cases of Zephyr's user mode features:
16
17- The kernel can protect against many unintentional programming errors which
18  could otherwise silently or spectacularly corrupt the system.
19
20- The kernel can sandbox complex data parsers such as interpreters, network
21  protocols, and filesystems such that malicious third-party code or data
22  cannot compromise the kernel or other threads.
23
24- The kernel can support the notion of multiple logical "applications", each
25  with their own group of threads and private data structures, which are
26  isolated from each other if one crashes or is otherwise compromised.
27
28Design Goals
29============
30
31For threads running in a non-privileged CPU state (hereafter referred to as
32'user mode') we aim to protect against the following:
33
34- We prevent access to memory not specifically granted, or incorrect access to
35  memory that has an incompatible policy, such as attempting to write to a
36  read-only area.
37
38  - Access to thread stack buffers will be controlled with a policy which
39    partially depends on the underlying memory protection hardware.
40
41    - A user thread will by default have read/write access to its own stack
42      buffer.
43
44    - A user thread will never by default have access to user thread stacks
45      that are not members of the same memory domain.
46
47    - A user thread will never by default have access to thread stacks owned
48      by a supervisor thread, or thread stacks used to handle system call
49      privilege elevations, interrupts, or CPU exceptions.
50
51    - A user thread may have read/write access to the stacks of other user
52      threads in the same memory domain, depending on hardware.
53
54       - On MPU systems, threads may only access their own stack buffer.
55
56       - On MMU systems, threads may access any user thread stack in the same
57         memory domain. Portable code should not assume this.
58
59  - By default, program text and read-only data are accessible to all threads
60    on read-only basis, kernel-wide. This policy may be adjusted.
61
62  - User threads by default are not granted default access to any memory
63    except what is noted above.
64
65- We prevent use of device drivers or kernel objects not specifically granted,
66  with the permission granularity on a per object or per driver instance
67  basis.
68
69- We validate kernel or driver API calls with incorrect parameters that would
70  otherwise cause a crash or corruption of data structures private to the
71  kernel. This includes:
72
73  - Using the wrong kernel object type.
74
75  - Using parameters outside of proper bounds or with nonsensical values.
76
77  - Passing memory buffers that the calling thread does not have sufficient
78    access to read or write, depending on the semantics of the API.
79
80  - Use of kernel objects that are not in a proper initialization state.
81
82- We ensure the detection and safe handling of user mode stack overflows.
83
84- We prevent invoking system calls to functions excluded by the kernel
85  configuration.
86
87- We prevent disabling of or tampering with kernel-defined and
88  hardware-enforced memory protections.
89
90- We prevent re-entry from user to supervisor mode except through the
91  kernel-defined system calls and interrupt handlers.
92
93- We prevent the introduction of new executable code by user mode threads,
94  except to the extent to which this is supported by kernel system calls.
95
96We are specifically not protecting against the following attacks:
97
98- The kernel itself, and any threads that are executing in supervisor mode,
99  are assumed to be trusted.
100
101- The toolchain and any supplemental programs used by the build system are
102  assumed to be trusted.
103
104- The kernel build is assumed to be trusted. There is considerable build-time
105  logic for creating the tables of valid kernel objects, defining system calls,
106  and configuring interrupts. The .elf binary files that are worked with
107  during this process are all assumed to be trusted code.
108
109- We can't protect against mistakes made in memory domain configuration done in
110  kernel mode that exposes private kernel data structures to a user thread. RAM
111  for kernel objects should always be configured as supervisor-only.
112
113- It is possible to make top-level declarations of user mode threads and
114  assign them permissions to kernel objects. In general, all C and header
115  files that are part of the kernel build producing zephyr.elf are assumed to
116  be trusted.
117
118- We do not protect against denial of service attacks through thread CPU
119  starvation. Zephyr has no thread priority aging and a user thread of a
120  particular priority can starve all threads of lower priority, and also other
121  threads of the same priority if time-slicing is not enabled.
122
123- There are build-time defined limits on how many threads can be active
124  simultaneously, after which creation of new user threads will fail.
125
126- Stack overflows for threads running in supervisor mode may be caught,
127  but the integrity of the system cannot be guaranteed.
128
129High-level Policy Details
130*************************
131
132Broadly speaking, we accomplish these thread-level memory protection goals
133through the following mechanisms:
134
135- Any user thread will only have access to a subset of memory:
136  typically its stack, program text, read-only data, and any partitions
137  configured in the :ref:`memory_domain` it belongs to. Access to any other RAM
138  must be done on the thread's behalf through system calls, or specifically
139  granted by a supervisor thread using the memory domain APIs. Newly created
140  threads inherit the memory domain configuration of the parent. Threads may
141  communicate with each other by having shared membership of the same memory
142  domains, or via kernel objects such as semaphores and pipes.
143
144- User threads cannot directly access memory belonging to kernel objects.
145  Although pointers to kernel objects are used to reference them, actual
146  manipulation of kernel objects is done through system call interfaces. Device
147  drivers and threads stacks are also considered kernel objects. This ensures
148  that any data inside a kernel object that is private to the kernel cannot be
149  tampered with.
150
151- User threads by default have no permission to access any kernel object or
152  driver other than their own thread object. Such access must be granted by
153  another thread that is either in supervisor mode or has permission on both
154  the receiving thread object and the kernel object being granted access to.
155  The creation of new threads has an option to automatically inherit
156  permissions of all kernel objects granted to the parent, except the parent
157  thread itself.
158
159- For performance and footprint reasons Zephyr normally does little or no
160  parameter error checking for kernel object or device driver APIs. Access from
161  user mode through system calls involves an extra layer of handler functions,
162  which are expected to rigorously validate access permissions and type of
163  the object, check the validity of other parameters through bounds checking or
164  other means, and verify proper read/write access to any memory buffers
165  involved.
166
167- Thread stacks are defined in such a way that exceeding the specified stack
168  space will generate a hardware fault. The way this is done specifically
169  varies per architecture.
170
171Constraints
172***********
173
174All kernel objects, thread stacks, and device driver instances must be defined
175at build time if they are to be used from user mode. Dynamic use-cases for
176kernel objects will need to go through pre-defined pools of available objects.
177
178There are some constraints if additional application binary data is loaded
179for execution after the kernel starts:
180
181- Loaded object code will not be able to define any kernel objects that will be
182  recognized by the kernel. This code will instead need to use APIs for
183  requesting kernel objects from pools.
184
185- Similarly, since the loaded object code will not be part of the kernel build
186  process, this code will not be able to install interrupt handlers,
187  instantiate device drivers, or define system calls, regardless of what
188  mode it runs in.
189
190- Loaded object code that does not come from a verified source should always
191  be entered with the CPU already in user mode.
192