commit 79de0be122fa6412f106e8a82dd92059770230e8 Author: JingMatrix Date: Sat Nov 22 10:15:46 2025 +0100 Set-up the ultimate goal of TEESimulator 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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..eaf8eee --- /dev/null +++ b/README.md @@ -0,0 +1,87 @@ +# TEESimulator – A Full TEE Emulation Framework + +**TEESimulator** is a system module designed to create a complete, software-based simulation of a hardware-backed Trusted Execution Environment ([TEE](https://source.android.com/docs/security/features/trusty)) for [Key Attestation](https://developer.android.com/privacy-and-security/security-key-attestation). + +The project's goal is to move beyond simple certificate patching and build a robust framework that can create and manage virtual, self-consistent cryptographic keys. + +## ✨ Core Principles + +* **Bypass Hardware-Backed Attestation:** The primary goal of this project is to defeat Key Attestation, a security mechanism that allows apps to verify that they are running on a secure, unmodified device. This module provides the tools to bypass these checks on rooted or modified devices. +* **Stateful Emulation:** Instead of patching responses from the real TEE, the ultimate goal is to create and manage virtual keys entirely in a simulated software environment. Any request concerning a virtual key will be handled by the simulator, ensuring perfect consistency without ever touching the real hardware. +* **Architectural Interception:** By hooking low-level Binder IPC calls to the Keystore, the framework can transparently redirect requests for virtual keys to the software-based simulator, while allowing requests for real keys to pass through to the hardware TEE. +* **100% FOSS:** Licensed under GPLv3, ensuring it stays free, auditable, and compliant with open-source laws. + +## 📱 Requirements +- Android 10 or above + +## 📦 Installation & Configuration + +1. Flash this module via (Magisk / KernelSU / APatch) and reboot. It will replace [TrickyStore](https://github.com/5ec1cff/TrickyStore), [TrickyStoreOSS](https://github.com/beakthoven/TrickyStoreOSS) and their forks. +2. (Optional) Place a hardware-backed `keybox.xml` at `/data/adb/tricky_store/keybox.xml`. This provides the cryptographic "root of trust" for the simulator. +3. (Optional) Customize target packages in `/data/adb/tricky_store/target.txt`. +4. (Optional) Customize the simulated security patch level in `/data/adb/tricky_store/security_patch.txt`. +5. Enjoy! + +**All configuration files are monitored and will take effect immediately upon saving.** + +### The `keybox.xml` Root of Trust + +This file provides the master cryptographic identity for the simulator. It contains a private key and a valid, hardware-backed certificate chain from a real device. The simulator uses this to sign the virtual certificates it generates, making them appear legitimate to verifiers. + +```xml + + + + + ... + ... + + + +``` + +### Mode and Keybox Configuration (`target.txt`) + +TEESimulator currently operates in two primary modes as it transitions towards full emulation. +You can control the simulation mode and the specific keybox.xml file used on a per-package basis. + +#### Mode Suffixes + +* **`!` → Force Generation Mode:** Creates a complete, software-based virtual key. This is the foundation of the full TEE simulation. +* **`?` → Force Leaf Hacking Mode:** A legacy mode where a real TEE key is generated, but its attestation certificate is intercepted and modified. +* **No symbol → Automatic Mode:** The module selects the most appropriate mode for the device. + +#### Multi-Keybox Configuration + +You can specify different keybox files for different groups of applications. This is done by adding a line with the filename in square brackets (e.g., [demo_keybox.xml]). + +All applications listed after this line will use the specified keybox file, until a new keybox is declared. Applications listed before any custom keybox declaration will use the default `keybox.xml`. + +For example: +``` +# These two apps will use the default /data/adb/tricky_store/keybox.xml +com.google.android.gms! +io.github.vvb2060.keyattestation? + +# Switch to a different keybox for the following apps. +# The file must be located at /data/adb/tricky_store/aosp_keybox.xml +[aosp_keybox.xml] +com.google.android.gsf + +# Switch again to another keybox. +# The file must be located at /data/adb/tricky_store/demo_keybox.xml +[demo_keybox.xml] +org.matrix.demo +``` + +### Security Patch Level (`security_patch.txt`) + +This allows you to configure the security patch level that the simulator will report in its forged attestation certificates. + +``` +# Advanced Configuration +system=2025-11 +boot=no # Do not report a boot patch level +vendor=20251101 # Report a specific vendor patch level +``` +**Note:** This only affects the Key Attestation data generated by the simulator. It does not change system properties.