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

🤝 Contributions

PRs are welcome as we work towards the goal of a complete TEE simulation. Thank you for supporting true open-source development.