Struct UserSlice

pub struct UserSlice { /* private fields */ }

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.

Examples

Takes a region of userspace memory from the current process, and modify it by adding one to every byte in the region.

use kernel::ffi::c_void;
use kernel::error::Result;
use kernel::uaccess::{UserPtr, UserSlice};

fn bytes_add_one(uptr: UserPtr, len: usize) -> Result<()> {
    let (read, mut write) = UserSlice::new(uptr, len).reader_writer();

    let mut buf = KVec::new();
    read.read_all(&mut buf, GFP_KERNEL)?;

    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.

use kernel::ffi::c_void;
use kernel::error::{code::EINVAL, Result};
use kernel::uaccess::{UserPtr, UserSlice};

/// Returns whether the data in this region is valid.
fn is_valid(uptr: UserPtr, len: usize) -> Result<bool> {
    let read = UserSlice::new(uptr, len).reader();

    let mut buf = KVec::new();
    read.read_all(&mut buf, GFP_KERNEL)?;

    todo!()
}

/// Returns the bytes behind this user pointer if they are valid.
fn get_bytes_if_valid(uptr: UserPtr, len: usize) -> Result<KVec<u8>> {
    if !is_valid(uptr, len)? {
        return Err(EINVAL);
    }

    let read = UserSlice::new(uptr, len).reader();

    let mut buf = KVec::new();
    read.read_all(&mut buf, GFP_KERNEL)?;

    // 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)
}

Implementations

impl UserSlice

pub fn new(ptr: UserPtr, length: usize) -> Self

Constructs a user slice from a raw pointer and a length in bytes.

Constructing a UserSlice performs no checks on the provided address and length, it can safely be constructed inside a kernel thread with no current userspace process. Reads and writes wrap the kernel APIs copy_from_user and copy_to_user, which check the memory map of the current process and enforce that the address range is within the user range (no additional calls to access_ok are needed). Validity of the pointer is checked when you attempt to read or write, not in the call to UserSlice::new.

Callers must be careful to avoid time-of-check-time-of-use (TOCTOU) issues. The simplest way is to create a single instance of UserSlice per user memory block as it reads each byte at most once.

pub fn read_all(self, buf: &mut KVec<u8>, flags: Flags) -> Result

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 reader(self) -> UserSliceReader

Constructs a UserSliceReader.

pub fn writer(self) -> UserSliceWriter

Constructs a UserSliceWriter.

pub fn reader_writer(self) -> (UserSliceReader, UserSliceWriter)

Constructs both a UserSliceReader and a UserSliceWriter.

Usually when this is used, you will first read the data, and then overwrite it afterwards.