xHook Documentation

xHook is a PLT (Procedure Linkage Table) hook library designed for Android native ELF (executable and shared libraries). It allows developers to intercept function calls within loaded libraries by replacing PLT entries with custom functions.

Key Features:

• Compatibility: Supports Android 4.0 - 10 (API level 14 - 29).
• Architecture Support: armeabi, armeabi-v7a, arm64-v8a, x86, and x86_64.
• ELF Support: Handles both ELF HASH and GNU HASH indexed symbols, as well as SLEB128 encoded relocation info.
• Flexibility: Supports setting hook info via POSIX BRE (Basic Regular Expression) and requires no root or special system permissions.
• Zero Dependencies: Does not depend on any third-party shared libraries.

Because ELF loading addresses are randomized at runtime, you must calculate the absolute address by adding the ELF's base address to the relative offset.

On Android versions 5.0 (API 21) and above, you can use dl_iterate_phdr. For older versions (Android 4.0+), you should parse /proc/self/maps to find the base address. In /proc/self/maps, the starting address of the first entry for a specific library (where the offset is 00000000) is typically the base address.

To build the native libraries, you must use Android NDK r16b and ensure it is in your environment PATH. Note that support for armeabi was removed in NDK r17.

Run the following commands to build and install:

./build_libs.sh
./install_libs.sh

#!/bin/bash
./build_libs.sh
./install_libs.sh

The ability to hook external function calls via PLT depends on how the ELF was compiled. There are three main scenarios:

1. Direct Calls: Can always be hooked regardless of compilation options. External function addresses are stored in .got.
2. Global Function Pointer Calls: Can always be hooked regardless of compilation options. External function addresses are stored in .data.
3. Local Function Pointer Calls:
   • With -O2 (default): The call is optimized into a direct call (Scenario 1), so it can be hooked.
   • With -O0: If the external function pointer was assigned to a local variable before the hook was executed, it cannot be hooked via PLT. If it is assigned after the hook, it can be hooked.

Tip for protection: To make an ELF harder to PLT hook, compile with -O0 and assign external function pointers to local variables as early as possible.

To perform accurate hooking, you must calculate the ELF's current base address in memory using the following steps:

1. Locate the line in /proc/self/maps where the offset is 0 and the pathname matches your target ELF. Save the start address of this line as p0.
2. Find the first segment in the ELF's Program Header Table (PHT) that has a type of PT_LOAD and an offset of 0. Save this segment's virtual memory relative address (p_vaddr) as p1.
3. The base address is calculated as: p0 - p1.

Note: In most ELFs, the p_vaddr of the first PT_LOAD segment is 0.

To build the native libraries, you must use Android NDK r16b and ensure it is in your PATH environment variable (support for armeabi was removed in r17).

Run the following commands to compile and install the libraries:

./build_libs.sh
./install_libs.sh

To run the provided Demo:

cd ./xhookwrapper/
./gradlew assembleDebug
adb install ./app/build/outputs/apk/debug/app-debug.apk

#!/bin/bash
./build_libs.sh
./install_libs.sh

# Demo steps
cd ./xhookwrapper/
./gradlew assembleDebug
adb install ./app/build/outputs/apk/debug/app-debug.apk

Use the xhook library to perform PLT hooks more elegantly and avoid hardcoding memory offsets. xhook handles the complexity of finding symbol addresses and managing memory permissions automatically.

Supported Architectures: armeabi, armeabi-v7a, and arm64-v8a. Supported Android Versions: Android 4.0+ (API level >= 14).

#include <stdlib.h>
#include <stdio.h>
#include <test.h>
#include <xhook.h>

void *my_malloc(size_t size)
{
    printf("%zu bytes memory are allocated by libtest.so\n", size);
    return malloc(size);
}

int main()
{
    xhook_register(".*/libtest\.so$", "malloc", my_malloc, NULL);
    xhook_refresh(0);
    
    say_hello();
    return 0;
}