1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
//! Typed, thread-safe error model for the import-rebinding engine.
//!
//! The C `plthook` returns integer codes and stashes a description in a
//! out as a defect to fix. Here every fallible operation returns a typed
//! [`Error`] with structured fields — no shared mutable error buffer, no
//! stringly-typed channel — so failures are inspectable and thread-safe.
/// Errors produced by the engine while acquiring, parsing, or patching a module.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
/// A requested module could not be located in the current process
/// (`GetModuleHandleExW` failed, or a null handle was supplied).
#[error("module not found: {reason} (os error {os_error})")]
ModuleNotFound {
/// What was being resolved (a handle, an address, or a name).
reason: &'static str,
/// `GetLastError()` captured at the failure site.
os_error: u32,
},
/// The loader reported no valid mapped size for the module, so no bounded
/// range exists to parse against.
#[error("could not determine the mapped size of module at {base:#x} (os error {os_error})")]
ImageSizeUnknown {
/// Module base address (`HMODULE`).
base: usize,
/// `GetLastError()` captured at the failure site.
os_error: u32,
},
/// A structural defect was found while parsing the mapped image (PE or ELF).
/// The parser bounds-checks every field against the validated mapped range
/// *before* dereferencing, so a malformed image yields this error rather than
#[error("malformed image: {0}")]
Malformed(&'static str),
/// The image is a valid PE/ELF the engine intentionally does not handle at
/// runtime (e.g. a 32-bit PE32 image inside a 64-bit process, a legacy
/// absolute-VA delay-import descriptor, or an ELF machine that is not
/// `EM_X86_64`/`EM_AARCH64`). Reported rather than guessed.
#[error("unsupported image: {0}")]
Unsupported(&'static str),
/// A `Replacement` marked `required` matched no import slot in the module.
#[error("required symbol not found in module `{module}`: {symbol}")]
SymbolNotFound {
/// Module name the lookup ran against.
module: String,
/// The symbol that was requested but not imported.
symbol: String,
},
/// A matched import's canonical original entry point could not be resolved,
/// so passing through to it is impossible. This arises for a **delay-load**
/// import whose providing DLL cannot be loaded (or whose symbol is absent
/// from it): the delay IAT slot holds only the `__delayLoadHelper2` stub
/// until first call, and the engine refuses to hand a stub out as the
/// original (calling it would resolve the import and overwrite the very slot
/// we patched, silently dropping the hook). Reported for a `required`
/// replacement; an `optional` one skips the slot instead.
#[error(
"could not resolve the original entry point for `{symbol}` from `{library}` \
(delay-load provider unavailable) in module `{module}`"
)]
OriginalUnresolved {
/// Module whose import was being hooked.
module: String,
/// Providing (delay-load) library that could not be resolved.
library: String,
/// The symbol whose original could not be resolved.
symbol: String,
},
/// A matched import slot holds an **authenticated** (PAC-signed) pointer — an
/// it would require a replacement signed with the slot's key, diversity, and
/// address-discrimination, which cannot be synthesized here; the engine refuses
/// the slot rather than write a pointer that fails its `AUT*` check (or is
/// dereferenced unsigned). arm64e support is a dedicated, device-tested effort;
/// plain arm64 and x86-64 slots are never authenticated and are unaffected.
#[error(
"refusing to rebind authenticated (arm64e PAC-signed) import `{symbol}` in \
module `{module}`: authenticated slots require dedicated PAC support"
)]
AuthenticatedSlot {
/// Module whose authenticated import was matched.
module: String,
/// The symbol whose slot is authenticated.
symbol: String,
},
/// Changing a slot page's protection failed. Carries the slot address and
/// the OS error. When this happens mid-install the engine rolls back every
#[error("VirtualProtect failed for slot {slot:#x}: os error {os_error}")]
Protect {
/// Address of the import slot whose page could not be reprotected.
slot: usize,
/// `GetLastError()` from the failing `VirtualProtect` call.
os_error: u32,
},
/// During restore, a slot no longer held this guard's replacement pointer,
/// untouched and reports the conflict instead (compare-exchange restore,
#[error(
"restore conflict at slot {slot:#x}: expected {expected:#x}, found {found:#x} \
(a subsequent hook owns this slot; left untouched)"
)]
RestoreConflict {
/// Address of the conflicted import slot.
slot: usize,
/// The replacement pointer this guard installed and expected to find.
expected: usize,
/// The pointer actually present in the slot.
found: usize,
},
}
/// Crate-local result alias.
pub type Result<T> = core::result::Result<T, Error>;