| .. _usermode: |
| |
| User Mode |
| ######### |
| |
| This section describes access policies for kernel objects, how system calls |
| 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. |
| |
| - 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 |
| |
| kernelobjects.rst |
| syscalls.rst |
| memory_domain.rst |
| mpu_stack_objects.rst |
| mpu_userspace.rst |
| usermode_sharedmem.rst |