On 04.04.24 14:31, Alice Ryhl wrote:
> diff --git a/rust/kernel/uaccess.rs b/rust/kernel/uaccess.rs
> new file mode 100644
> index 000000000000..3f8ad4dc13c4
> --- /dev/null
> +++ b/rust/kernel/uaccess.rs
> @@ -0,0 +1,311 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! Slices to user space memory regions.
> +//!
> +//! C header: [`include/linux/uaccess.h`](srctree/include/linux/uaccess.h)
> +
> +use crate::{bindings, error::code::*, error::Result};
> +use alloc::vec::Vec;
> +use core::ffi::{c_ulong, c_void};
> +use core::mem::MaybeUninit;
> +
> +/// A pointer to an area in userspace memory, which can be either read-only or
> +/// read-write.
> +///
> +/// All methods on this struct are safe: attempting to read or write on bad
> +/// addresses (either out of the bound of the slice or unmapped addresses) will
> +/// return `EFAULT`. Concurrent access, *including data races to/from userspace
> +/// memory*, is permitted, because fundamentally another userspace
> +/// thread/process could always be modifying memory at the same time (in the
> +/// same way that userspace Rust's [`std::io`] permits data races with the
> +/// contents of files on disk). In the presence of a race, the exact byte values
> +/// read/written are unspecified but the operation is well-defined. Kernelspace
> +/// code should validate its copy of data after completing a read, and not
> +/// expect that multiple reads of the same address will return the same value.
> +///
> +/// These APIs are designed to make it difficult to accidentally write TOCTOU
> +/// (time-of-check to time-of-use) bugs. Every time a memory location is read,
> +/// the reader's position is advanced by the read length and the next read will
> +/// start from there. This helps prevent accidentally reading the same location
> +/// twice and causing a TOCTOU bug.
> +///
> +/// Creating a [`UserSliceReader`] and/or [`UserSliceWriter`] consumes the
> +/// `UserSlice`, helping ensure that there aren't multiple readers or writers to
> +/// the same location.
> +///
> +/// If double-fetching a memory location is necessary for some reason, then that
> +/// is done by creating multiple readers to the same memory location, e.g. using
> +/// [`clone_reader`].
I think we should have consistent 100 column formatting. And not
something less.
> +///
> +/// # Examples
[...]
> + /// Reads raw data from the user slice into a kernel buffer.
> + ///
> + /// Fails with `EFAULT` if the read happens on a bad address.
> + pub fn read_raw(&mut self, out: &mut [MaybeUninit<u8>]) -> Result {
> + let len = out.len();
> + let out_ptr = out.as_mut_ptr().cast::<c_void>();
> + if len > self.length {
> + return Err(EFAULT);
> + }
> + let Ok(len_ulong) = c_ulong::try_from(len) else {
> + return Err(EFAULT);
> + };
> + // SAFETY: The caller promises that `out` is valid for writing `len` bytes.
This comment needs updating.
> + let res = unsafe { bindings::copy_from_user(out_ptr, self.ptr, len_ulong) };
> + if res != 0 {
> + return Err(EFAULT);
> + }
> + // Userspace pointers are not directly dereferencable by the kernel, so
> + // we cannot use `add`, which has C-style rules for defined behavior.
> + self.ptr = self.ptr.wrapping_byte_add(len);
> + self.length -= len;
> + Ok(())
> + }
> +
> + /// Reads raw data from the user slice into a kernel buffer.
> + ///
> + /// Fails with `EFAULT` if the read happens on a bad address.
> + pub fn read_slice(&mut self, out: &mut [u8]) -> Result {
> + // SAFETY: The types are compatible and `read_raw` doesn't write
> + // uninitialized bytes to `out`.
Can you add this as a guarantee to `read_raw`?
> + let out = unsafe { &mut *(out as *mut [u8] as *mut [MaybeUninit<u8>]) };
> + self.read_raw(out)
> + }
> +
> + /// Reads the entirety of the user slice, appending it to the end of the
> + /// provided buffer.
> + ///
> + /// Fails with `EFAULT` if the read happens on a bad address.
> + pub fn read_all(mut self, buf: &mut Vec<u8>) -> Result {
> + let len = self.length;
> + buf.try_reserve(len)?;
> +
> + // The call to `try_reserve` was successful, so the spare capacity is at
> + // least `len` bytes long.
> + self.read_raw(&mut buf.spare_capacity_mut()[..len])?;
> +
> + // SAFETY: Since the call to `read_raw` was successful, so the next
> + // `len` bytes of the vector have been initialized.
> + unsafe { buf.set_len(buf.len() + len) };
> + Ok(())
> + }
> +}
> +
> +/// A writer for [`UserSlice`].
> +///
> +/// Used to incrementally write into the user slice.
> +pub struct UserSliceWriter {
> + ptr: *mut c_void,
> + length: usize,
> +}
> +
> +impl UserSliceWriter {
> + /// Returns the amount of space remaining in this buffer.
> + ///
> + /// Note that even writing less than this number of bytes may fail.
> + pub fn len(&self) -> usize {
> + self.length
> + }
> +
> + /// Returns `true` if no more data can be written to this buffer.
> + pub fn is_empty(&self) -> bool {
> + self.length == 0
> + }
> +
> + /// Writes raw data to this user pointer from a kernel buffer.
> + ///
> + /// Fails with `EFAULT` if the write happens on a bad address.
> + pub fn write_slice(&mut self, data: &[u8]) -> Result {
> + let len = data.len();
> + let data_ptr = data.as_ptr().cast::<c_void>();
> + if len > self.length {
> + return Err(EFAULT);
> + }
> + let Ok(len_ulong) = c_ulong::try_from(len) else {
> + return Err(EFAULT);
> + };
> + let res = unsafe { bindings::copy_to_user(self.ptr, data_ptr, len_ulong) };
Missing SAFETY comment.
--
Cheers,
Benno
> + if res != 0 {
> + return Err(EFAULT);
> + }
> + // Userspace pointers are not directly dereferencable by the kernel, so
> + // we cannot use `add`, which has C-style rules for defined behavior.
> + self.ptr = self.ptr.wrapping_byte_add(len);
> + self.length -= len;
> + Ok(())
> + }
> +}
>
> --
> 2.44.0.478.gd926399ef9-goog
>
