ColdHook

ColdHook is a mini and simple open source memory hooking library for Windows x86/x64 made in C++. This library is mainly intended for a simple usage and especially for whoever has a small knowlegde of how hooks actually works. If you find any issue, feel free to report.

Read the functions documentation just below to understand how ColdHook must be used.

Features

Function hooking (Wrap mode, Function emulation mode).
Custom bytes hooking (Ability to hook custom bytes provided by the user to a specified memory address).
Ability to unhook/hook again with a single call once the hooking procedure is initialized.
Ability to return the error ID if any error occurs during the library execution.
Ability to re-calculate special instructions if needed.

Build requirements

MSVC 2019 or higher build tools are required to compile this project.

Functions documentation

InitFunctionHookByName

This function Initializes a new hook by name.
- Syntax
```
    int32_t InitFunctionHookByName(
        Hook_Info** OutputInfo, 
        bool WrapFunction, 
        bool CheckKBase, 
        const char* ModulName, 
        const char* FName, 
        void* HookedF, 
        int32_t* OutErrorCode);
```
- Arguments
  - OutputInfo
    
    A pointer to a variable pointer that will receive the Hook_Info structure to retrieve hook informations.
  - WrapFunction
    
    If this argument is false, the function will only pass the control to the provided function without the returning back option. Intended if you need to emulate the target function, otherwise set to true if you still need to call the original hooked function once you handled what you had to.
  - CheckKBase
    
    If this argument is true and the requested module name is kernel32.dll, the function will check if the kernelbase.dll module is present, if yes, the hook will be placed to the requested function on the kernelbase.dll module instead.
  - ModulName
    
    A string buffer pointer of the module name that the hook target function is present at. If this paramater is NULL, the considered module will be the executable one.
  - FName
    
    A string buffer pointer of the target desired function name where the hook must be installed to.
  - HookedF
    
    A function pointer where you wish to redirect the target function.
  - OutErrorCode
    
    A pointer to a variable that will receive the error id if the function fails. This paramater can be NULL.
- Return value
  
  If the function succeeds, the return value is an ID of the new hook that can be registered to the system later. If the function fails the return value is NULL. For more informations check the error ID stored in the variable provided in the OutErrorCode argument.
InitFunctionHookByAddress

This function Initializes a new hook by addresses.
- Syntax
```
    int32_t InitFunctionHookByAddress(
        Hook_Info** OutputInfo, 
        bool WrapFunction, 
        void* Target, 
        void* HookedF, 
        int32_t* OutErrorCode);
```
- Arguments
  - OutputInfo
    
    A pointer to a variable pointer that will receive the Hook_Info structure to retrieve hook informations.
  - WrapFunction
    
    If this argument is false, the function will only pass the control to the provided function without the returning back option. Intended if you need to emulate the target function, otherwise set to true if you still need to call the original hooked function once you handled what you had to.
  - Target
    
    A pointer to the function that should be hooked.
  - HookedF
    
    A function pointer where you wish to redirect the target function.
  - OutErrorCode
    
    A pointer to a variable that will receive the error id if the function fails. This paramater can be NULL.
- Return value
  
  If the function succeeds, the return value is an ID of the new hook that can be registered to the system later. If the function fails the return value is NULL. For more informations check the error ID stored in the variable provided in the OutErrorCode argument.
InitHookCustomData

This function Initializes a new hook using custom bytes provided by the user.
- Syntax
```
    int32_t InitHookCustomData(
        Hook_Info** OutputInfo, 
        void* Target, 
        void* CustomData, 
        size_t CSize, 
        int32_t* OutErrorCode);
```
- Arguments
  - OutputInfo
    
    A pointer to a variable pointer that will receive the Hook_Info structure to retrieve hook informations.
  - Target
    
    A pointer to the buffer that should be hooked.
  - CustomData
    
    A function pointer where you wish to redirect the target function.
  - CSize
    
    The size in bytes that should be hooked.
  - OutErrorCode
    
    A pointer to a variable that will receive the error id if the function fails. This paramater can be NULL.
- Return value
  
  If the function succeeds, the return value is an ID of the new hook that can be registered to the system later. If the function fails the return value is NULL. For more informations check the error ID stored in the variable provided in the OutErrorCode argument.
UnHookRegisteredData

This function restores the original bytes to the requested hook ID
- Syntax
```
    bool UnHookRegisteredData(
        int32_t HookID, 
        int32_t* OutErrorCode);
```
- Arguments
  - HookID
    
    The hook ID returned by the hook initializers functions.
  - OutErrorCode
    
    A pointer to a variable that will receive the error id if the function fails. This paramater can be NULL.
- Return value
  
  If the function succeeds, the return value is true. If the function fails the return value is false. For more informations check the error ID stored in the variable provided in the OutErrorCode argument.
HookAgainRegisteredData

This function restores the hook bytes to the requested hook ID
- Syntax
```
    bool HookAgainRegisteredData(
        int32_t HookID, 
        int32_t* OutErrorCode);
```
- Arguments
  - HookID
    
    The hook ID returned by the hook initializers functions.
  - OutErrorCode
    
    A pointer to a variable that will receive the error id if the function fails. This paramater can be NULL.
- Return value
  
  If the function succeeds, the return value is true. If the function fails the return value is false. For more informations check the error ID stored in the variable provided in the OutErrorCode argument.
ServiceGlobalInit

This function initializes the ColdHook service
- Syntax
```
    bool ServiceGlobalInit(int32_t* OutErrorCode);
```
- Arguments
  - OutErrorCode
    
    A pointer to a variable that will receive the error id if the function fails. This paramater can be NULL.
- Return value
  
  If the function succeeds, the return value is true. If the function fails the return value is false. For more informations check the error ID stored in the variable provided in the OutErrorCode argument.
ServiceGlobalShutDown

This function stops the ColdHook service and unhooks the data if any
- Syntax
```
    bool ServiceGlobalShutDown(bool UnHook, int32_t* OutErrorCode);
```
- Arguments
  - UnHook
    
    If this argument is set to true, every registered hooked function/address bytes will be restored, otherwise set it to false.
  - OutErrorCode
    
    A pointer to a variable that will receive the error id if the function fails. This paramater can be NULL.
- Return value
  
  If the function succeeds, the return value is true. If the function fails the return value is false. For more informations check the error ID stored in the variable provided in the OutErrorCode argument.
RetrieveHookInfoByID

This function retrieves the registered Hook_Info structure by the ID.
- Syntax
```
    bool RetrieveHookInfoByID(
        Hook_Info** OutputInfo, 
        int32_t HookID, 
        int32_t* OutErrorCode);
```
- Arguments
  - OutputInfo
    
    A pointer to a variable pointer that will receive the Hook_Info structure to retrieve hook informations.
  - HookID
    
    The hook ID returned by the hook initializers functions.
  - OutErrorCode
    
    A pointer to a variable that will receive the error id if the function fails. This paramater can be NULL.
- Return value
  
  If the function succeeds, the return value is true. If the function fails the return value is false. For more informations check the error ID stored in the variable provided in the OutErrorCode argument.
RetrieveHookIDByInfo

This function retrieves the registered hook ID structure by the Hook_Info structure.
- Syntax
```
    bool RetrieveHookIDByInfo(
        Hook_Info* InputInfo, 
        int32_t* OutHookID, 
        int32_t* OutErrorCode);
```
- Arguments
  - InputInfo
    
    A pointer to the Hook_Info structure to give hook informations.
  - OutHookID
    
    A pointer to a variable that will receive the registered hook ID.
  - OutErrorCode
    
    A pointer to a variable that will receive the error id if the function fails. This paramater can be NULL.
- Return value
  
  If the function succeeds, the return value is true. If the function fails the return value is false. For more informations check the error ID stored in the variable provided in the OutErrorCode argument.
ServiceRegisterHookInformation

This function stores on the ColdHook service the returned hook ID and the Hook_Info structure. This must be called when a new hook is initialized
- Syntax
```
   bool ServiceRegisterHookInformation(
        Hook_Info* InputInfo, 
        int32_t HookID, 
        int32_t* OutErrorCode);
```
- Arguments
  - InputInfo
    
    A pointer to the Hook_Info structure to give the hook informations.
  - HookID
    
    The hook ID returned by the hook initializers functions.
  - OutErrorCode
    
    A pointer to a variable that will receive the error id if the function fails. This paramater can be NULL.
- Return value
  
  If the function succeeds, the return value is true. If the function fails the return value is false. For more informations check the error ID stored in the variable provided in the OutErrorCode argument.
ServiceUnRegisterHookInformation

This function removes on the ColdHook service the returned hook ID and the Hook_Info structure. This must be called when a new hook is initialized, this must not be called if the Hook ID status is still hooked
- Syntax
```
   bool ServiceUnRegisterHookInformation(
        int32_t HookID, 
        int32_t* OutErrorCode);
```
- Arguments
  - HookID
    
    The hook ID returned by the hook initializers functions.
  - OutErrorCode
    
    A pointer to a variable that will receive the error id if the function fails. This paramater can be NULL.
- Return value
  
  If the function succeeds, the return value is true. If the function fails the return value is false. For more informations check the error ID stored in the variable provided in the OutErrorCode argument.
CHRetrieveErrorCodeString

This function retrieves the string of the requested error code ID
- Syntax
```
   const char* CHRetrieveErrorCodeString(int32_t InErrorCode);
```
- Arguments
  - InErrorCode
    
    An int32_t value which contains the error code ID.
- Return value
  
  If the function succeeds, the return value is the string of the requested error code ID. If the function fails the return value is Unknown error as string.

Credits

Zydis disassembler for the hook trampoline
MSDN: Documentation style.

Some notes

This project is also used on ColdAPI project, maybe something insteresting to look at.

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
src		src
.gitattributes		.gitattributes
LICENSE.md		LICENSE.md
README.md		README.md

License

Rat431/ColdHook

Folders and files

Latest commit

History

Repository files navigation

ColdHook

Features

Build requirements

Functions documentation

InitFunctionHookByName

Syntax

Arguments

Return value

InitFunctionHookByAddress

Syntax

Arguments

Return value

InitHookCustomData

Syntax

Arguments

Return value

UnHookRegisteredData

Syntax

Arguments

Return value

HookAgainRegisteredData

Syntax

Arguments

Return value

ServiceGlobalInit

Syntax

Arguments

Return value

ServiceGlobalShutDown

Syntax

Arguments

Return value

RetrieveHookInfoByID

Syntax

Arguments

Return value

RetrieveHookIDByInfo

Syntax

Arguments

Return value

ServiceRegisterHookInformation

Syntax

Arguments

Return value

ServiceUnRegisterHookInformation

Syntax

Arguments

Return value

CHRetrieveErrorCodeString

Syntax

Arguments

Return value

Credits

Some notes

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages