use crate::error::{Error, Result};
use crate::import::RawImport;
use crate::module::Module;
use crate::{ImportKind, Symbol, sys};
use core::ffi::c_void;
use core::sync::atomic::{AtomicUsize, Ordering};
use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
fn install_lock() -> MutexGuard<'static, ()> {
static LOCK: Mutex<()> = Mutex::new(());
LOCK.lock().unwrap_or_else(PoisonError::into_inner)
}
unsafe fn slot_swap(slot: usize, new: usize) -> usize {
let atomic = unsafe { &*(slot as *const AtomicUsize) };
atomic.swap(new, Ordering::AcqRel)
}
unsafe fn slot_compare_exchange(
slot: usize,
expected: usize,
new: usize,
) -> core::result::Result<usize, usize> {
let atomic = unsafe { &*(slot as *const AtomicUsize) };
atomic.compare_exchange(expected, new, Ordering::AcqRel, Ordering::Acquire)
}
unsafe fn slot_load(slot: usize) -> usize {
let atomic = unsafe { &*(slot as *const AtomicUsize) };
atomic.load(Ordering::Acquire)
}
struct PageProtector {
pages: Vec<(usize, u32)>,
}
impl PageProtector {
fn make_writable(slots: &[usize]) -> Result<Self> {
let page_size = sys::page_size();
let mask = !(page_size - 1);
let mut pages: Vec<usize> = Vec::new();
for &slot in slots {
let first = slot & mask;
let last = slot.saturating_add(crate::arch::PTR_SIZE - 1) & mask;
let mut page = first;
loop {
if !pages.contains(&page) {
pages.push(page);
}
if page == last {
break;
}
page = page.saturating_add(page_size);
}
}
let mut done: Vec<(usize, u32)> = Vec::with_capacity(pages.len());
for &page in &pages {
match unsafe { sys::make_writable(page) } {
Ok(old) => done.push((page, old)),
Err(err) => {
for &(p, old) in done.iter().rev() {
let _ = unsafe { sys::restore_protection(p, old) };
}
return Err(err);
}
}
}
Ok(Self { pages: done })
}
fn restore(self) -> Result<()> {
let mut first_err = None;
for &(page, old) in self.pages.iter().rev() {
if let Err(err) = unsafe { sys::restore_protection(page, old) } {
first_err.get_or_insert(err);
}
}
first_err.map_or(Ok(()), Err)
}
}
fn apply(patches: &[(usize, usize)]) -> Result<Vec<usize>> {
let slots: Vec<usize> = patches.iter().map(|&(slot, _)| slot).collect();
let protector = PageProtector::make_writable(&slots)?;
let mut priors = Vec::with_capacity(patches.len());
for &(slot, new) in patches {
priors.push(unsafe { slot_swap(slot, new) });
}
if let Err(err) = protector.restore() {
if let Ok(reprotect) = PageProtector::make_writable(&slots) {
for (&(slot, _), &prior) in patches.iter().zip(&priors) {
unsafe {
slot_swap(slot, prior);
}
}
let _ = reprotect.restore();
}
return Err(err);
}
Ok(priors)
}
#[derive(Debug, Clone)]
pub struct ImportSlot {
module_base: usize,
library: Arc<str>,
symbol: Option<Symbol>,
version: Option<Arc<str>>,
address: usize,
kind: ImportKind,
authenticated: bool,
}
impl ImportSlot {
pub(crate) fn from_raw(module_base: usize, raw: RawImport) -> Self {
Self {
module_base,
library: raw.library,
symbol: raw.symbol,
version: raw.version,
address: raw.slot,
kind: raw.kind,
authenticated: raw.authenticated,
}
}
#[must_use]
pub fn library(&self) -> &str {
&self.library
}
#[must_use]
pub fn symbol(&self) -> Option<&Symbol> {
self.symbol.as_ref()
}
#[must_use]
pub fn version(&self) -> Option<&str> {
self.version.as_deref()
}
#[must_use]
pub fn address(&self) -> *mut *mut c_void {
self.address as *mut *mut c_void
}
#[must_use]
pub fn kind(&self) -> ImportKind {
self.kind
}
#[must_use]
pub fn is_authenticated(&self) -> bool {
self.authenticated
}
#[must_use]
pub fn protection(&self) -> u32 {
sys::query_protection(self.address)
}
#[must_use]
pub fn module_base(&self) -> *const c_void {
self.module_base as *const c_void
}
fn match_replacement(&self, replacement: &Replacement) -> Option<&Symbol> {
let symbol = self.symbol.as_ref()?;
if !library_matches(replacement.library.as_deref(), &self.library) {
return None;
}
symbol.matches(&replacement.symbol).then_some(symbol)
}
}
fn library_matches(filter: Option<&[u8]>, actual: &str) -> bool {
filter.is_none_or(|wanted| wanted.eq_ignore_ascii_case(actual.as_bytes()))
}
#[derive(Debug)]
pub struct Replacement {
pub library: Option<Vec<u8>>,
pub symbol: Symbol,
pub replacement: *const c_void,
pub required: bool,
}
impl Replacement {
#[must_use]
pub fn by_name(library: &str, symbol: &str, replacement: *const c_void) -> Self {
Self {
library: Some(library.as_bytes().to_vec()),
symbol: Symbol::name(symbol),
replacement,
required: true,
}
}
#[must_use]
pub fn by_symbol(symbol: &str, replacement: *const c_void) -> Self {
Self {
library: None,
symbol: Symbol::name(symbol),
replacement,
required: true,
}
}
#[must_use]
pub fn optional(mut self) -> Self {
self.required = false;
self
}
}
#[derive(Debug, Clone)]
pub struct InstalledHook {
library: Arc<str>,
symbol: Symbol,
slot: usize,
original: usize,
prior_value: usize,
replacement: usize,
}
impl InstalledHook {
#[must_use]
pub fn library(&self) -> &str {
&self.library
}
#[must_use]
pub fn symbol(&self) -> &Symbol {
&self.symbol
}
#[must_use]
pub fn slot(&self) -> *mut *mut c_void {
self.slot as *mut *mut c_void
}
#[must_use]
pub fn original(&self) -> *const c_void {
self.original as *const c_void
}
#[must_use]
pub fn replacement(&self) -> *const c_void {
self.replacement as *const c_void
}
}
#[derive(Debug)]
pub struct HookGuard {
module_base: usize,
hooks: Vec<InstalledHook>,
active: bool,
}
impl HookGuard {
#[must_use]
pub fn installed(&self) -> &[InstalledHook] {
&self.hooks
}
#[must_use]
pub fn original(&self, symbol: &Symbol) -> Option<*const c_void> {
self.hooks
.iter()
.find(|hook| hook.symbol.matches(symbol))
.map(InstalledHook::original)
}
pub fn uninstall(mut self) -> Result<()> {
self.restore()
}
fn restore(&mut self) -> Result<()> {
if !self.active {
return Ok(());
}
self.active = false;
if self.hooks.is_empty() {
return Ok(());
}
let _lock = install_lock();
if !sys::module_still_loaded(self.module_base) {
return Ok(());
}
let slots: Vec<usize> = self.hooks.iter().map(|hook| hook.slot).collect();
let protector = PageProtector::make_writable(&slots)?;
let mut first_err: Option<Error> = None;
for hook in &self.hooks {
if !sys::slot_belongs_to_module(hook.slot, self.module_base) {
continue;
}
match unsafe { slot_compare_exchange(hook.slot, hook.replacement, hook.prior_value) } {
Ok(_) => {}
Err(found) if found == hook.prior_value => {
}
Err(found) => {
first_err.get_or_insert(Error::RestoreConflict {
slot: hook.slot,
expected: hook.replacement,
found,
});
}
}
}
if let Err(err) = protector.restore() {
first_err.get_or_insert(err);
}
first_err.map_or(Ok(()), Err)
}
}
impl Drop for HookGuard {
fn drop(&mut self) {
let _ = self.restore();
}
}
struct PendingHook {
library: Arc<str>,
symbol: Symbol,
slot: usize,
original: usize,
replacement: usize,
}
pub fn install(module: &Module, replacements: &[Replacement]) -> Result<HookGuard> {
let _lock = install_lock();
let imports = module.imports()?;
let mut pending: Vec<PendingHook> = Vec::new();
for replacement in replacements {
let mut matched = false;
for slot in &imports {
let Some(symbol) = slot.match_replacement(replacement) else {
continue;
};
matched = true;
if slot.authenticated {
return Err(Error::AuthenticatedSlot {
module: module.name().to_owned(),
symbol: symbol.describe(),
});
}
if pending.iter().any(|hook| hook.slot == slot.address) {
continue;
}
let slot_value = unsafe { slot_load(slot.address) };
let original = match sys::resolve_original(slot.kind, &slot.library, symbol, slot_value)
{
Some(original) => original,
None if replacement.required => {
return Err(Error::OriginalUnresolved {
module: module.name().to_owned(),
library: slot.library.to_string(),
symbol: symbol.describe(),
});
}
None => continue,
};
pending.push(PendingHook {
library: slot.library.clone(),
symbol: symbol.clone(),
slot: slot.address,
original,
replacement: replacement.replacement as usize,
});
}
if !matched && replacement.required {
return Err(Error::SymbolNotFound {
module: module.name().to_owned(),
symbol: replacement.symbol.describe(),
});
}
}
if pending.is_empty() {
return Ok(HookGuard {
module_base: module.base_addr(),
hooks: Vec::new(),
active: true,
});
}
let patches: Vec<(usize, usize)> = pending
.iter()
.map(|hook| (hook.slot, hook.replacement))
.collect();
let priors = apply(&patches)?;
let hooks = pending
.into_iter()
.zip(priors)
.map(|(hook, prior_value)| InstalledHook {
library: hook.library,
symbol: hook.symbol,
slot: hook.slot,
original: hook.original,
prior_value,
replacement: hook.replacement,
})
.collect();
Ok(HookGuard {
module_base: module.base_addr(),
hooks,
active: true,
})
}
unsafe impl Send for Replacement {}
unsafe impl Sync for Replacement {}
#[cfg(test)]
#[allow(
clippy::unwrap_used,
clippy::expect_used,
clippy::indexing_slicing,
clippy::unnecessary_box_returns,
clippy::borrowed_box,
clippy::ref_as_ptr
)]
mod tests {
use super::*;
fn cell(value: usize) -> Box<usize> {
Box::new(value)
}
fn addr(cell: &Box<usize>) -> usize {
cell.as_ref() as *const usize as usize
}
#[test]
fn apply_swaps_and_reports_priors() {
let slot = cell(0x1111);
let priors = apply(&[(addr(&slot), 0x2222)]).expect("apply succeeds");
assert_eq!(priors, vec![0x1111]);
assert_eq!(*slot, 0x2222);
}
#[test]
fn apply_rolls_back_on_injected_failure() {
let good = cell(0xAAAA);
let patches = [(addr(&good), 0xBBBB), (0x1usize, 0xCCCC)];
let result = apply(&patches);
assert!(matches!(result, Err(Error::Protect { .. })));
assert_eq!(*good, 0xAAAA);
}
#[test]
fn compare_exchange_restore_detects_a_subsequent_hook() {
let slot = cell(0x1000); let a = addr(&slot);
let priors = apply(&[(a, 0x2000)]).expect("install A");
assert_eq!(priors, vec![0x1000]);
unsafe { slot_swap(a, 0x3000) };
let result = unsafe { slot_compare_exchange(a, 0x2000, 0x1000) };
assert_eq!(result, Err(0x3000));
assert_eq!(*slot, 0x3000, "subsequent hook preserved");
}
#[test]
fn library_matching_is_case_insensitive_and_optional() {
assert!(library_matches(None, "KERNEL32.dll"));
assert!(library_matches(Some(b"kernel32.DLL"), "KERNEL32.dll"));
assert!(!library_matches(Some(b"ole32.dll"), "KERNEL32.dll"));
}
}