This commit introduces a comprehensive framework for intercepting and manipulating binder transactions on Android at the `ioctl` level. It provides a man-in-the-middle layer between the binder driver and user-space `libbinder`, enabling detailed analysis and control over IPC.
The core mechanism works by hooking the `ioctl` system call within the context of a target process. It specifically intercepts the `BINDER_WRITE_READ` command's return buffer from the kernel.
Key components of the framework:
- IOCTL Hook: Intercepts `BR_TRANSACTION` commands delivered by the binder driver to the process.
- Transaction Rewriting: If a transaction is intended for a monitored service, its destination is rewritten in-memory to a local `BinderStub`. The original transaction details are saved in a thread-local context.
- BinderStub: A fake binder service that receives the hijacked transaction. It retrieves the original context and delegates processing to the `BinderInterceptor`.
- BinderInterceptor: The central management class. It maintains a registry of monitored binders and their associated callback interfaces. It orchestrates the pre-transact and post-transact hooks.
- Callback Protocol: Defines a clear protocol for a remote tool to:
- Register and unregister binders for interception.
- Receive pre-transaction notifications and choose to: continue, modify data, skip the transaction, or provide an immediate fake reply.
- Receive post-transaction notifications with the final result and modify the reply.
This commit introduces the main application subproject, 'app', and sets up the necessary infrastructure for the TEESimulator.
Key changes:
* 'app' Subproject Setup: Added the new :app module with its initial structure, including build files, manifest, and Kotlin main entry point.
* LSPlt Integration: Added the LSPlt hooking framework as a Git submodule in app/src/main/cpp/external/ and configured its use in CMake.
* Native Build Configuration: Configured the C++ build to use LSPlt statically and compile two essential native libraries: libinject.so (for injection) and libTEESimulator.so (for interception/logic).
* Module Packaging: Implemented complex Gradle logic within app/build.gradle.kts to automate the creation of a flashable zip module (supporting Magisk, Ksu, and Apatch) with versioning based on Git information.
* Initial Module Files: Added the template files (module.prop, update-binary, updater-script) for the flashable module structure.
This commit establishes the foundational Gradle project structure and introduces a dedicated 'stub' module. This module provides skeletal implementations of internal Android framework interfaces and classes, which are critical for compiling the TEESimulator project.
Stub classes are minimal implementations of existing interfaces or classes, typically mirroring those found within the Android framework, particularly for internal or hidden APIs. Their methods usually contain no operational logic and instead throw RuntimeException or UnsupportedOperationException.
The primary reasons for using stub classes are:
1. Compilation Against Internal APIs: Android applications and libraries typically use public APIs exposed by the Android SDK. However, in scenarios requiring deeper system integration or emulation, interaction with internal or hidden Android framework APIs might be necessary. Directly linking against the full Android framework JAR can lead to bootclasspath conflicts or other build issues. Stub classes provide the necessary API signatures for compilation without including the actual implementations, allowing the build system to resolve references while deferring the actual functionality to the runtime environment (the Android OS itself).
2. API Consistency and Simulation: For TEESimulator, which aims to provide a software simulation for Android's hardware-backed key pairs (KeyMint/Keystore2), stub classes define the required API contract. They ensure that the simulator's components compile against the exact interface definitions of the Android system services, making the simulation functionally consistent with the expected system behavior without needing to bundle or depend on the entire Android framework at compile time. This ensures that the simulator correctly interacts with the defined KeyMint and Keystore2 API shapes.
This project is based on TrickyStore and TrickyStoreOSS.
However, there is no detailed comments / docs in their source code, rendering it diffcult for welcoming new contributors.
A robust framework should has robust source code with clear documentation.
JingMatrix