ElleKit Documentation

ElleKit is a multi-purpose hooking and assembly library designed for arm64/arm64e devices running the XNU kernel. Its primary functions include:

• C Function Hooking: Patches memory pages directly to intercept C functions.
• Objective-C Hooking: Supports hooking Objective-C messages (preserving the original implementation) and class pairs via MSHookClassPair.
• Assembly & JIT: Provides an arm64 assembler and a JIT inline assembly implementation for Swift.
• API Compatibility: Reimplements both the Substrate and libhooker APIs.

Supported Platforms:

• iOS 15-27 (arm64)
• iOS 15-17 (arm64e)
• macOS Ventura (arm64/arm64e) — Note: Currently unsupported on latest macOS due to Apple's codesigning changes.

ElleKit uses two different strategies for C function hooking depending on the memory distance between the hook and the target:

Within 128MB of address space

ElleKit performs a simple branch instruction patch. This is the fastest method for hooking.

Beyond 128MB of address space

ElleKit uses an exception-based approach:

1. It sets up an exception port to catch breakpoint exceptions.
2. It patches the target function with a brk #1 instruction.
3. When the exception is triggered, the handler catches it, redirects execution to the target function, and resumes execution. While this involves exception handling, it is optimized for performance.

ElleKit can be built as a dynamic library, a Swift package, or via a Debian package.

• Dynamic Library: Use Xcode 14.
• Debian Package: Run make deb to build both the library and the package.
• macOS Library: Set MAC=1 during the build process.
• Swift Package: Can be used directly as a Swift package.

# Build the library and the package
make deb

# Build specifically for macOS
MAC=1 make deb

To avoid manually running the loader script every time your Mac starts, you can install a LaunchDaemon. This ensures ElleKit is automatically injected as soon as you log in to your user account.

Installation Steps

1. Download and place the plist file: Download the com.evln.ellekit.startup.plist file and save it to the following system directory (this requires root privileges): /Library/LaunchDaemons/com.evln.ellekit.startup.plist

2. Load the Daemon: Open a terminal and use launchctl to load the configuration:

   sudo launchctl load -w /Library/LaunchDaemons/com.evln.ellekit.startup.plist

3. Verify: Reboot your Mac. ElleKit should now be injected automatically on startup.

ElleKit can be integrated into your project using three primary methods:

1. Substrate API: Use the standard Substrate headers.
2. libhooker API: Use the libhooker interface.
3. Swift Functions: Call the Swift functions directly for native integration.

Depending on your target, you can hook most C functions (even those without symbols if you provide a direct pointer) and Objective-C messages.

To hook a C function in Swift, you can use the hook function. You can either provide an original function pointer to allow for chaining/calling the original implementation, or provide only the target and replacement functions.

When providing an orig function, the returned value is a pointer to the original implementation, which is relocated to a different memory page.

// Hooking with an original function pointer
let atoiC: @convention(c) (UnsafePointer<CChar>?) -> Int32 = atoi
let repC: @convention(c) () -> Int32 = Replacement
let orig = hook(
    unsafeBitCast(atoiC, to: UnsafeMutableRawPointer.self),
    unsafeBitCast(repC, to: UnsafeMutableRawPointer.self)
)

// Hooking without an original function pointer
hook(
    target,
    replacement
)

If you need to use the Substrate API directly, you can call MSHookFunction. This requires allocating memory for the original function pointer (orig), which will hold the address of the original implementation after the hook is applied.

let atoiC: @convention(c) (UnsafePointer<CChar>?) -> Int32 = atoi
let repC: @convention(c) () -> Int32 = Replacement
let orig = UnsafeMutablePointer<UnsafeMutableRawPointer?>.allocate(capacity: 10)
MSHookFunction(
    unsafeBitCast(atoiC, to: UnsafeMutableRawPointer.self),
    unsafeBitCast(repC, to: UnsafeMutableRawPointer.self),
    orig
)