75 lines
4.0 KiB
Markdown
75 lines
4.0 KiB
Markdown
# TEESimulator – A Full TEE Emulation Framework
|
||
|
||
**TEESimulator** is a FOSS 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.
|
||
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
|
||
<?xml version="1.0"?>
|
||
<AndroidAttestation>
|
||
<Keybox DeviceID="...">
|
||
<Key algorithm="ecdsa|rsa">
|
||
<PrivateKey format="pem">...</PrivateKey>
|
||
<CertificateChain>...</CertificateChain>
|
||
</Key>
|
||
</Keybox>
|
||
</AndroidAttestation>
|
||
```
|
||
|
||
### Mode Configuration (`target.txt`)
|
||
|
||
TEESimulator currently operates in two primary modes as it transitions towards full emulation. You can control this behavior on a per-package basis.
|
||
|
||
* **`!` → 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.
|
||
|
||
For example:
|
||
```
|
||
# target.txt
|
||
# Use full generation/simulation for this app
|
||
com.google.android.gms!
|
||
|
||
# Use the legacy leaf hacking mode
|
||
io.github.vvb2060.keyattestation?
|
||
```
|
||
|
||
### 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.
|
||
|
||
## 🤝 Contributions
|
||
PRs are welcome as we work towards the goal of a complete TEE simulation. Thank you for supporting true open-source development.
|