# 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 file allows you to configure the `osPatchLevel`, `vendorPatchLevel`, and `bootPatchLevel` that the simulator will report in its patched or forged attestation certificates. **Note:** This only affects the Key Attestation data generated by the simulator. It does not change the actual system properties of your device. #### Global and Per-Package Configuration You can set a global patch level that applies to all applications, and you can also override these settings for specific packages. The syntax is hierarchical: * Settings defined at the top of the file, before any `[package.name]` line, are **global** and serve as the default for all apps. * To create a specific configuration for an application, add its package name in square brackets (e.g., `[com.google.android.gms]`). All settings following this line will apply *only* to that package until a new package context is declared. #### Configuration Keys and Values You can specify the patch level for the following components using a `key=value` format: * `system`: The main OS patch level. * `vendor`: The vendor patch level. * `boot`: The boot/kernel patch level. * `all`: A convenient shorthand to set the same date for `system`, `vendor`, and `boot` simultaneously. Any individual key can still be used to override the value set by `all`. Dates should be provided in `YYYY-MM-DD` format (e.g., `2025-11-05`). #### Special Keywords In addition to date values, two special keywords provide advanced control: * **`no`**: This keyword instructs the simulator to **completely omit** the corresponding patch level tag from the generated attestation. * **`device_default`**: This keyword forces the simulator to fall back and use the device's **real hardware value** for that specific patch level. This is essential for creating exceptions to a global override or an `all` rule. #### Example Configuration This example demonstrates how to combine global settings, per-package overrides, and special keywords for fine-grained control. ``` # --- Global Configuration --- # This is the default for all apps unless specified otherwise. # - Forge a recent system patch level. # - Use the device's real vendor patch level. # - Do not report a boot patch level at all. system=2025-11-05 vendor=device_default boot=no # --- Per-Package Override for Google Play Services --- # This app will report an older, specific date for its system patch. # It will inherit the global settings for vendor (device_default) and boot (no). [com.google.android.gms] system=2024-10-01 # --- Per-Package Override for a Demo App --- # This app gets a completely custom configuration. [org.matrix.demo] # Set a base date for all patch levels... all=2025-09-15 # ...but make an exception: use the real boot patch level instead of the one from 'all'. boot=device_default ```