Home

Awesome

ElleKit

What this is

Requirements

Tested configurations

Used by

Usage

Use the Substrate API header or the libhooker API. You can also use the Swift functions directly

How to load ElleKit on startup

See here for a guide on how to install a LaunchDaemon that loads ElleKit on startup.

Building

To build a dynamic library, use Xcode 14. To build the library and the package, run make deb. For the macOS library, set MAC=1. You can also use this as a Swift package.

Status

The C hooking technique

ElleKit will only ever patch the functions you give it. If you hook a function within 128mb of address space, it will make a simple branch instruction and patch the function with it.

If you hook beyond 128mb of address space, it'll set up an exception port to catch all breakpoint exceptions and handle them. Then, it'll patch the target with a brk #1 instruction. ElleKit saves the hooks' target and replacement function and when the exception handler is called, it changes the thread state to redirect execution to the target, then resume execution. This might sound extremely inefficient but it's not too bad.

The original function

ElleKit writes the original function implementation to a new memory page and then provides a pointer to it. If you use LHHookFunctions, it will use one page for the orig functions, which will be faster than allocating a new one for each hook. Orig functions are assembled like so:

// Insert address to target function
movk x16, target_addr % 65536)
movk x16, (target_addr / 65536) % 65536 lsl: 16
movk x16, ((target_addr / 65536) / 65536) % 65536, lsl: 32
movk x16, ((target_addr / 65536) / 65536) / 65536, lsl: 48

// Jump first instruction (the branch to the replacement, aka what we patched)
add x16, x16, 4 

// Execute the skipped instruction
[4 first unpatched bytes of the target function]

// Call the target function
br x16