#include "hook_ptwh.h"

Data Structures
struct	_HOOK_PTS_ENTRY

struct	_HOOK_PTS

struct	_HOOK_PTS_STATE

Macros
#define	HOOK_PTS_FLG_DELETE_PT_HOOK 0x00000100

#define	HOOK_PTS_FLG_DELETE_PD_HOOK 0x00000200

#define	HOOK_PTS_MONITORED_BITS (PT_P \| PD_PS \| PT_US \| PT_RW \| 0x000FFFFFFFFFF000)

#define	HOOK_PT_HASH_SIZE 64

#define	HOOK_PT_HASH_ID(x) (((x) >> 12) & (HOOK_PT_HASH_SIZE - 1))

#define	HOOK_PT_PAE_ROOT_HASH_ID(x) (((x) >> 5) & (HOOK_PT_HASH_SIZE - 1))

Typedefs
typedef INTSTATUS(*	PFUNC_SwapCallback) (void *Context, QWORD VirtualAddress, QWORD OldEntry, QWORD NewEntry, QWORD OldPageSize, QWORD NewPageSize)
	Callback invoked on translation modifications. More...

typedef struct _HOOK_PTS_ENTRY	HOOK_PTS_ENTRY

typedef struct _HOOK_PTS_ENTRY *	PHOOK_PTS_ENTRY

typedef struct _HOOK_PTS	HOOK_PTS

typedef struct _HOOK_PTS *	PHOOK_PTS

typedef struct _HOOK_PTS_STATE	HOOK_PTS_STATE

typedef struct _HOOK_PTS_STATE *	PHOOK_PTS_STATE

Functions
INTSTATUS	IntHookPtsSetHook (QWORD Cr3, QWORD VirtualAddress, PFUNC_SwapCallback Callback, void Context, void Parent, DWORD Flags, PHOOK_PTS *Hook)
	Start monitoring translation modifications for the given VirtualAddress. More...

INTSTATUS	IntHookPtsRemoveHook (HOOK_PTS **Hook, DWORD Flags)
	Remove a PTS hook. More...

INTSTATUS	IntHookPtsDeleteHook (HOOK_PTS **Hook, DWORD Flags)
	Permanently delete the PTS hook. More...

INTSTATUS	IntHookPtsCommitHooks (void)
	Commit all PTS hook modifications. More...

INTSTATUS	IntHookPtsInit (void)
	Initializes the PTS hooks system. More...

INTSTATUS	IntHookPtsWriteEntry (PHOOK_PTS_ENTRY Entry, QWORD OldValue, QWORD NewValue)
	Tests the translation modification handler. More...

INTSTATUS	IntHookPtsCheckIntegrity (void)
	Checks the integrity of the existing page-table hooks. Used for debugging the PT filter. More...

void	IntHookPtsDump (void)
	Prints all the page table hooks. More...

Macro Definition Documentation

◆ HOOK_PT_HASH_ID

#define HOOK_PT_HASH_ID ( x ) (((x) >> 12) & (HOOK_PT_HASH_SIZE - 1))

Definition at line 22 of file hook_pts.h.

Referenced by IntHookPtsSetHook().

◆ HOOK_PT_HASH_SIZE

#define HOOK_PT_HASH_SIZE 64

Definition at line 21 of file hook_pts.h.

Referenced by IntHookPtsDump(), and IntHookPtsInit().

◆ HOOK_PT_PAE_ROOT_HASH_ID

#define HOOK_PT_PAE_ROOT_HASH_ID ( x ) (((x) >> 5) & (HOOK_PT_HASH_SIZE - 1))

Definition at line 23 of file hook_pts.h.

Referenced by IntHookPtsSetHook().

◆ HOOK_PTS_FLG_DELETE_PD_HOOK

#define HOOK_PTS_FLG_DELETE_PD_HOOK 0x00000200

Definition at line 15 of file hook_pts.h.

Referenced by IntHookPtsDeleteHookInternal(), IntHookPtsDeleteParents(), and IntHookPtsRemoveHookInternal().

◆ HOOK_PTS_FLG_DELETE_PT_HOOK

#define HOOK_PTS_FLG_DELETE_PT_HOOK 0x00000100

Definition at line 14 of file hook_pts.h.

Referenced by IntHookPtsDeletePdHook(), and IntHookPtsRemovePteHook().

◆ HOOK_PTS_MONITORED_BITS

#define HOOK_PTS_MONITORED_BITS (PT_P | PD_PS | PT_US | PT_RW | 0x000FFFFFFFFFF000)

Monitored bits inside the page-table entries. If any of these bits is modified, the translation modification callback will be called.

Definition at line 19 of file hook_pts.h.

Referenced by IntHandleMemAccess(), IntHookPtsCheckIntegrity(), IntHookPtsWriteCallback(), IntPtiDeliverDriverForLoad(), and IntVeDeliverDriverForLoad().

Typedef Documentation

◆ HOOK_PTS

typedef struct _HOOK_PTS HOOK_PTS

A handle to a virtual address monitoring hook. Each hook placed on a virtual address will create such a structure. Placing multiple hooks on the same virtual address will result in multiple such structures being allocated, but the low-level hook structures (for example, HOOK_PTS_ENTRY) will remain the same. Removing one such hook will not affect other swap hooks set on the same virtual address.

◆ HOOK_PTS_ENTRY

typedef struct _HOOK_PTS_ENTRY HOOK_PTS_ENTRY

Describes one page table entry hook. Please note that "Page Table" is being generically referred to, as it may be any level page table (PT, PD, PDP, PML4, PML5). Each monitored page-table entry will have exactly one such structure attached. If multiple virtual addresses which translate through this entry are monitored, the ref count will simply be incremented accordingly.

◆ HOOK_PTS_STATE

typedef struct _HOOK_PTS_STATE HOOK_PTS_STATE

Global swap hooks state.

◆ PFUNC_SwapCallback

typedef INTSTATUS(* PFUNC_SwapCallback) (void *Context, QWORD VirtualAddress, QWORD OldEntry, QWORD NewEntry, QWORD OldPageSize, QWORD NewPageSize)

Callback invoked on translation modifications.

This callback is invoked whenever a translation modification takes place for a monitored virtual address. NOTE: If the function needs the virtual address space, it can simply query the current Cr3 value, as translation modification callbacks are always called in the virtual address space in which they happened.

Parameters

[in]	Context	The user provided context when establishing the swap hook.
[in]	VirtualAddress	The monitored virtual address.
[in]	OldEntry	Old page-table entry.
[in]	NewEntry	New page-table entry.
[in]	OldPageSize	Old page size.
[in]	NewPageSize	New page size.

Definition at line 41 of file hook_pts.h.

◆ PHOOK_PTS

typedef struct _HOOK_PTS * PHOOK_PTS

◆ PHOOK_PTS_ENTRY

typedef struct _HOOK_PTS_ENTRY * PHOOK_PTS_ENTRY

◆ PHOOK_PTS_STATE

typedef struct _HOOK_PTS_STATE * PHOOK_PTS_STATE

Function Documentation

◆ IntHookPtsCheckIntegrity()

INTSTATUS IntHookPtsCheckIntegrity ( void )

Checks the integrity of the existing page-table hooks. Used for debugging the PT filter.

This function will iterate through all the monitored virtual addresses and check if the actual translation present inside the guest is the same as the last value saved by Introcore. Basically, this function ensures that these hook structures are up to date with the actual memory contents. Used for debugging the PT filter.

Return values

INT_STATUS_SUCCESS	On success.
INT_STATUS_NOT_NEEDED_HINT	If PT filtering is not enabled.
INT_STATUS_NOT_INITIALIZED_HINT	If the hooks system is not initialized.

Definition at line 2236 of file hook_pts.c.

Referenced by IntHandleTimer().

◆ IntHookPtsCommitHooks()

INTSTATUS IntHookPtsCommitHooks ( void )

Commit all PTS hook modifications.

This function will effectively delete all the removed PTS hooks. Hooks which are flagged with the HOOK_FLG_CHAIN_DELETE delete will be spared, as it is expected that they will be deleted by a higher-level hook manager.

Return values

INT_STATUS_SUCCESS On success.

Definition at line 2084 of file hook_pts.c.

Referenced by IntHookCommitAllHooks().

◆ IntHookPtsDeleteHook()

INTSTATUS IntHookPtsDeleteHook	(	HOOK_PTS **	Hook,
		DWORD	Flags
	)

Permanently delete the PTS hook.

This function will permanently delete an existing PTS hook. This function must be called only if the hook has already been removed.

Parameters

[in,out]	Hook	The hook to be deleted.
[in]	Flags	Hook flags. Check out HOOK_FLG* for more info.

Return values

INT_STATUS_SUCCESS	On success.
INT_STATUS_INVALID_PARAMETER	If an invalid parameter is supplied.

Definition at line 1993 of file hook_pts.c.

Referenced by IntHookGvaDeleteHookInternal().

◆ IntHookPtsDump()

void IntHookPtsDump ( void )

Prints all the page table hooks.

This prints all the page table hooks from gHooks.

Definition at line 2452 of file hook_pts.c.

Referenced by IntHandleMemAccess(), and IntHookPtwEmulateWrite().

◆ IntHookPtsInit()

INTSTATUS IntHookPtsInit ( void )

Initializes the PTS hooks system.

Return values

INT_STATUS_SUCCESS On success.

Definition at line 2183 of file hook_pts.c.

Referenced by IntHookInit().

◆ IntHookPtsRemoveHook()

INTSTATUS IntHookPtsRemoveHook	(	HOOK_PTS **	Hook,
		DWORD	Flags
	)

Remove a PTS hook.

Remove a PTS hook. Modifications to the subsequent virtual address translations will not be reported anymore. The hook is not deleted until either the commit phase, or when a higher level hook manager decides so.

Parameters

[in,out]	Hook	The hook to be removed.
[in]	Flags	Hook flags. Check out HOOK_FLG* for more info.

Return values

INT_STATUS_SUCCESS	On success.
INT_STATUS_INVALID_PARAMETER	If an invalid parameter is supplied.

Definition at line 1944 of file hook_pts.c.

Referenced by DbgPtsUnhook(), IntHookGvaRemoveHookInternal(), IntHookPtsInvokeCallbacks(), IntHookRemoveChain(), IntIcFreeInvdEntry(), IntSwapMemCancelTransaction(), IntSwapMemPageSwappedIn(), IntWinPfnHandleTranslationChange(), IntWinPfnRemoveLock(), and IntWinPfnUnlockAddress().

◆ IntHookPtsSetHook()

INTSTATUS IntHookPtsSetHook	(	QWORD	Cr3,
		QWORD	VirtualAddress,
		PFUNC_SwapCallback	Callback,
		void *	Context,
		void *	Parent,
		DWORD	Flags,
		PHOOK_PTS *	Hook
	)

Start monitoring translation modifications for the given VirtualAddress.

Establishes a hook inside the page-tables of the given VirtualAddress inside the Cr3 virtual address space. Whenever there is a translation modification for the given VirtualAddress, the Callback will be invoked. The Context can be a user-supplied value which is passed to the invoked callback. This function will either add a new page-table entry hook (PTS entry hook) on each page-table entry used to translate the provided virtualAddress, or it will simply increment the reference count of an existing such entry.

Parameters

[in]	Cr3	The monitored virtual address space.
[in]	VirtualAddress	The virtual address to be monitored.
[in]	Callback	The PFUNC_SwapCallback to be called when the translation is modified.
[in]	Context	Optional context that will be passed to the Callback.
[in]	Parent	Optional parent hook.
[in]	Flags	Hook flags. Check HOOK_FLG* for more info.
[out]	Hook	The hook handle which can later be used to remove this hook.

Return values

INT_STATUS_SUCCESS	On success.
INT_STATUS_INVALID_PARAMETER	If an invalid parameter is supplied.
INT_STATUS_NOT_SUPPORTED	If a kernel-mode address is to be monitored outside the kernel Cr3.
INT_STATUS_INSUFFICIENT_RESOURCES	If a memory allocation fails.

Definition at line 1535 of file hook_pts.c.

Referenced by DbgPtsHook(), IntHookGvaSetHook(), IntIcAddInvdForInstruction(), IntSwapMemReadData(), and IntWinPfnLockAddress().

◆ IntHookPtsWriteEntry()

INTSTATUS IntHookPtsWriteEntry	(	PHOOK_PTS_ENTRY	Entry,
		QWORD	OldValue,
		QWORD	NewValue
	)

Tests the translation modification handler.

Parameters

[in]	Entry	The entry to be "modified".
[in]	OldValue	Old page-table entry value.
[in]	NewValue	New page-table entry value.

Definition at line 2216 of file hook_pts.c.

Referenced by DbgPtsWrite().

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ HOOK_PT_HASH_ID

◆ HOOK_PT_HASH_SIZE

◆ HOOK_PT_PAE_ROOT_HASH_ID

◆ HOOK_PTS_FLG_DELETE_PD_HOOK

◆ HOOK_PTS_FLG_DELETE_PT_HOOK

◆ HOOK_PTS_MONITORED_BITS

Typedef Documentation

◆ HOOK_PTS

◆ HOOK_PTS_ENTRY

◆ HOOK_PTS_STATE

◆ PFUNC_SwapCallback

◆ PHOOK_PTS

◆ PHOOK_PTS_ENTRY

◆ PHOOK_PTS_STATE

Function Documentation

◆ IntHookPtsCheckIntegrity()

◆ IntHookPtsCommitHooks()

◆ IntHookPtsDeleteHook()

◆ IntHookPtsDump()

◆ IntHookPtsInit()

◆ IntHookPtsRemoveHook()

◆ IntHookPtsSetHook()

◆ IntHookPtsWriteEntry()