src/internal/hook_patch_witness.hpp
| Line | Branch | Exec | Source |
|---|---|---|---|
| 1 | #ifndef DETOURMODKIT_INTERNAL_HOOK_PATCH_WITNESS_HPP | ||
| 2 | #define DETOURMODKIT_INTERNAL_HOOK_PATCH_WITNESS_HPP | ||
| 3 | |||
| 4 | /** | ||
| 5 | * @file hook_patch_witness.hpp | ||
| 6 | * @brief Ownership witness for inline-hook patch windows. | ||
| 7 | */ | ||
| 8 | |||
| 9 | #include "internal/hook_fault_boundary.hpp" | ||
| 10 | #include "internal/memory_guarded.hpp" | ||
| 11 | |||
| 12 | #include <algorithm> | ||
| 13 | #include <array> | ||
| 14 | #include <cstddef> | ||
| 15 | #include <cstdint> | ||
| 16 | #include <string_view> | ||
| 17 | |||
| 18 | namespace DetourModKit::detail | ||
| 19 | { | ||
| 20 | /** | ||
| 21 | * @brief Who owns the bytes currently at an inline backend's patch window. | ||
| 22 | * @details Original means no patch is installed; OwnedPatch means the bytes exactly match an encoding this backend | ||
| 23 | * committed; Foreign means the readable window matches neither; Indeterminate means it could not be read. | ||
| 24 | * LayeredOver means the window holds the patch of another coordinator layer, which an arm recaptures | ||
| 25 | * (`[B-110]`). Only the arm witness reports it. | ||
| 26 | */ | ||
| 27 | enum class PatchWitness : std::uint8_t | ||
| 28 | { | ||
| 29 | Original, | ||
| 30 | OwnedPatch, | ||
| 31 | Foreign, | ||
| 32 | Indeterminate, | ||
| 33 | LayeredOver | ||
| 34 | }; | ||
| 35 | |||
| 36 | /// Names a patch witness for an operator-facing diagnostic. | ||
| 37 | 280 | [[nodiscard]] constexpr std::string_view witness_description(PatchWitness witness) noexcept | |
| 38 | { | ||
| 39 | 280 | switch (witness) | |
| 40 | { | ||
| 41 | 7 | case PatchWitness::Original: | |
| 42 | 7 | return "prologue is original"; | |
| 43 | 59 | case PatchWitness::OwnedPatch: | |
| 44 | 59 | return "our patch is still installed"; | |
| 45 | 209 | case PatchWitness::Foreign: | |
| 46 | 209 | return "another writer owns the prologue"; | |
| 47 | ✗ | case PatchWitness::LayeredOver: | |
| 48 | ✗ | return "another layer owns the prologue"; | |
| 49 | 5 | case PatchWitness::Indeterminate: | |
| 50 | 5 | break; | |
| 51 | } | ||
| 52 | 5 | return "prologue could not be read"; | |
| 53 | } | ||
| 54 | |||
| 55 | /** | ||
| 56 | * @brief Reads a backend target and classifies ownership of its patch window. | ||
| 57 | * @details OwnedPatch requires both exact bytes and persistent provenance that the backend completed a patch-byte | ||
| 58 | * capture. Pre-sized or default-initialized storage is not evidence that the backend emitted those bytes. | ||
| 59 | */ | ||
| 60 | 76151 | template <class Backend> [[nodiscard]] PatchWitness witness_patch(const Backend &backend) noexcept | |
| 61 | { | ||
| 62 | 76151 | const auto &original = backend.original_bytes(); | |
| 63 | 76151 | std::array<std::uint8_t, BACKEND_MAX_STEAL_WINDOW> current{}; | |
| 64 | 152302 | if (original.empty() || original.size() > current.size() || backend.target() == nullptr) | |
| 65 | { | ||
| 66 | ✗ | return PatchWitness::Indeterminate; | |
| 67 | } | ||
| 68 | 76151 | const std::size_t count = original.size(); | |
| 69 | 76151 | if (!guarded_read_bytes(reinterpret_cast<std::uintptr_t>(backend.target()), current.data(), count)) | |
| 70 | { | ||
| 71 | 9 | return PatchWitness::Indeterminate; | |
| 72 | } | ||
| 73 | 76142 | const auto span = static_cast<std::ptrdiff_t>(count); | |
| 74 | 152284 | if (std::equal(original.begin(), original.begin() + span, current.begin())) | |
| 75 | { | ||
| 76 | 29626 | return PatchWitness::Original; | |
| 77 | } | ||
| 78 | 46516 | const auto &emitted = backend.patch_bytes(); | |
| 79 | 91019 | if (backend.patch_bytes_valid() && emitted.size() == count && | |
| 80 | 135522 | std::equal(emitted.begin(), emitted.begin() + span, current.begin())) | |
| 81 | { | ||
| 82 | 36105 | return PatchWitness::OwnedPatch; | |
| 83 | } | ||
| 84 | 10411 | return PatchWitness::Foreign; | |
| 85 | } | ||
| 86 | |||
| 87 | /// Returns whether a witness authorizes the backend to overwrite the target. | ||
| 88 | 24048 | [[nodiscard]] constexpr bool witness_permits_write(PatchWitness witness) noexcept | |
| 89 | { | ||
| 90 | 24048 | return witness == PatchWitness::Original || witness == PatchWitness::OwnedPatch; | |
| 91 | } | ||
| 92 | |||
| 93 | /// Returns whether an arm over @p witness makes the hook the newest layer of its target (`[B-110]`). | ||
| 94 | 15377 | [[nodiscard]] constexpr bool witness_promotes_arm(PatchWitness witness) noexcept | |
| 95 | { | ||
| 96 | 15377 | return witness == PatchWitness::Original || witness == PatchWitness::LayeredOver; | |
| 97 | } | ||
| 98 | |||
| 99 | /** | ||
| 100 | * @brief Classifies a target for an arm: @ref witness_patch, with LayeredOver in place of Foreign when the backend | ||
| 101 | * reports the patch of another coordinator layer. | ||
| 102 | * @note The backend query takes the process coordinator, so a caller that holds a target slot keeps the order of | ||
| 103 | * `[B-109]`. | ||
| 104 | */ | ||
| 105 | 15377 | template <class Backend> [[nodiscard]] PatchWitness witness_arm(const Backend &backend) noexcept | |
| 106 | { | ||
| 107 | 15377 | const PatchWitness witness = witness_patch(backend); | |
| 108 | 15377 | return witness == PatchWitness::Foreign && backend.window_holds_layer() ? PatchWitness::LayeredOver : witness; | |
| 109 | } | ||
| 110 | } // namespace DetourModKit::detail | ||
| 111 | |||
| 112 | #endif // DETOURMODKIT_INTERNAL_HOOK_PATCH_WITNESS_HPP | ||
| 113 |