Skip to main content

plthook/
error.rs

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