dttr_runtime.h File Reference

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include <windows.h>
#include <dttr_versions.h>

Go to the source code of this file.

Data Structures
struct	DTTR_Core_Context
struct	DTTR_Core_API

Macros
#define	DTTR_DECLARE_STORAGE(type, name)
#define	DTTR_DEFINE_STORAGE(type, name)
#define	DTTR_DECLARE_HOOK_STORAGE(name)
#define	DTTR_DEFINE_HOOK_STORAGE(name)
#define	DTTR_STORAGE_SLOT(type, name)
#define	DTTR_HOOK_STORAGE_SLOT(name)

Typedefs
typedef uintptr_t(*	DTTR_Core_SigscanFn) (HMODULE mod, const char *sig, const char *mask)
typedef struct DTTR_Core_Hook	DTTR_Core_Hook
typedef struct DTTR_Core_API	DTTR_Core_API
typedef struct DTTR_Core_Context	DTTR_Core_Context
typedef DTTR_Core_Hook *(*	DTTR_Core_HookFunctionFn) (uintptr_t addr, int prologue_size, void *handler, void **out_original)
typedef DTTR_Core_Hook *(*	DTTR_Core_HookPointerFn) (uintptr_t addr, void *new_value, void **out_original)
typedef DTTR_Core_Hook *(*	DTTR_Core_PatchBytesFn) (uintptr_t addr, const uint8_t *bytes, size_t size)
typedef void(*	DTTR_Core_UnhookFn) (DTTR_Core_Hook *hook)
typedef bool(*	DTTR_Core_HookIsActiveFn) (DTTR_Core_Hook *hook)
typedef bool(*	DTTR_Core_UnhookCheckedFn) (DTTR_Core_Hook *hook)

Functions
DTTR_Core_Hook *	DTTR_Core_HookAttachFunction (uintptr_t addr, int prologue_size, void *handler, void **out_original)
DTTR_Core_Hook *	DTTR_Core_HookAttachPointer (uintptr_t addr, void *new_value, void **out_original)
DTTR_Core_Hook *	DTTR_Core_HookPatchBytes (uintptr_t addr, const uint8_t *bytes, size_t size)
void	DTTR_Core_HookDetach (DTTR_Core_Hook *hook)
bool	DTTR_Core_HookDetachChecked (DTTR_Core_Hook *hook)
bool	DTTR_Core_HookIsActive (DTTR_Core_Hook *hook)
bool	DTTR_Core_HookDetachOwnerChecked (void *owner)
void *	DTTR_Core_HookSetOwner (void *owner)
void	DTTR_Core_HookDetachOwner (void *owner)
void	DTTR_Core_HookCleanupAll ()
	Detach all remaining hooks and free the sigscan cache.
bool	DTTR_Core_HookCleanupAllChecked ()
uintptr_t	DTTR_Core_HookSigscan (HMODULE mod, const char *sig, const char *mask)
uintptr_t	DTTR_Core_HookCachedSigscan (HMODULE mod, const char *sig, const char *mask)

Detailed Description

Low-level runtime hook, patch, storage, and signature scanning helpers.

Definition in file dttr_runtime.h.

Macro Definition Documentation

DTTR_DECLARE_HOOK_STORAGE

#define DTTR_DECLARE_HOOK_STORAGE

(

name

)

Value:

extern uintptr_t name##_site;                                                        \
extern DTTR_Core_Hook *name##_handle;

Definition at line 71 of file dttr_runtime.h.

DTTR_DECLARE_STORAGE

#define DTTR_DECLARE_STORAGE	(		type,
			name )

Value:

extern type name;

Definition at line 68 of file dttr_runtime.h.

DTTR_DEFINE_HOOK_STORAGE

#define DTTR_DEFINE_HOOK_STORAGE

(

name

)

Value:

uintptr_t name##_site;                                                               \
DTTR_Core_Hook *name##_handle;

Definition at line 74 of file dttr_runtime.h.

DTTR_DEFINE_STORAGE

#define DTTR_DEFINE_STORAGE	(		type,
			name )

Value:

type name;

Definition at line 69 of file dttr_runtime.h.

DTTR_HOOK_STORAGE_SLOT

#define DTTR_HOOK_STORAGE_SLOT

(

name

)

Value:

DTTR_DECLARE_HOOK_STORAGE(name)

Definition at line 79 of file dttr_runtime.h.

DTTR_STORAGE_SLOT

#define DTTR_STORAGE_SLOT	(		type,
			name )

Value:

DTTR_DECLARE_STORAGE(type, name)

Definition at line 78 of file dttr_runtime.h.

Referenced by DTTR_STORAGE_SLOT().

Typedef Documentation

DTTR_Core_API

typedef struct DTTR_Core_API DTTR_Core_API

Definition at line 23 of file dttr_runtime.h.

DTTR_Core_Context

typedef struct DTTR_Core_Context DTTR_Core_Context

DTTR_Core_Hook

typedef struct DTTR_Core_Hook DTTR_Core_Hook

Definition at line 22 of file dttr_runtime.h.

DTTR_Core_HookFunctionFn

typedef DTTR_Core_Hook *(* DTTR_Core_HookFunctionFn) (uintptr_t addr, int prologue_size, void *handler, void **out_original)

Definition at line 34 of file dttr_runtime.h.

DTTR_Core_HookIsActiveFn

typedef bool(* DTTR_Core_HookIsActiveFn) (DTTR_Core_Hook *hook)

Definition at line 49 of file dttr_runtime.h.

DTTR_Core_HookPointerFn

typedef DTTR_Core_Hook *(* DTTR_Core_HookPointerFn) (uintptr_t addr, void *new_value, void **out_original)

Definition at line 42 of file dttr_runtime.h.

DTTR_Core_PatchBytesFn

typedef DTTR_Core_Hook *(* DTTR_Core_PatchBytesFn) (uintptr_t addr, const uint8_t *bytes, size_t size)

Definition at line 45 of file dttr_runtime.h.

DTTR_Core_SigscanFn

typedef uintptr_t(* DTTR_Core_SigscanFn) (HMODULE mod, const char *sig, const char *mask)

Definition at line 20 of file dttr_runtime.h.

DTTR_Core_UnhookCheckedFn

typedef bool(* DTTR_Core_UnhookCheckedFn) (DTTR_Core_Hook *hook)

Definition at line 50 of file dttr_runtime.h.

DTTR_Core_UnhookFn

typedef void(* DTTR_Core_UnhookFn) (DTTR_Core_Hook *hook)

Definition at line 48 of file dttr_runtime.h.

Function Documentation

DTTR_Core_HookAttachFunction()

DTTR_Core_Hook * DTTR_Core_HookAttachFunction	(	uintptr_t	addr,
		int	prologue_size,
		void *	handler,
		void **	out_original )

Install a JMP hook and optionally return the trampoline.

Parameters

addr	Function entry or instruction site to hook.
prologue_size	Minimum prologue bytes for the hook injection site, or 0 for automatic sizing.
handler	Replacement function to call.
out_original	Optional output receiving the original trampoline.

Returns

Hook handle on success, or NULL on failure.

Definition at line 861 of file hook_registry.c.

References hook_chain::addr, check_overlap(), decode_prologue(), dttr_core_hook_set_last_error(), DTTR_ERR_HOOK_CHAIN_UNSUPPORTED, DTTR_HOOK_MAX_INSN, DTTR_HOOK_MAX_PROLOGUE, DTTR_HOOK_PATCH_SIZE, DTTR_LOG_DEBUG, DTTR_LOG_ERROR, DTTR_LOG_WARN, free, function_chain_append(), function_chain_push_head(), function_link_create(), hook_chain_destroy(), hook_error_clear(), hook_find_function_chain(), NULL, hook_chain::original, hook_chain::patch_size, hook_chain::prologue_size, hook_chain::trampoline, and trampoline_relocate().

Referenced by test_function_hooks_chain_and_detach().

DTTR_Core_HookAttachPointer()

DTTR_Core_Hook * DTTR_Core_HookAttachPointer	(	uintptr_t	addr,
		void *	new_value,
		void **	out_original )

Patch a pointer or IAT slot and optionally return the previous value.

Parameters

addr	Address of the pointer slot to replace.
new_value	Replacement pointer value.
out_original	Optional output receiving the previous pointer value.

Returns

Hook handle on success, or NULL on failure.

Definition at line 1010 of file hook_registry.c.

References DTTR_Core_HookPatchBytes(), DTTR_LOG_ERROR, and NULL.

Referenced by test_pointer_hook_detach_restores_original().

DTTR_Core_HookCachedSigscan()

uintptr_t DTTR_Core_HookCachedSigscan	(	HMODULE	mod,
		const char *	sig,
		const char *	mask )

Scan a module with the runtime signature cache.

Parameters

mod	Module to scan.
sig	Raw byte signature buffer.
mask	Mask string where implementation-defined wildcard characters skip bytes.

Returns

Matching address, or 0 when not found.

Definition at line 467 of file hook_registry.c.

References DTTR_Core_HookSigscan().

DTTR_Core_HookCleanupAll()

void DTTR_Core_HookCleanupAll

(

)

Detach all remaining hooks and free the sigscan cache.

Definition at line 1142 of file hook_registry.c.

References DTTR_Core_HookCleanupAllChecked(), and DTTR_LOG_ERROR.

Referenced by cleanup_runtime(), test_cleanup_all_restores_hooks_and_allows_reuse(), test_function_hooks_chain_and_detach(), test_overlapping_byte_patches_are_rejected(), test_owner_detach_only_detaches_matching_owner(), test_patch_bytes_detach_restores_original(), test_patch_group_target_failure_rolls_back_only_new_entries(), and test_pointer_hook_detach_restores_original().

DTTR_Core_HookCleanupAllChecked()

bool DTTR_Core_HookCleanupAllChecked

(

)

Detach all remaining hooks, free the sigscan cache, and report restore failures.

Returns

true when every active hook was detached.

Definition at line 1122 of file hook_registry.c.

References cleanup_sigscan_cache(), hook_detach_index(), and NULL.

Referenced by DTTR_Core_HookCleanupAll().

DTTR_Core_HookDetach()

void DTTR_Core_HookDetach

(

DTTR_Core_Hook *

hook

)

Detach one hook or patch.

Parameters

hook	Hook or patch handle returned by this runtime, or NULL.

Definition at line 1078 of file hook_registry.c.

References DTTR_Core_HookDetachChecked().

Referenced by test_function_hooks_chain_and_detach(), test_overlapping_byte_patches_are_rejected(), test_patch_bytes_detach_restores_original(), and test_pointer_hook_detach_restores_original().

DTTR_Core_HookDetachChecked()

bool DTTR_Core_HookDetachChecked

(

DTTR_Core_Hook *

hook

)

Detach one hook or patch and report restore failure.

Parameters

hook	Hook or patch handle returned by this runtime, or NULL.

Returns

true when the hook is detached, already stale, or NULL.

Definition at line 1063 of file hook_registry.c.

References DTTR_LOG_DEBUG, hook_detach_index(), and hook_find_index().

Referenced by DTTR_Core_HookDetach(), DTTR_Core_Unhook(), DTTR_Core_Unpatch(), and patch_group_detach_checked().

DTTR_Core_HookDetachOwner()

void DTTR_Core_HookDetachOwner

(

void *

owner

)

Detach hooks tagged with the given owner.

Parameters

owner

Owner pointer previously active when hooks or byte patches were created.

Definition at line 1111 of file hook_registry.c.

References DTTR_Core_HookDetachOwnerChecked().

Referenced by test_owner_detach_only_detaches_matching_owner().

DTTR_Core_HookDetachOwnerChecked()

bool DTTR_Core_HookDetachOwnerChecked

(

void *

owner

)

Detach hooks tagged with the given owner and report restore failures.

Parameters

owner

Owner pointer previously active when hooks or byte patches were created.

Returns

true when every owned hook was detached or no owner was supplied.

Definition at line 1086 of file hook_registry.c.

References hook_detach_index().

Referenced by DTTR_Core_HookDetachOwner(), and unload_mod().

DTTR_Core_HookIsActive()

bool DTTR_Core_HookIsActive

(

DTTR_Core_Hook *

hook

)

Report whether a hook handle is still registered with the runtime.

Parameters

hook	Hook or patch handle returned by this runtime, or NULL.

Returns

true while the hook is still active.

Definition at line 1082 of file hook_registry.c.

References hook_find_index().

Referenced by dttr_pcdogs_hook_is_active().

DTTR_Core_HookPatchBytes()

DTTR_Core_Hook * DTTR_Core_HookPatchBytes	(	uintptr_t	addr,
		const uint8_t *	bytes,
		size_t	size )

Patch bytes and keep the originals for detach.

Parameters

addr	Address to patch.
bytes	Replacement bytes to write.
size	Number of replacement bytes.

Returns

Patch handle on success, or NULL on failure.

Definition at line 1029 of file hook_registry.c.

References check_overlap(), DTTR_LOG_ERROR, hook_create(), NULL, DTTR_Core_Hook::original, size, and write_bytes().

Referenced by DTTR_Core_HookAttachPointer(), install_win_main_hook(), test_cleanup_all_restores_hooks_and_allows_reuse(), test_overlapping_byte_patches_are_rejected(), test_owner_detach_only_detaches_matching_owner(), and test_patch_bytes_detach_restores_original().

DTTR_Core_HookSetOwner()

void * DTTR_Core_HookSetOwner

(

void *

owner

)

Set the owner tag for subsequent hooks and return the previous owner.

Parameters

owner

Opaque owner pointer assigned to hooks or byte patches created after this call.

The owner tag is process-global runtime state. Save the returned owner and restore it before returning from a callback if you set it manually.

Returns

Previous owner pointer.

Definition at line 1104 of file hook_registry.c.

Referenced by init_mod(), and test_owner_detach_only_detaches_matching_owner().

DTTR_Core_HookSigscan()

uintptr_t DTTR_Core_HookSigscan	(	HMODULE	mod,
		const char *	sig,
		const char *	mask )

Scan a module for the first matching signature.

Parameters

mod	Module to scan.
sig	Raw byte signature buffer.
mask	Mask string where implementation-defined wildcard characters skip bytes.

Returns

Matching address, or 0 when not found.

Definition at line 48 of file hook_registry.c.

References DTTR_Sigscan_Bytes(), and size.

Referenced by DTTR_Core_AOBFindInModule(), DTTR_Core_HookCachedSigscan(), and install_win_main_hook().