Re: [PATCH v3 1/4] rust: uaccess: add userspace pointers

[Boqun Feng <boqun.feng@gmail.com>]

On Mon, Mar 11, 2024 at 10:47:13AM +0000, Alice Ryhl wrote:
> From: Wedson Almeida Filho <wedsonaf@gmail.com>
> 
[...]
> +/// # Examples
> +///
> +/// Takes a region of userspace memory from the current process, and modify it
> +/// by adding one to every byte in the region.
> +///
> +/// ```no_run
> +/// use alloc::vec::Vec;
> +/// use core::ffi::c_void;
> +/// use kernel::error::Result;
> +/// use kernel::uaccess::UserSlice;
> +///
> +/// pub fn bytes_add_one(uptr: *mut c_void, len: usize) -> Result<()> {

I hit the following compile error when trying to run kunit test:

	ERROR:root:error: unreachable `pub` item
	    --> rust/doctests_kernel_generated.rs:4167:1
	     |
	4167 | pub fn bytes_add_one(uptr: *mut c_void, len: usize) -> Result<()> {
	     | ---^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
	     | |
	     | help: consider restricting its visibility: `pub(crate)`
	     |
	     = help: or consider exporting it for use by other crates
	     = note: requested on the command line with `-D unreachable-pub`

	error: unreachable `pub` item
	    --> rust/doctests_kernel_generated.rs:4243:1
	     |
	4243 | pub fn get_bytes_if_valid(uptr: *mut c_void, len: usize) -> Result<Vec<u8>> {
	     | ---^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
	     | |
	     | help: consider restricting its visibility: `pub(crate)`
	     |
	     = help: or consider exporting it for use by other crates

	error: aborting due to 2 previous errors

, which should be fixed if we make the function in the example not
`pub`.

> +///     let (read, mut write) = UserSlice::new(uptr, len).reader_writer();
> +///
> +///     let mut buf = Vec::new();
> +///     read.read_all(&mut buf)?;
> +///
> +///     for b in &mut buf {
> +///         *b = b.wrapping_add(1);
> +///     }
> +///
> +///     write.write_slice(&buf)?;
> +///     Ok(())
> +/// }
> +/// ```
> +///
> +/// Example illustrating a TOCTOU (time-of-check to time-of-use) bug.
> +///
> +/// ```no_run
> +/// use alloc::vec::Vec;
> +/// use core::ffi::c_void;
> +/// use kernel::error::{code::EINVAL, Result};
> +/// use kernel::uaccess::UserSlice;
> +///
> +/// /// Returns whether the data in this region is valid.
> +/// fn is_valid(uptr: *mut c_void, len: usize) -> Result<bool> {
> +///     let read = UserSlice::new(uptr, len).reader();
> +///
> +///     let mut buf = Vec::new();
> +///     read.read_all(&mut buf)?;
> +///
> +///     todo!()
> +/// }
> +///
> +/// /// Returns the bytes behind this user pointer if they are valid.
> +/// pub fn get_bytes_if_valid(uptr: *mut c_void, len: usize) -> Result<Vec<u8>> {

Ditto here.

> +///     if !is_valid(uptr, len)? {
> +///         return Err(EINVAL);
> +///     }
> +///
> +///     let read = UserSlice::new(uptr, len).reader();
> +///
> +///     let mut buf = Vec::new();
> +///     read.read_all(&mut buf)?;
> +///
> +///     // THIS IS A BUG! The bytes could have changed since we checked them.
> +///     //
> +///     // To avoid this kind of bug, don't call `UserSlice::new` multiple
> +///     // times with the same address.
> +///     Ok(buf)
> +/// }
> +/// ```
> +///
> +/// [`std::io`]: https://doc.rust-lang.org/std/io/index.html
> +/// [`clone_reader`]: UserSliceReader::clone_reader
> +pub struct UserSlice {
> +    ptr: *mut c_void,
> +    length: usize,
> +}
> +

Regards,
Boqun

[...]