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) for 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 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.