plthook/slot.rs
1//! Import slots, replacements, the installed-hook guard, and the transactional
2//!
3//! This module is platform-agnostic apart from the two protection primitives it
4//! calls in [`crate::sys`] (`make_writable` / `restore_protection`) and the
5//! original-symbol resolver. The transaction — resolve-all-first, page-batched
6//! protection changes, atomic aligned swap, rollback on failure, and
7//! compare-exchange restore — is exactly what the ELF and Mach-O backends will
8//! reuse, swapping only the underlying `sys` calls.
9//!
10//! ## Concurrency model
11//! A single process-wide [`install_lock`] serializes every install, uninstall,
12//! and protection change, so slot *writes* never race each other. Calls *through*
13//! a slot are lock-free: the target's compiled code reads the slot as an aligned
14//! pointer-width load, and every write we make is a single aligned atomic store
15//! (via [`AtomicUsize`]). Aligned pointer-width loads/stores are atomic on all
16//! supported ISAs (x86-64, aarch64), so a concurrent call observes either the
17//! old or the new pointer — never a torn value. No allocation, logging, or lock
18//! acquisition happens on the call-through path (there is none: we only patch
19//! data).
20
21use crate::error::{Error, Result};
22use crate::import::RawImport;
23use crate::module::Module;
24use crate::{ImportKind, Symbol, sys};
25use core::ffi::c_void;
26use core::sync::atomic::{AtomicUsize, Ordering};
27use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
28
29/// The process-wide install/uninstall/protection lock. A poisoned lock is
30/// recovered (we never leave engine state inconsistent under it), so a panic in
31/// unrelated code cannot wedge the engine.
32fn install_lock() -> MutexGuard<'static, ()> {
33 static LOCK: Mutex<()> = Mutex::new(());
34 LOCK.lock().unwrap_or_else(PoisonError::into_inner)
35}
36
37/// Atomically swap the pointer stored in `slot`, returning the previous value.
38///
39/// # Safety
40/// `slot` must be a pointer-aligned, writable, in-bounds import slot (its page
41/// made writable by [`PageProtector`]). The engine holds [`install_lock`], so
42/// this is the only writer.
43unsafe fn slot_swap(slot: usize, new: usize) -> usize {
44 // SAFETY: caller guarantees `slot` is a valid, aligned, writable pointer cell.
45 let atomic = unsafe { &*(slot as *const AtomicUsize) };
46 atomic.swap(new, Ordering::AcqRel)
47}
48
49/// Compare-exchange restore: store `new` only if the slot still holds `expected`.
50///
51/// # Safety
52/// Same requirements as [`slot_swap`].
53unsafe fn slot_compare_exchange(
54 slot: usize,
55 expected: usize,
56 new: usize,
57) -> core::result::Result<usize, usize> {
58 // SAFETY: caller guarantees `slot` is a valid, aligned, writable pointer cell.
59 let atomic = unsafe { &*(slot as *const AtomicUsize) };
60 atomic.compare_exchange(expected, new, Ordering::AcqRel, Ordering::Acquire)
61}
62
63/// Read the current pointer in a slot (the pre-write "original" fallback).
64///
65/// # Safety
66/// `slot` must be a readable, pointer-aligned import slot.
67unsafe fn slot_load(slot: usize) -> usize {
68 // SAFETY: caller guarantees `slot` is a valid, aligned, readable pointer cell.
69 let atomic = unsafe { &*(slot as *const AtomicUsize) };
70 atomic.load(Ordering::Acquire)
71}
72
73/// A batch of page-protection changes, captured so they can be restored exactly.
74///
75/// Protections are captured and restored **per unique page**, not per slot:
76/// several slots typically share one page, and capturing each page's original
77/// protection exactly once is the only way to restore it correctly regardless of
78struct PageProtector {
79 /// `(page_start, original_protection)`, in the order pages were made writable.
80 pages: Vec<(usize, u32)>,
81}
82
83impl PageProtector {
84 /// Make every page spanned by `slots` writable, capturing prior protections.
85 /// On any failure, restore the pages already changed and return the error —
86 /// so a failed call leaves no page writable.
87 fn make_writable(slots: &[usize]) -> Result<Self> {
88 let page_size = sys::page_size();
89 let mask = !(page_size - 1);
90 let mut pages: Vec<usize> = Vec::new();
91 for &slot in slots {
92 let first = slot & mask;
93 let last = slot.saturating_add(crate::arch::PTR_SIZE - 1) & mask;
94 let mut page = first;
95 loop {
96 if !pages.contains(&page) {
97 pages.push(page);
98 }
99 if page == last {
100 break;
101 }
102 page = page.saturating_add(page_size);
103 }
104 }
105
106 let mut done: Vec<(usize, u32)> = Vec::with_capacity(pages.len());
107 for &page in &pages {
108 // SAFETY: `page` is a page-aligned address derived from a validated,
109 // committed import slot.
110 match unsafe { sys::make_writable(page) } {
111 Ok(old) => done.push((page, old)),
112 Err(err) => {
113 for &(p, old) in done.iter().rev() {
114 // SAFETY: `p` was just made writable with captured `old`.
115 let _ = unsafe { sys::restore_protection(p, old) };
116 }
117 return Err(err);
118 }
119 }
120 }
121 Ok(Self { pages: done })
122 }
123
124 /// Restore every page to its captured protection, returning the first error.
125 fn restore(self) -> Result<()> {
126 let mut first_err = None;
127 for &(page, old) in self.pages.iter().rev() {
128 // SAFETY: `page` was made writable by this protector with captured `old`.
129 if let Err(err) = unsafe { sys::restore_protection(page, old) } {
130 first_err.get_or_insert(err);
131 }
132 }
133 first_err.map_or(Ok(()), Err)
134 }
135}
136
137/// Apply a set of `(slot, new_value)` writes transactionally.
138///
139/// Makes all pages writable, performs the atomic swaps, then restores
140/// protections. If making a page writable fails, nothing is swapped. If (against
141/// all expectation) restoring protection fails after swapping, the swaps are
142/// rolled back before the error is surfaced — so on any error nothing remains
143/// patched and no page is left with changed protection.
144fn apply(patches: &[(usize, usize)]) -> Result<Vec<usize>> {
145 let slots: Vec<usize> = patches.iter().map(|&(slot, _)| slot).collect();
146 let protector = PageProtector::make_writable(&slots)?;
147
148 let mut priors = Vec::with_capacity(patches.len());
149 for &(slot, new) in patches {
150 // SAFETY: every page is writable; slots are validated pointer cells.
151 priors.push(unsafe { slot_swap(slot, new) });
152 }
153
154 if let Err(err) = protector.restore() {
155 // Defensive rollback: undo swaps and best-effort re-restore protections.
156 if let Ok(reprotect) = PageProtector::make_writable(&slots) {
157 for (&(slot, _), &prior) in patches.iter().zip(&priors) {
158 // SAFETY: pages writable again; slots valid.
159 unsafe {
160 slot_swap(slot, prior);
161 }
162 }
163 let _ = reprotect.restore();
164 }
165 return Err(err);
166 }
167 Ok(priors)
168}
169
170/// A single writable import slot discovered in a module.
171#[derive(Debug, Clone)]
172pub struct ImportSlot {
173 module_base: usize,
174 library: Arc<str>,
175 symbol: Option<Symbol>,
176 version: Option<Arc<str>>,
177 address: usize,
178 kind: ImportKind,
179 authenticated: bool,
180}
181
182impl ImportSlot {
183 pub(crate) fn from_raw(module_base: usize, raw: RawImport) -> Self {
184 Self {
185 module_base,
186 library: raw.library,
187 symbol: raw.symbol,
188 version: raw.version,
189 address: raw.slot,
190 kind: raw.kind,
191 authenticated: raw.authenticated,
192 }
193 }
194
195 /// Providing library / DLL name, as recorded in the import descriptor.
196 #[must_use]
197 pub fn library(&self) -> &str {
198 &self.library
199 }
200
201 /// The imported symbol, or `None` for a legacy address-only slot
202 /// (`OriginalFirstThunk == 0`), whose name is unrecoverable in memory.
203 #[must_use]
204 pub fn symbol(&self) -> Option<&Symbol> {
205 self.symbol.as_ref()
206 }
207
208 /// The observed symbol version, e.g. `GLIBC_2.2.5` for an ELF import bound to
209 /// unversioned ELF imports. Informational: matching is by name.
210 #[must_use]
211 pub fn version(&self) -> Option<&str> {
212 self.version.as_deref()
213 }
214
215 /// Address of the IAT slot — a `*mut *mut c_void` pointing at the live
216 /// function pointer the target dereferences on every call.
217 #[must_use]
218 pub fn address(&self) -> *mut *mut c_void {
219 self.address as *mut *mut c_void
220 }
221
222 /// Standard vs delay-load import.
223 #[must_use]
224 pub fn kind(&self) -> ImportKind {
225 self.kind
226 }
227
228 /// Whether this slot holds an **authenticated** (PAC-signed) pointer — only on
229 /// slot: a raw replacement pointer would fail its `AUTIA`/`AUTDA` check (or, on a
230 /// PAC-relaxed CPU, be called unsigned), so the transaction reports
231 /// [`Error::AuthenticatedSlot`] rather than corrupt it. Always `false` off
232 /// arm64e.
233 #[must_use]
234 pub fn is_authenticated(&self) -> bool {
235 self.authenticated
236 }
237
238 /// The current page protection of the slot's IAT page, queried on demand
239 /// (informational — the install/restore path captures protection itself).
240 ///
241 /// Enumeration deliberately does **not** query this per slot: for an image
242 /// with many imports that would issue one `VirtualQuery` syscall per slot for
243 /// a purely informational value. Callers that want it pay for exactly the
244 /// slots they ask about, and always observe the *live* protection rather than
245 /// a stale enumeration-time snapshot.
246 #[must_use]
247 pub fn protection(&self) -> u32 {
248 sys::query_protection(self.address)
249 }
250
251 /// Base address of the module this slot belongs to.
252 #[must_use]
253 pub fn module_base(&self) -> *const c_void {
254 self.module_base as *const c_void
255 }
256
257 /// If this slot satisfies `replacement`, return its matched symbol.
258 fn match_replacement(&self, replacement: &Replacement) -> Option<&Symbol> {
259 let symbol = self.symbol.as_ref()?;
260 if !library_matches(replacement.library.as_deref(), &self.library) {
261 return None;
262 }
263 symbol.matches(&replacement.symbol).then_some(symbol)
264 }
265}
266
267/// Case-insensitive (ASCII) DLL-name match; `None` filter matches any library.
268fn library_matches(filter: Option<&[u8]>, actual: &str) -> bool {
269 filter.is_none_or(|wanted| wanted.eq_ignore_ascii_case(actual.as_bytes()))
270}
271
272/// A requested slot replacement.
273///
274/// `library` optionally scopes the match to one providing DLL (case-insensitive);
275/// `symbol` names the import; `replacement` is the new function pointer. When
276/// `required` is set, [`install`] fails if the symbol is not imported by the
277/// module; otherwise a missing symbol is silently skipped — the behavior the
278/// `hookfs` install layer needs when applying its superset of candidate hooks.
279#[derive(Debug)]
280pub struct Replacement {
281 /// Optional providing-DLL filter (ASCII, case-insensitive).
282 pub library: Option<Vec<u8>>,
283 /// The symbol to rebind.
284 pub symbol: Symbol,
285 /// The replacement function pointer.
286 pub replacement: *const c_void,
287 /// Fail the install if this symbol is not present (vs. skip it).
288 pub required: bool,
289}
290
291impl Replacement {
292 /// A required by-name replacement in a specific library.
293 #[must_use]
294 pub fn by_name(library: &str, symbol: &str, replacement: *const c_void) -> Self {
295 Self {
296 library: Some(library.as_bytes().to_vec()),
297 symbol: Symbol::name(symbol),
298 replacement,
299 required: true,
300 }
301 }
302
303 /// A required by-name replacement matching the symbol in **any** providing
304 /// library — the form the ELF backend uses, where imports are matched by name
305 #[must_use]
306 pub fn by_symbol(symbol: &str, replacement: *const c_void) -> Self {
307 Self {
308 library: None,
309 symbol: Symbol::name(symbol),
310 replacement,
311 required: true,
312 }
313 }
314
315 /// A replacement that is skipped (not an error) if the symbol is absent.
316 #[must_use]
317 pub fn optional(mut self) -> Self {
318 self.required = false;
319 self
320 }
321}
322
323/// One installed hook: enough to restore it and to hand the caller the original.
324#[derive(Debug, Clone)]
325pub struct InstalledHook {
326 library: Arc<str>,
327 symbol: Symbol,
328 slot: usize,
329 original: usize,
330 prior_value: usize,
331 replacement: usize,
332}
333
334impl InstalledHook {
335 /// Providing library of the hooked import.
336 #[must_use]
337 pub fn library(&self) -> &str {
338 &self.library
339 }
340 /// The hooked symbol.
341 #[must_use]
342 pub fn symbol(&self) -> &Symbol {
343 &self.symbol
344 }
345 /// Address of the patched IAT slot.
346 #[must_use]
347 pub fn slot(&self) -> *mut *mut c_void {
348 self.slot as *mut *mut c_void
349 }
350 /// The canonical original entry point — the real callee the `hookfs` shims
351 /// invoke for passthrough. For a standard import this is `GetProcAddress`
352 /// (or the load-time-bound slot value as a fallback); for a delay import it
353 /// is always the authoritatively resolved export, never the
354 /// `__delayLoadHelper2` stub the delay slot holds before first call.
355 #[must_use]
356 pub fn original(&self) -> *const c_void {
357 self.original as *const c_void
358 }
359 /// The replacement pointer installed into the slot.
360 #[must_use]
361 pub fn replacement(&self) -> *const c_void {
362 self.replacement as *const c_void
363 }
364}
365
366/// RAII owner of a set of installed hooks. Dropping it restores the original
367/// slot values (best-effort, compare-exchange); [`HookGuard::uninstall`] does the
368/// same but surfaces any conflict.
369#[derive(Debug)]
370pub struct HookGuard {
371 module_base: usize,
372 hooks: Vec<InstalledHook>,
373 active: bool,
374}
375
376impl HookGuard {
377 /// The hooks this guard installed.
378 #[must_use]
379 pub fn installed(&self) -> &[InstalledHook] {
380 &self.hooks
381 }
382
383 /// The canonical original entry point for `symbol`, if this guard hooked it.
384 #[must_use]
385 pub fn original(&self, symbol: &Symbol) -> Option<*const c_void> {
386 self.hooks
387 .iter()
388 .find(|hook| hook.symbol.matches(symbol))
389 .map(InstalledHook::original)
390 }
391
392 /// Restore every slot and consume the guard, reporting the first conflict or
393 /// protection error encountered (the rest are still restored).
394 pub fn uninstall(mut self) -> Result<()> {
395 self.restore()
396 }
397
398 /// The shared restore path used by both [`Self::uninstall`] and [`Drop`].
399 fn restore(&mut self) -> Result<()> {
400 if !self.active {
401 return Ok(());
402 }
403 self.active = false;
404 if self.hooks.is_empty() {
405 return Ok(());
406 }
407
408 let _lock = install_lock();
409
410 // Liveness: if the module has unloaded, leak the patch state rather than
411 if !sys::module_still_loaded(self.module_base) {
412 return Ok(());
413 }
414
415 let slots: Vec<usize> = self.hooks.iter().map(|hook| hook.slot).collect();
416 let protector = PageProtector::make_writable(&slots)?;
417
418 let mut first_err: Option<Error> = None;
419 for hook in &self.hooks {
420 // Extra guard against base reuse: only touch slots still inside this
421 // module's committed image mapping.
422 if !sys::slot_belongs_to_module(hook.slot, self.module_base) {
423 continue;
424 }
425 // Compare-exchange: restore only if the slot still holds our
426 // SAFETY: page writable; slot validated to belong to the image.
427 match unsafe { slot_compare_exchange(hook.slot, hook.replacement, hook.prior_value) } {
428 Ok(_) => {}
429 Err(found) if found == hook.prior_value => {
430 // Already the original value (benign, e.g. redundant restore).
431 }
432 Err(found) => {
433 first_err.get_or_insert(Error::RestoreConflict {
434 slot: hook.slot,
435 expected: hook.replacement,
436 found,
437 });
438 }
439 }
440 }
441
442 if let Err(err) = protector.restore() {
443 first_err.get_or_insert(err);
444 }
445 first_err.map_or(Ok(()), Err)
446 }
447}
448
449impl Drop for HookGuard {
450 fn drop(&mut self) {
451 // Best-effort restore; a Drop must not unwind across into user code.
452 let _ = self.restore();
453 }
454}
455
456struct PendingHook {
457 library: Arc<str>,
458 symbol: Symbol,
459 slot: usize,
460 original: usize,
461 replacement: usize,
462}
463
464/// Install a set of [`Replacement`]s into `module`'s import table, transactionally.
465///
466/// All target slots are resolved first (and each `required` symbol verified
467/// present); all originals are resolved before any slot is written; the writes
468/// are then applied atomically with page-batched protection changes and rolled
469/// restores the originals when dropped or [`HookGuard::uninstall`]ed.
470pub fn install(module: &Module, replacements: &[Replacement]) -> Result<HookGuard> {
471 let _lock = install_lock();
472
473 let imports = module.imports()?;
474 let mut pending: Vec<PendingHook> = Vec::new();
475
476 for replacement in replacements {
477 let mut matched = false;
478 for slot in &imports {
479 let Some(symbol) = slot.match_replacement(replacement) else {
480 continue;
481 };
482 matched = true;
483 // a correctly PAC-signed replacement we cannot synthesize. Refuse loudly
484 // rather than write a pointer that fails its auth check (or, worse, is
485 // dereferenced unsigned) — fail-closed beats a corrupt slot. This aborts
486 // the whole transaction before any write, so nothing is left patched.
487 if slot.authenticated {
488 return Err(Error::AuthenticatedSlot {
489 module: module.name().to_owned(),
490 symbol: symbol.describe(),
491 });
492 }
493 if pending.iter().any(|hook| hook.slot == slot.address) {
494 continue;
495 }
496 // Resolve the canonical original before any write (R6). It must be the
497 // real callee for passthrough — never a resolver stub. The per-platform
498 // policy lives in `sys::resolve_original`: PE prefers `GetProcAddress`
499 // with the load-time slot value as a fallback (delay imports force-load
500 // the provider); ELF always uses `dlsym(RTLD_DEFAULT)` and never the
501 // lazily-bound slot. A `None` here means the original is genuinely
502 // unresolvable — fail a `required` hook rather than hand out a stub, or
503 // skip an `optional` one.
504 // SAFETY: `slot.address` is a readable, pointer-aligned slot cell.
505 let slot_value = unsafe { slot_load(slot.address) };
506 let original = match sys::resolve_original(slot.kind, &slot.library, symbol, slot_value)
507 {
508 Some(original) => original,
509 None if replacement.required => {
510 return Err(Error::OriginalUnresolved {
511 module: module.name().to_owned(),
512 library: slot.library.to_string(),
513 symbol: symbol.describe(),
514 });
515 }
516 None => continue,
517 };
518 pending.push(PendingHook {
519 library: slot.library.clone(),
520 symbol: symbol.clone(),
521 slot: slot.address,
522 original,
523 replacement: replacement.replacement as usize,
524 });
525 }
526 if !matched && replacement.required {
527 return Err(Error::SymbolNotFound {
528 module: module.name().to_owned(),
529 symbol: replacement.symbol.describe(),
530 });
531 }
532 }
533
534 if pending.is_empty() {
535 return Ok(HookGuard {
536 module_base: module.base_addr(),
537 hooks: Vec::new(),
538 active: true,
539 });
540 }
541
542 let patches: Vec<(usize, usize)> = pending
543 .iter()
544 .map(|hook| (hook.slot, hook.replacement))
545 .collect();
546 let priors = apply(&patches)?;
547
548 let hooks = pending
549 .into_iter()
550 .zip(priors)
551 .map(|(hook, prior_value)| InstalledHook {
552 library: hook.library,
553 symbol: hook.symbol,
554 slot: hook.slot,
555 original: hook.original,
556 prior_value,
557 replacement: hook.replacement,
558 })
559 .collect();
560
561 Ok(HookGuard {
562 module_base: module.base_addr(),
563 hooks,
564 active: true,
565 })
566}
567
568/// `Replacement` holds a raw function pointer, which is `!Send` by default; the
569/// pointer is a process-global code address safe to move between threads.
570// SAFETY: the pointer refers to a `'static` function in a loaded module.
571unsafe impl Send for Replacement {}
572// SAFETY: `Replacement` exposes the pointer only by value; no interior mutability.
573unsafe impl Sync for Replacement {}
574
575#[cfg(test)]
576#[allow(
577 clippy::unwrap_used,
578 clippy::expect_used,
579 clippy::indexing_slicing,
580 clippy::unnecessary_box_returns,
581 clippy::borrowed_box,
582 clippy::ref_as_ptr
583)]
584mod tests {
585 use super::*;
586
587 // A heap-allocated pointer-sized cell standing in for an import slot. Its
588 // page is ordinary committed read/write memory, so `VirtualProtect` succeeds
589 // — exactly what the transaction needs to exercise its protection dance.
590 fn cell(value: usize) -> Box<usize> {
591 Box::new(value)
592 }
593 fn addr(cell: &Box<usize>) -> usize {
594 cell.as_ref() as *const usize as usize
595 }
596
597 #[test]
598 fn apply_swaps_and_reports_priors() {
599 let slot = cell(0x1111);
600 let priors = apply(&[(addr(&slot), 0x2222)]).expect("apply succeeds");
601 assert_eq!(priors, vec![0x1111]);
602 assert_eq!(*slot, 0x2222);
603 }
604
605 #[test]
606 fn apply_rolls_back_on_injected_failure() {
607 let good = cell(0xAAAA);
608 // Second "slot" is a bogus, unmapped address: making its page writable
609 // fails, so the whole transaction must abort with nothing swapped.
610 let patches = [(addr(&good), 0xBBBB), (0x1usize, 0xCCCC)];
611 let result = apply(&patches);
612 assert!(matches!(result, Err(Error::Protect { .. })));
613 // The good slot must be untouched (no swap happened before the failure).
614 assert_eq!(*good, 0xAAAA);
615 }
616
617 #[test]
618 fn compare_exchange_restore_detects_a_subsequent_hook() {
619 let slot = cell(0x1000); // original
620 let a = addr(&slot);
621 // Our hook: original -> replacement A.
622 let priors = apply(&[(a, 0x2000)]).expect("install A");
623 assert_eq!(priors, vec![0x1000]);
624
625 // SAFETY: heap cell, writable, aligned.
626 unsafe { slot_swap(a, 0x3000) };
627
628 // Restoring A with compare-exchange must NOT clobber B: the slot no
629 // longer holds A's replacement (0x2000), so the exchange fails.
630 // SAFETY: heap cell, writable, aligned.
631 let result = unsafe { slot_compare_exchange(a, 0x2000, 0x1000) };
632 assert_eq!(result, Err(0x3000));
633 assert_eq!(*slot, 0x3000, "subsequent hook preserved");
634 }
635
636 #[test]
637 fn library_matching_is_case_insensitive_and_optional() {
638 assert!(library_matches(None, "KERNEL32.dll"));
639 assert!(library_matches(Some(b"kernel32.DLL"), "KERNEL32.dll"));
640 assert!(!library_matches(Some(b"ole32.dll"), "KERNEL32.dll"));
641 }
642}