From 4a02d0038fbd7a55733cf2ab7b79d82a24af0d3c Mon Sep 17 00:00:00 2001 From: William Findlay Date: Fri, 29 Oct 2021 11:49:46 -0400 Subject: [PATCH] aya-bpf/helpers: add documentation and implement all bpf_probe_read_* wrappers This patch adds some documentation to aya-bpf/helpers and adds documentation for the module itself and for all of the wrappers currently defined in the module. It also implements the rest of the bpf_probe_read_* wrappers that were missing from this file. In the future, it probably also makes sense to add some bpf_probe_read_* wrappers that can read directly into a map pointer, avoiding the BPF stack altogether. I'm going to call this out of scope for this PR, but plan to submit a subsequent one that addresses this use case. Signed-off-by: William Findlay --- bpf/aya-bpf/src/helpers.rs | 259 +++++++++++++++++++++++++++++++++++++ 1 file changed, 259 insertions(+) diff --git a/bpf/aya-bpf/src/helpers.rs b/bpf/aya-bpf/src/helpers.rs index 9424881e..34eb96bf 100644 --- a/bpf/aya-bpf/src/helpers.rs +++ b/bpf/aya-bpf/src/helpers.rs @@ -1,3 +1,12 @@ +//! This module contains kernel helper functions that may be exposed to specific BPF +//! program types. These helpers can be used to perform common tasks, query and operate on +//! data exposed by the kernel, and perform some operations that would normally be denied +//! by the BPF verifier. +//! +//! Here, we provide some higher-level wrappers around the underlying kernel helpers, but +//! also expose bindings to the underlying helpers as a fall-back in case of a missing +//! implementation. + use core::mem::{self, MaybeUninit}; pub use aya_bpf_bindings::helpers as gen; @@ -5,6 +14,31 @@ pub use gen::*; use crate::cty::{c_char, c_long, c_void}; +/// Read bytes stored at `src` and store them as a `T`. +/// +/// Generally speaking, the more specific [`bpf_probe_read_user`] and +/// [`bpf_probe_read_kernel`] should be preferred over this function. +/// +/// Returns a bitwise copy of `mem::size_of::()` bytes stored at the user space address +/// `src`. See `bpf_probe_read_kernel` for reading kernel space memory. +/// +/// # Examples +/// +/// ```no_run +/// # #![allow(dead_code)] +/// # use aya_bpf::{cty::{c_int, c_long}, helpers::bpf_probe_read}; +/// # fn try_test() -> Result<(), c_long> { +/// # let kernel_ptr: *const c_int = 0 as _; +/// let my_int: c_int = unsafe { bpf_probe_read(kernel_ptr)? }; +/// +/// // Do something with my_int +/// # Ok::<(), c_long>(()) +/// # } +/// ``` +/// +/// # Errors +/// +/// On failure, this function returns a negative value wrapped in an `Err`. #[inline] pub unsafe fn bpf_probe_read(src: *const T) -> Result { let mut v: MaybeUninit = MaybeUninit::uninit(); @@ -20,6 +54,149 @@ pub unsafe fn bpf_probe_read(src: *const T) -> Result { Ok(v.assume_init()) } +/// Read bytes stored at the _user space_ pointer `src` and store them as a `T`. +/// +/// Returns a bitwise copy of `mem::size_of::()` bytes stored at the user space address +/// `src`. See `bpf_probe_read_kernel` for reading kernel space memory. +/// +/// # Examples +/// +/// ```no_run +/// # #![allow(dead_code)] +/// # use aya_bpf::{cty::{c_int, c_long}, helpers::bpf_probe_read_user}; +/// # fn try_test() -> Result<(), c_long> { +/// # let user_ptr: *const c_int = 0 as _; +/// let my_int: c_int = unsafe { bpf_probe_read_user(user_ptr)? }; +/// +/// // Do something with my_int +/// # Ok::<(), c_long>(()) +/// # } +/// ``` +/// +/// # Errors +/// +/// On failure, this function returns a negative value wrapped in an `Err`. +#[inline] +pub unsafe fn bpf_probe_read_user(src: *const T) -> Result { + let mut v: MaybeUninit = MaybeUninit::uninit(); + let ret = gen::bpf_probe_read_user( + v.as_mut_ptr() as *mut c_void, + mem::size_of::() as u32, + src as *const c_void, + ); + if ret < 0 { + return Err(ret); + } + + Ok(v.assume_init()) +} + +/// Read bytes stored at the _kernel space_ pointer `src` and store them as a `T`. +/// +/// Returns a bitwise copy of `mem::size_of::()` bytes stored at the kernel space address +/// `src`. See `bpf_probe_read_user` for reading user space memory. +/// +/// # Examples +/// +/// ```no_run +/// # #![allow(dead_code)] +/// # use aya_bpf::{cty::{c_int, c_long}, helpers::bpf_probe_read_kernel}; +/// # fn try_test() -> Result<(), c_long> { +/// # let kernel_ptr: *const c_int = 0 as _; +/// let my_int: c_int = unsafe { bpf_probe_read_kernel(kernel_ptr)? }; +/// +/// // Do something with my_int +/// # Ok::<(), c_long>(()) +/// # } +/// ``` +/// +/// # Errors +/// +/// On failure, this function returns a negative value wrapped in an `Err`. +#[inline] +pub unsafe fn bpf_probe_read_kernel(src: *const T) -> Result { + let mut v: MaybeUninit = MaybeUninit::uninit(); + let ret = gen::bpf_probe_read_kernel( + v.as_mut_ptr() as *mut c_void, + mem::size_of::() as u32, + src as *const c_void, + ); + if ret < 0 { + return Err(ret); + } + + Ok(v.assume_init()) +} + +/// Read a null-terminated string stored at `src` into `dest`. +/// +/// Generally speaking, the more specific [`bpf_probe_read_user_str`] and +/// [`bpf_probe_read_kernel_str`] should be preferred over this function. +/// +/// In case the length of `dest` is smaller then the length of `src`, the read bytes will +/// be truncated to the size of `dest`. +/// +/// # Examples +/// +/// ```no_run +/// # #![allow(dead_code)] +/// # use aya_bpf::{cty::c_long, helpers::bpf_probe_read_str}; +/// # fn try_test() -> Result<(), c_long> { +/// # let kernel_ptr: *const u8 = 0 as _; +/// let mut my_str = [0u8; 16]; +/// let num_read = unsafe { bpf_probe_read_str(kernel_ptr, &mut my_str)? }; +/// +/// // Do something with num_read and my_str +/// # Ok::<(), c_long>(()) +/// # } +/// ``` +/// +/// # Errors +/// +/// On failure, this function returns Err(-1). +#[inline] +pub unsafe fn bpf_probe_read_str(src: *const u8, dest: &mut [u8]) -> Result { + let len = gen::bpf_probe_read_str( + dest.as_mut_ptr() as *mut c_void, + dest.len() as u32, + src as *const c_void, + ); + if len < 0 { + return Err(-1); + } + + let mut len = len as usize; + if len > dest.len() { + // this can never happen, it's needed to tell the verifier that len is + // bounded + len = dest.len(); + } + Ok(len as usize) +} + +/// Read a null-terminated string from _user space_ stored at `src` into `dest`. +/// +/// In case the length of `dest` is smaller then the length of `src`, the read bytes will +/// be truncated to the size of `dest`. +/// +/// # Examples +/// +/// ```no_run +/// # #![allow(dead_code)] +/// # use aya_bpf::{cty::c_long, helpers::bpf_probe_read_user_str}; +/// # fn try_test() -> Result<(), c_long> { +/// # let user_ptr: *const u8 = 0 as _; +/// let mut my_str = [0u8; 16]; +/// let num_read = unsafe { bpf_probe_read_user_str(user_ptr, &mut my_str)? }; +/// +/// // Do something with num_read and my_str +/// # Ok::<(), c_long>(()) +/// # } +/// ``` +/// +/// # Errors +/// +/// On failure, this function returns Err(-1). #[inline] pub unsafe fn bpf_probe_read_user_str(src: *const u8, dest: &mut [u8]) -> Result { let len = gen::bpf_probe_read_user_str( @@ -40,6 +217,65 @@ pub unsafe fn bpf_probe_read_user_str(src: *const u8, dest: &mut [u8]) -> Result Ok(len as usize) } +/// Read a null-terminated string from _kernel space_ stored at `src` into `dest`. +/// +/// In case the length of `dest` is smaller then the length of `src`, the read bytes will +/// be truncated to the size of `dest`. +/// +/// # Examples +/// +/// ```no_run +/// # #![allow(dead_code)] +/// # use aya_bpf::{cty::c_long, helpers::bpf_probe_read_kernel_str}; +/// # fn try_test() -> Result<(), c_long> { +/// # let kernel_ptr: *const u8 = 0 as _; +/// let mut my_str = [0u8; 16]; +/// let num_read = unsafe { bpf_probe_read_kernel_str(kernel_ptr, &mut my_str)? }; +/// +/// // Do something with num_read and my_str +/// # Ok::<(), c_long>(()) +/// # } +/// ``` +/// +/// # Errors +/// +/// On failure, this function returns Err(-1). +#[inline] +pub unsafe fn bpf_probe_read_kernel_str(src: *const u8, dest: &mut [u8]) -> Result { + let len = gen::bpf_probe_read_kernel_str( + dest.as_mut_ptr() as *mut c_void, + dest.len() as u32, + src as *const c_void, + ); + if len < 0 { + return Err(-1); + } + + let mut len = len as usize; + if len > dest.len() { + // this can never happen, it's needed to tell the verifier that len is + // bounded + len = dest.len(); + } + Ok(len as usize) +} + +/// Read the `comm` field associated with the current task struct +/// as a `[c_char; 16]`. +/// +/// # Examples +/// +/// ```no_run +/// # #![allow(dead_code)] +/// # use aya_bpf:: helpers::bpf_get_current_comm; +/// let comm = bpf_get_current_comm(); +/// +/// // Do something with comm +/// ``` +/// +/// # Errors +/// +/// On failure, this function returns a negative value wrapped in an `Err`. #[inline] pub fn bpf_get_current_comm() -> Result<[c_char; 16], c_long> { let mut comm: [c_char; 16usize] = [0; 16]; @@ -51,6 +287,29 @@ pub fn bpf_get_current_comm() -> Result<[c_char; 16], c_long> { } } +/// Read the process id and thread group id associated with the current task struct as +/// a `u64`. +/// +/// In the return value, the upper 32 bits are the `tgid`, and the lower 32 bits are the +/// `pid`. That is, the returned value is equal to: `(tgid << 32) | pid`. A caller may +/// access the individual fields by either casting to a `u32` or performing a `>> 32` bit +/// shift and casting to a `u32`. +/// +/// Note that the naming conventions used in the kernel differ from user space. From the +/// perspective of user space, `pid` may be thought of as the thread id, and `tgid` may be +/// thought of as the process id. For single-threaded processes, these values are +/// typically the same. +/// +/// # Examples +/// +/// ```no_run +/// # #![allow(dead_code)] +/// # use aya_bpf:: helpers::bpf_get_current_pid_tgid; +/// let tgid = (bpf_get_current_pid_tgid() >> 32) as u32; +/// let pid = bpf_get_current_pid_tgid() as u32; +/// +/// // Do something with pid and tgid +/// ``` #[inline] pub fn bpf_get_current_pid_tgid() -> u64 { unsafe { gen::bpf_get_current_pid_tgid() }