From: Roberto Sassu roberto.sassu@huawei.com
Add a documentation, to explain the motivation behind the new component, to describe the software architecture, the API and an example used for testing.
Signed-off-by: Roberto Sassu roberto.sassu@huawei.com --- Documentation/driver-api/index.rst | 1 + Documentation/driver-api/umd_mgmt.rst | 99 +++++++++++++++++++++++++++ MAINTAINERS | 1 + 3 files changed, 101 insertions(+) create mode 100644 Documentation/driver-api/umd_mgmt.rst
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index ff9aa1afdc6..ad42cd968dc 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -113,6 +113,7 @@ available subsections can be seen below. xillybus zorro hte/index + umd_mgmt
.. only:: subproject and html
diff --git a/Documentation/driver-api/umd_mgmt.rst b/Documentation/driver-api/umd_mgmt.rst new file mode 100644 index 00000000000..7dbb50b3643 --- /dev/null +++ b/Documentation/driver-api/umd_mgmt.rst @@ -0,0 +1,99 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================== +User Mode Driver Management Library +=================================== + +:Author: Roberto Sassu, Huawei Technologies Duesseldorf GmbH +:Date: 2023-03-16 + +Introduction +============ + +The idea of moving code away from the kernel and running it in user space +is not new. For example, the User Space I/O driver model allows developers +to implement most of the driver logic in user space, and keep only a small +part in a kernel module, for example to handle interrupts. + +The User Mode Driver (UMD) is a more specialized solution, primarily used +by bpfilter, consisting of a user space process running from code embedded +in a kernel module, communicating only through a pipe with the kernel. + +The kernel makes a request, possibly originated by the user of the system, +and sends it to the user space process. The latter handles the kernel +request, and sends the response back to the kernel. Finally, the kernel +eventually forwards the result to the user. + +This usage model is particularly interesting for security. The kernel can +offload to user space workloads that could introduce possible threats, for +example parsing unknown and possibly malicious data. While the kernel +already does that, it is important to limit to the minimum the chances of +an attacker to exploit a vulnerability in the kernel code. + +If a user space process becomes corrupted, it can still send malicious data +to the kernel, but it won't be able to directly corrupt the kernel memory. +In addition, if the communication protocol between the user space process +and the kernel is simple enough, malicious data can be effectively +sanitized. + +The purpose of this library is simply to facilitate developers to create +UMDs and to help them customize the UMDs to their needs. + + + +Architecture +============ + +The architecture of the UMD library is as follows: + +:: + + +-----------+ +---------------+ + | UMD | 2. request module | UMD Loader | + | Manager |------------------->| (kmod + | + | |------+ | user binary) | + +-----------+ | +---------------+ + ^ | | kernel space + -------------------------------------------------------------------------- + | | 4. send/ v 3. fork/execve/pipe user space + | | receive +-------------+ + 1. user request +------------>| UMD Handler | + | (exec user | + | binary) | + +-------------+ + +The `UMD Manager` is the frontend interface to any user or +kernel-originated request. It invokes the `UMD Loader` to start the +`UMD Handler`, and communicates with the latter to satisfy the request. + +The `UMD Loader` is merely responsible to extract the `user binary` from +the kernel module, copy it to a tmpfs filesystem, fork the current process, +start the `UMD Handler`, and create a pipe for the communication between +the `UMD Manager` and the `UMD Handler`. + +The `UMD Handler` reads requests from the `UMD Manager`, processes them +internally, and sends the response to it. + + +API +=== + +.. kernel-doc:: include/linux/usermode_driver_mgmt.h + +.. kernel-doc:: kernel/usermode_driver_mgmt.c + + +Example +======= + +An example of usage of the UMD management library can be found in +tools/testing/selftests/umd_mgmt/sample_umd. + +sample_mgr.c implements the `UMD Manager`, sample_loader.c implements the +`UMD Loader` and, finally, sample_handler.c implements the `UMD Handler`. + +The `UMD Manager` exposes /sys/kernel/security/sample_umd and accepts a +number between 0-128K intended as an offset in the response buffer, at +which the `UMD Handler` sets the byte to 1. The `UMD Manager` verifies +that. If the byte is not set to 1, the `UMD Manager` rejects the write, so +that the failure can be reported by the test. diff --git a/MAINTAINERS b/MAINTAINERS index a0cd161843e..4b9d251259d 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -11249,6 +11249,7 @@ KERNEL USERMODE DRIVER MANAGEMENT M: Roberto Sassu roberto.sassu@huawei.com L: linux-kernel@vger.kernel.org S: Maintained +F: Documentation/driver-api/umd_mgmt.rst F: include/linux/usermode_driver_mgmt.h F: kernel/usermode_driver_mgmt.c F: tools/testing/selftests/umd_mgmt/*