From 54c12a9fd55f213c7dd57729c02000d4742f1737 Mon Sep 17 00:00:00 2001 From: Enginex0 Date: Thu, 26 Mar 2026 12:34:36 +0100 Subject: [PATCH] docs(readme): rewrite for TEESimulator-RS v6.0.0 Fix all links from old TEESimulator repo, strip emoji clutter, add v6.0.0 changelog, update update.json to point at new repo. --- README.md | 268 ++++++++++++-------------------------------- module/changelog.md | 21 ++++ module/update.json | 8 +- 3 files changed, 99 insertions(+), 198 deletions(-) diff --git a/README.md b/README.md index df4673f..bdec69d 100644 --- a/README.md +++ b/README.md @@ -1,259 +1,139 @@

-

🔐 TEESimulator

+

TEESimulator-RS

Full TEE Emulation for Rooted Android

-

Hardware attestation. Software keys. Zero detection.

- Build - v4.2 - Android 10+ - Telegram + Build + Android 10+ + Telegram

--- > [!NOTE] -> **This is a personal fork of [JingMatrix/TEESimulator](https://github.com/JingMatrix/TEESimulator)** with additional hardening, native Rust certificate generation, key persistence, and anti-detection features. For the upstream project, see the original repo. +> Fork of [JingMatrix/TEESimulator](https://github.com/JingMatrix/TEESimulator) with native Rust certificate generation, key persistence, and AOSP-compliant attestation behavior. For the upstream project, see the original repo. ---- +## What It Does -## 🧬 What is TEESimulator? +TEESimulator intercepts Binder IPC at the `ioctl` level inside the `keystore2` process and generates entire certificate chains from scratch, signed by your keybox, with correct attestation extensions. Apps that verify hardware attestation see a legitimate device. -TEESimulator is a **complete software simulation** of Android's hardware-backed [Trusted Execution Environment](https://source.android.com/docs/security/features/trusty) for [Key Attestation](https://developer.android.com/privacy-and-security/security-key-attestation). Instead of patching certificates from the real TEE after the fact, TEESimulator intercepts Binder IPC at the `ioctl` level and generates entire certificate chains from scratch — signed by your keybox, with correct attestation extensions, indistinguishable from hardware-generated keys. +This is not TrickyStore. TEESimulator replaces TrickyStore and its forks entirely. It shares the same config paths for drop-in compatibility, but the internals are different: native Rust cert generation, binder-level interception via `lsplt`, per-UID rate limiting, key persistence, and AOSP-spec attestation behavior. -The result: **apps that verify hardware attestation see a legitimate, unmodified device** — even on rooted hardware with an unlocked bootloader. - -> **This is not TrickyStore.** TEESimulator replaces TrickyStore and its forks entirely. It shares the same config paths for drop-in compatibility, but the architecture is fundamentally different: native Rust certificate generation, binder-level interception via `lsplt`, per-UID rate limiting, key persistence, and a multi-layer defense against detector apps. - ---- - -## 🔥 Why TEESimulator? - -🔐 **Native Cert Generation** — v4.0 generates X.509 certificate chains in Rust with `ring` and manual DER encoding. No BouncyCastle overhead, no Java crypto quirks, byte-perfect issuer chain linkage. - -🎯 **Binder-Level Interception** — Hooks `ioctl()` on `libc.so` via `lsplt` inside the `keystore2` process. Intercepts `generateKey`, `importKey`, and `getKeyEntry` transactions before the HAL ever sees them. - -🛡️ **Detector Resistant** — Per-UID rate limiting blocks DuckDetector-style keygen flooding. Oversized challenges rejected with real KeyMint error codes. Chain consistency verified byte-for-byte. - -💾 **Key Persistence** — Generated keys survive reboots. Apps that store attestation keys (banking, biometrics) don't break after a restart. - -🔧 **Drop-In Replacement** — Same config paths as TrickyStore (`/data/adb/tricky_store/`). Swap the module ZIP, keep your keybox and target list. - ---- - -## ✨ Features - -**Core Attestation Engine** -- [x] **Full certificate chain generation** — leaf + intermediates + root, signed by your keybox -- [x] **Native Rust certgen** — `libcertgen.so` built with `ring`, `rsa`, and manual DER assembly -- [x] **BouncyCastle fallback** — unsupported curves (P-224, P-521, Curve25519) fall back to Java -- [x] **ASN.1 attestation extensions** — OID 1.3.6.1.4.1.11129.2.1.17 with all AOSP-specified tags -- [x] **Multi-keybox support** — different keybox files per app group via `target.txt` - -**Interception Layer** -- [x] **Binder ioctl hook** — `lsplt` PLT hook on `libc.so` inside `keystore2` process -- [x] **generateKey / importKey / getKeyEntry** — all three transaction types intercepted -- [x] **256KB native payload cap** — oversized binder payloads bypass interception cleanly -- [x] **Challenge validation** — rejects >128-byte attestation challenges with `INVALID_INPUT_LENGTH` - -**Hardening** -- [x] **Per-UID rate limiter** — 2 hardware keygens per 30s burst window, software fallback on overflow -- [x] **importKey eviction guard** — retained patch chains prevent generate-then-import cache attacks -- [x] **Key persistence** — file-backed storage with file-level locking, survives reboots and keybox rotations -- [x] **Global exception handler** — uncaught exceptions logged, daemon stays alive - -**Configuration** -- [x] **Live config reload** — `FileObserver` watches all config files, changes apply immediately -- [x] **Security patch spoofing** — per-package `system`, `vendor`, `boot` patch levels with dynamic templates -- [x] **Lifecycle scripts** — KSU Action button clears key cache, uninstall removes all traces - ---- - -## 📋 Requirements +## Requirements > [!IMPORTANT] -> TEESimulator requires root access and a valid `keybox.xml` for hardware-level attestation results. Without a keybox, the module generates software-level certificates that won't pass strict hardware attestation checks. +> A valid `keybox.xml` is required for hardware-level attestation. Without one, the module generates software-level certificates that won't pass strict hardware checks. -**You need:** -1. Android 10 or above -2. A supported root manager (KernelSU, Magisk, or APatch) -3. A hardware-backed `keybox.xml` placed at `/data/adb/tricky_store/keybox.xml` +1. Android 10+ +2. Root manager: KernelSU, Magisk, or APatch +3. `keybox.xml` at `/data/adb/tricky_store/keybox.xml` ---- +## Quick Start -## 📱 Compatibility +1. Download the latest ZIP from [Releases](https://github.com/Enginex0/TEESimulator-RS/releases) +2. Install via your root manager and reboot +3. Place your keybox at `/data/adb/tricky_store/keybox.xml` +4. Configure targets in `/data/adb/tricky_store/target.txt` +5. Verify with Play Integrity or Key Attestation Demo -### Root Managers +## Architecture -| Manager | Status | Notes | -|---|---|---| -| KernelSU | ✅ Tested | Full support including Action button and lifecycle scripts | -| Magisk | ✅ Supported | Standard module install | -| APatch | ✅ Supported | Standard module install | +**Native Cert Generation** — `libcertgen.so` generates X.509 chains in Rust using `ring` and manual DER encoding. BouncyCastle fallback for unsupported curves (P-224, P-521, Curve25519). -### Tested Devices +**Binder Interception** — PLT hook on `ioctl()` in `libc.so` via `lsplt` inside `keystore2`. Intercepts `generateKey`, `importKey`, and `getKeyEntry` transactions. -| Device | Android | TEE | Status | -|---|---|---|---| -| Redmi 14C (2409BRN2CA) | 14 (SDK 34) | Beanpod KeyMaster | ✅ Daily driver | +**AOSP Compliance** — Self-signed certs for non-attested keys (matching `ta/src/keys.rs`), correct AuthorizationList tag ordering, version-guarded extension fields, `authorize_create` enforcement. -> Tested against DuckDetector, Luna, Play Integrity, and Key Attestation Demo. If you test on a different device, [open an issue](https://github.com/Enginex0/TEESimulator/issues) with your results. +**Key Persistence** — Generated keys survive reboots. File-backed with file-level locking. ---- +**Rate Limiting** — Per-UID hardware keygen cap (2/30s window, 2 concurrent). Overflow falls to software certs. -## 🚀 Quick Start +## Configuration -1. **Download** the latest release ZIP from [Releases](https://github.com/Enginex0/TEESimulator/releases) -2. **Install** via your root manager (KSU / Magisk / APatch) and reboot -3. **Place your keybox** at `/data/adb/tricky_store/keybox.xml` -4. **Configure targets** in `/data/adb/tricky_store/target.txt` -5. **Verify** — check Play Integrity or run Key Attestation Demo +All config files live at `/data/adb/tricky_store/` and are hot-reloaded via `FileObserver`. -TEESimulator replaces TrickyStore, TrickyStoreOSS, and their forks. Existing config files are compatible. +### target.txt ---- +Controls which apps get intercepted and the simulation mode. -## 🔨 Building from Source +| Suffix | Mode | +|--------|------| +| `!` | Force software key generation | +| `?` | Force leaf certificate patching (real TEE key, patched cert) | +| *(none)* | Automatic selection | -The CI workflow builds on every push to `main`. You can also build locally or trigger a build from your own fork. - -**Prerequisites:** JDK 21, Android SDK/NDK 27, Rust stable with `aarch64-linux-android` target, `cargo-ndk`. - -```bash -git clone https://github.com/Enginex0/TEESimulator.git -cd TEESimulator -./gradlew zipRelease zipDebug -``` - -Output ZIPs land in `out/`. The Gradle build automatically invokes `cargo ndk` to cross-compile `libcertgen.so` before packaging. - -To rebuild from a fork, push to `main` or use **Actions → Build → Run workflow**. The workflow installs all toolchains (Java, Rust, cargo-ndk, ccache) and uploads Release + Debug ZIPs as artifacts. - ---- - -## ⚙️ Configuration - -All configuration files live at `/data/adb/tricky_store/` and are monitored by `FileObserver` — changes take effect immediately without rebooting. - -### The `keybox.xml` Root of Trust - -This file provides the master cryptographic identity. It contains a private key and a hardware-backed certificate chain from a real device. TEESimulator signs all generated certificates with this key, making them appear legitimate to verifiers. - -```xml - - - - - ... - ... - - - -``` - -### Target Packages (`target.txt`) - -Controls which apps get intercepted and what simulation mode to use. - -#### Mode Suffixes - -* **`!` → Force Generation** — Creates a complete software-based virtual key. Full TEE simulation. -* **`?` → Force Leaf Hacking** — Real TEE key generated, but its attestation certificate is intercepted and patched. -* **No symbol → Automatic** — Module selects the best mode for your device. - -#### Multi-Keybox - -Specify different keybox files for different app groups. Apps listed after a `[filename.xml]` line use that keybox. Apps before any declaration use the default `keybox.xml`. +Multi-keybox support via `[filename.xml]` headers: ``` -# Default keybox com.google.android.gms! io.github.vvb2060.keyattestation? -# Switch to a different keybox for the following apps [aosp_keybox.xml] com.google.android.gsf - -# Another keybox -[demo_keybox.xml] -org.matrix.demo ``` -### Security Patch Level (`security_patch.txt`) +### security_patch.txt -Configure the `osPatchLevel`, `vendorPatchLevel`, and `bootPatchLevel` reported in attestation certificates. This only affects attestation data — it does not change actual system properties. - -#### Global and Per-Package - -Settings at the top of the file are global defaults. Add `[package.name]` to override for specific apps. - -#### Keys +Override patch levels reported in attestation certificates. Global defaults at top, per-package overrides with `[package.name]`. | Key | Scope | -|---|---| +|-----|-------| | `system` | OS patch level | | `vendor` | Vendor patch level | | `boot` | Boot/kernel patch level | -| `all` | Shorthand — sets all three at once | +| `all` | Sets all three | -#### Special Keywords - -| Keyword | Effect | -|---|---| -| `today` | Current date, dynamically resolved on each attestation | -| `YYYY-MM-DD` templates | Semi-dynamic — `YYYY-MM-05` resolves to the 5th of the current month | -| `no` | Omit this patch level tag entirely from the attestation | -| `device_default` | Use the device's real hardware value | -| `prop` | Read from `ro.build.version.security_patch` (matches what detectors see via getprop) | - -#### Example +Special values: `today`, `YYYY-MM-DD` templates, `no` (omit tag), `device_default`, `prop` (read from system property). ``` -# Global — default for all apps system=YYYY-MM-05 vendor=device_default boot=no -# Override for GMS [com.google.android.gms] -system=2024-10-01 - -# Custom config for a demo app -[org.matrix.demo] -all=2025-09-15 -boot=device_default +system=2025-10-01 ``` ---- +## Building from Source -## 💬 Community +Prerequisites: JDK 21, Android SDK/NDK 27, Rust stable with `aarch64-linux-android` target, `cargo-ndk`. + +```bash +git clone --recursive https://github.com/Enginex0/TEESimulator-RS.git +cd TEESimulator-RS +./gradlew zipRelease zipDebug +``` + +Output ZIPs in `out/`. Gradle invokes `cargo ndk` automatically to cross-compile `libcertgen.so`. + +Push to `main` or use **Actions > Build > Run workflow** to trigger CI. + +## Compatibility + +| Root Manager | Status | +|---|---| +| KernelSU | Tested (Action button + lifecycle scripts) | +| Magisk | Supported | +| APatch | Supported | + +## Community

- Telegram + Telegram

---- +## Credits -## 🙏 Credits +- [JingMatrix](https://github.com/JingMatrix/TEESimulator) — original TEESimulator and interception architecture +- [5ec1cff](https://github.com/5ec1cff/TrickyStore) — TrickyStore, the project that pioneered keystore interception +- [LSPlt](https://github.com/LSPosed/LSPlt) — PLT hook library +- [ring](https://github.com/briansmith/ring) — Rust cryptography library +- [MhmRdd](https://github.com/MhmRdd) — AOSP compliance work via upstream [PR #157](https://github.com/JingMatrix/TEESimulator/pull/157) +- [fatalcoder524](https://github.com/fatalcoder524) — contributor and collaborator +- [huguangares](https://github.com/huguangares) — collaborator and tester -- **[JingMatrix](https://github.com/JingMatrix/TEESimulator)** — original author of TEESimulator and the interception architecture -- **[5ec1cff](https://github.com/5ec1cff/TrickyStore)** — TrickyStore, the project that pioneered keystore interception on Android -- **[LSPlt](https://github.com/LSPosed/LSPlt)** — PLT hook library used for binder interception -- **[ring](https://github.com/briansmith/ring)** — Rust cryptography library powering native cert generation -- **[MhmRdd](https://github.com/MhmRdd)** — AOSP compliance improvements via upstream [PR #157](https://github.com/JingMatrix/TEESimulator/pull/157), including authorize_create enforcement, attestation extension alignment, and binder transaction filtering -- **[fatalcoder524](https://github.com/fatalcoder524)** — a real contributor and collaborator on this project -- **[huguangares](https://github.com/huguangares)** — collaborator and tester +## License ---- - -## 📄 License - -This project is licensed under the [GNU General Public License v3.0](LICENSE). - ---- - -

- 🔐 Because the best attestation is the one the TEE never generated. -

+[GNU General Public License v3.0](LICENSE) diff --git a/module/changelog.md b/module/changelog.md index eb64e54..e7bbb98 100644 --- a/module/changelog.md +++ b/module/changelog.md @@ -1,3 +1,24 @@ +## TEESimulator-RS v6.0.0 + +Repository consolidation release. All tee-rebuild work merged as the new main branch. + +### AOSP Self-Signed Cert Compliance +- No-challenge keys now generate self-signed certs (subject == issuer, depth 1), matching AOSP `ta/src/keys.rs:451-478` +- Both Kotlin (BouncyCastle) and Rust (native-certgen) paths corrected +- Eliminates attestation behavioral probes that detect keybox issuer on non-attested keys + +### Stability +- Binder stress crash hardening for concurrent generateKey calls +- AUTO mode TEE race for consistent attestation on devices with working G10 +- Oversized transactions routed to software gen instead of crashing +- Operation-time params (BLOCK_MODE, PADDING, DIGEST) passed through to CipherPrimitive + +### Infrastructure +- Version scheme changed to semver (v6.0.0) +- Repository moved to TEESimulator-RS as canonical source + +--- + ## TEESimulator-RS v5.0: AOSP Compliance Overhaul Major release integrating 30+ AOSP compliance improvements from upstream PR #157 analysis, layered on top of our StrongBox hardening and native cert gen architecture. diff --git a/module/update.json b/module/update.json index d40981b..ef75a11 100644 --- a/module/update.json +++ b/module/update.json @@ -1,6 +1,6 @@ { - "version": "v4.5", - "versionCode": 111, - "zipUrl": "https://github.com/Enginex0/TEESimulator/releases/download/v4.5/TEESimulator-v4.5-Release.zip", - "changelog": "https://raw.githubusercontent.com/Enginex0/TEESimulator/main/module/changelog.md" + "version": "v6.0.0", + "versionCode": 155, + "zipUrl": "https://github.com/Enginex0/TEESimulator-RS/releases/latest/download/TEESimulator-RS-Release.zip", + "changelog": "https://raw.githubusercontent.com/Enginex0/TEESimulator-RS/main/module/changelog.md" }