### Install OmegaRelay with one-liner Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/vps/README.md One-line install for OmegaRelay on a VPS. Generates a random PSK, sets the domain, and runs the remote install script. The script handles rustup, clone, build, certbot, systemd unit, and start. ```bash sudo OMEGA_PSK="$(openssl rand -hex 32)" \ OMEGA_DOMAIN=relay.example.com \ bash <(curl -sSL https://raw.githubusercontent.com/Andrea-tb/OmegaRelay/main/vps/install.sh) ``` -------------------------------- ### Build commands for Windows (PowerShell) Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OMEGA_INTEGRATION.md One-time setup commands to install Rust toolchain, Android target, cargo-ndk, and pull the LSPlt submodule, followed by per-build environment variables and the Gradle command to produce the release zip. Tested with AGP 8.13.2, Kotlin 2.3.0, NDK 27.3.13750724, JDK 21. ```powershell # One-time: install Rust toolchain + Android target + cargo-ndk $env:Path = "$env:USERPROFILE\.cargo\bin;C:\msys64\mingw64\bin;$env:Path" rustup target add --toolchain stable-x86_64-pc-windows-gnu aarch64-linux-android cargo +stable-x86_64-pc-windows-gnu install cargo-ndk --locked # One-time: pull the LSPlt submodule git submodule update --init --recursive # Per build: keep Rust off the unicode-named workspace path on Windows $env:RUSTUP_TOOLCHAIN = "stable-x86_64-pc-windows-gnu" $env:CARGO_TARGET_DIR = "C:\Temp\teesim-rust-target" .\gradlew.bat :app:zipRelease # → out/TEESimulator-RS-vX.Y.Z-NNN-Release.zip ``` -------------------------------- ### Deploy with direct TLS Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/vps/README.md Simplest deployment: direct TLS. Sets the PSK and domain, then runs the install script. The phone connects to wss://relay.example.com:8443/. ```bash sudo OMEGA_PSK="..." OMEGA_DOMAIN=relay.example.com bash install.sh ``` -------------------------------- ### Start server for smoke test Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/server/README.md Starts the server in release mode with the configuration file, used as the first step of the smoke test. ```bash cargo run --release -- config.toml ``` -------------------------------- ### Run the relay server with RUST_LOG=info Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/module/provider/README.md Command to start the relay server and watch for the provider authentication log line. ```text RUST_LOG=info cargo run --bin omega-server -- server/config.toml # ... watch for `session authenticated peer=... device_id=device-b-1 role=Provider` ``` -------------------------------- ### Module directory layout Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/module/provider/README.md Shows the file structure of the installed module and the configuration/state directory. ```text /data/adb/modules/omega_provider/ ├── module.prop ├── service.sh # boot hook (post-fs-data) ├── daemon.sh # JVM restart loop ├── customize.sh # installer ├── sepolicy.rule ├── classes.dex # compiled daemon (~3.6 MB) ├── provider.example.conf └── webroot/ ├── index.html # KSU WebUI ├── style.css ├── ksu.js └── app.js /data/adb/omega/ # config + state ├── provider.conf # YOUR config (mode 600) ├── provider.pid └── logs/ └── provider.log ``` -------------------------------- ### Configure config.toml with PSK generation Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/server/README.md Copies the example configuration and generates a strong pre-shared key (PSK) using either openssl or PowerShell. Then edit config.toml to set the psk and bind_addr values. ```bash cp config.example.toml config.toml # Generate a strong PSK: # openssl rand -hex 32 # Or PowerShell: # -join ((48..57)+(65..90)+(97..122) | Get-Random -Count 48 | % {[char]$_}) # Edit config.toml: set psk and bind_addr. ``` -------------------------------- ### Configure server config.toml Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/DEPLOY.md Example server configuration for OmegaRelay. Copy server/config.example.toml to config.toml and edit. Sets bind_addr to 0.0.0.0:8443, a pre-shared key (psk), TLS with Let's Encrypt certificates, and defines two devices: device-b-1 as provider and device-a-1 as consumer paired with device-b-1. auto_generate_self_signed is false; set true only for self-signed development. ```toml bind_addr = "0.0.0.0:8443" psk = "" [tls] enabled = true cert_path = "/etc/letsencrypt/live/relay.example.com/fullchain.pem" key_path = "/etc/letsencrypt/live/relay.example.com/privkey.pem" auto_generate_self_signed = false # set true for self-signed dev only [devices.device-b-1] role = "provider" [devices.device-a-1] role = "consumer" paired_with = "device-b-1" ``` -------------------------------- ### Install Consumer module via KSU Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md Install the TEESimulator-RS Consumer module on Device A via KSU. Requires adb and a BL-unlocked device with KSU installed. ```bash adb push TEESimulator-RS-v6.0.0-165-Release.zip /data/local/tmp/ adb shell "su -c 'ksud module install /data/local/tmp/TEESimulator-RS-v6.0.0-165-Release.zip'" adb reboot ``` -------------------------------- ### Local file build (no internet for git) Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/vps/README.md Local file build for VPS without internet access to GitHub. Creates a tarball on the laptop, copies it to the VPS, extracts it, and runs the install script with OMEGA_SRC pointing to the local source. ```bash # On your laptop: tar czf omega.tgz OmegaRelay/ scp omega.tgz vps:/tmp/ ``` ```bash # On the VPS: cd /tmp && tar xzf omega.tgz sudo OMEGA_PSK="..." OMEGA_SRC=/tmp/OmegaRelay bash /tmp/OmegaRelay/vps/install.sh ``` -------------------------------- ### Obtain a real TLS certificate with certbot Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/server/README.md Example command to obtain a Let's Encrypt certificate for production deployment. After running, point cert_path/key_path in config.toml to the generated certificate files. ```bash # example with certbot certbot certonly --standalone -d relay.example.com # then point cert_path/key_path in config.toml to /etc/letsencrypt/live/... ``` -------------------------------- ### Push provider module ZIP via adb Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/DEPLOY.md Push the built provider module ZIP to Device B's /sdcard/Download/ directory via adb. After pushing, install it in KernelSU Manager → Modules → Install from storage and reboot. ```powershell adb push ..\..\dist\omega-provider-v0.1.0.zip /sdcard/Download/ ``` -------------------------------- ### Real-device smoke test commands (bash) Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OMEGA_INTEGRATION.md Commands to push and install the consumer module, write the relay config, mark the test app for RELAY, and watch the engines. Expected log lines and UI results are included in comments. ```bash # 1. Push and install the consumer module on Device A adb push out/TEESimulator-RS-*.zip /data/local/tmp/ adb shell su -c "ksud module install /data/local/tmp/TEESimulator-RS-*.zip" adb reboot # 2. After boot, write the relay config (Device A side) adb shell su -c "cat > /data/adb/tricky_store/omega-relay.conf <<'EOF' url = ws://178.22.26.156:8443/ # or wss://your.domain/ in production psk = device_id = device-a-1 # must match a [devices.*] entry on the server tls_insecure = false EOF" # 3. Mark the test app for RELAY in target.txt (hot-reloaded) adb shell "su -c 'sed -i "s/^io.github.vvb2060.keyattestation.*$/io.github.vvb2060.keyattestation@/" /data/adb/tricky_store/target.txt'" # 4. Watch the engines adb logcat -s TEESimulator:V # 5. On Device A, open KeyAttestation, leave all menu checkboxes off, # tap the regenerate button. Expected log lines: # I RelayClient: authenticated, session_id= # I Generating software key for KeyAttestation[...] # I NativeCertGen: generated key pair successfully (3 certs) # I RelayEngine: task OK in 4xxms, chain len=6 # I RELAY: replaced software chain (len=3) with remote chain (len=6) for KeyAttestation # # Expected in the KeyAttestation UI: # "Google 硬件认证根证书" / "Google Hardware Attestation Root" # 6-cert chain ``` -------------------------------- ### Build OmegaRelay Consumer module Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/STATUS.md Builds the OmegaRelay Consumer module (Device A) fork of TEES-RS. Includes one-time setup (submodule init, adding the Android target, installing cargo-ndk) and per-build environment variables to avoid the unicode-named workspace path. The final Gradle command produces out/TEESimulator-RS-*.zip. ```powershell cd TEESimulator-RS-Online # One-time setup git submodule update --init --recursive $env:Path = "$env:USERPROFILE\.cargo\bin;C:\msys64\mingw64\bin;$env:Path" rustup target add --toolchain stable-x86_64-pc-windows-gnu aarch64-linux-android cargo +stable-x86_64-pc-windows-gnu install cargo-ndk --locked # Per-build env (keep cargo off the unicode-named workspace path) $env:RUSTUP_TOOLCHAIN = "stable-x86_64-pc-windows-gnu" $env:CARGO_TARGET_DIR = "C:\Temp\teesim-rust-target" .\gradlew.bat :app:zipRelease # → out/TEESimulator-RS-*.zip ``` -------------------------------- ### Build the server with cargo build --release Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/server/README.md Builds the OmegaRelay server in release mode. Requires Rust 1.75+ installed via rustup. The resulting binary is placed at ../target/release/omega-server[.exe]. ```bash cd server cargo build --release # Binary: ../target/release/omega-server[.exe] ``` -------------------------------- ### Build OmegaRelay Provider APK Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/STATUS.md Builds the OmegaRelay Provider APK for Device B using Gradle. After building, open the project in Android Studio for one-click install. ```powershell cd OmegaRelay/android .\gradlew.bat :daemon-provider-app:assembleDebug ``` -------------------------------- ### omega-relay.conf relay client configuration Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OMEGA_INTEGRATION.md Shows the omega-relay.conf file format for the relay client. It is read once at process start; missing or invalid config causes RelayEngine.initialize() to return false and '@'-flagged packages fall back to PATCH. ```text url = wss://relay.example.com:8443/ psk = REPLACE_WITH_SHARED_SECRET_AT_LEAST_16_CHARS device_id = device-a-1 tls_insecure = false ``` -------------------------------- ### Expected output for attestation test Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md Expected output when manually testing attestation. Shows a successful relay task with chain length 6 and installation of the remote chain. ```text RelayEngine: task OK in ms, chain len=6 RELAY: installed remote chain (len=6) over placeholder for ``` -------------------------------- ### Consumer relay configuration Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md Configuration file for the Consumer relay, specifying the relay server URL, PSK, and device ID. Must be edited after installing the module and requires a reboot to take effect. ```ini url = ws://your-vps-ip:8443/ psk = your-secret-key device_id = device-a-1 ``` -------------------------------- ### Uninstall OmegaRelay Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/vps/README.md Uninstall OmegaRelay: disables and removes the systemd service, deletes the installation directories and binary, removes the omega user, and optionally revokes the Let's Encrypt certificate. ```bash sudo systemctl disable --now omega-relay sudo rm -f /etc/systemd/system/omega-relay.service sudo systemctl daemon-reload sudo rm -rf /usr/local/lib/omega-relay /etc/omega-relay /usr/local/bin/omega-server sudo userdel omega # Optionally also revoke the cert: sudo certbot delete --cert-name relay.example.com ``` -------------------------------- ### View Consumer logs with adb logcat Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md View all TEESimulator logs, filter for relay-related entries, or clear logcat and start fresh. Useful for debugging the Consumer side. ```bash adb logcat -s TEESimulator:V ``` ```bash adb logcat -s TEESimulator:V | grep -iE "relay|RELAY|task|chain" ``` ```bash adb logcat -c && adb logcat -s TEESimulator:V ``` -------------------------------- ### AttestExternalKey verified certificate chain Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/STATUS.md Output from hardware validation on OnePlus 11 (Snapdragon 8 Gen 2, ColorOS 16) showing the verified certificate chain for AttestExternalKey. The chain contains 6 certificates, starting with a forged leaf containing Device A's public key and ending with the Google Hardware Attestation Root. ```text === AttestExternalKey verified chain (6 certs) === cert0 (forged leaf, contains Device A pubkey) ↓ signed by signer's TEE-resident private key cert1 (signer leaf, TEE-issued via setAttestKeyAlias) ↓ signed by attest_key (PURPOSE_ATTEST_KEY) cert2 (attest_key leaf, TEE-issued) ↓ signed by Qualcomm intermediate cert3 (intermediate, title=TEE) ↓ signed by Qualcomm batch cert4 (Qualcomm batch root) ↓ signed by Google cert5 (Google Hardware Attestation Root, self-signed) ``` -------------------------------- ### Build Rust server and run tests Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/STATUS.md Sets up the MSYS2 MinGW and Cargo paths, then runs tests and builds for the omega-protocol and omega-server crates using the stable-x86_64-pc-windows-gnu toolchain. ```powershell $env:Path = "C:\msys64\mingw64\bin;$env:USERPROFILE\.cargo\bin;$env:Path" $env:CARGO_TARGET_DIR = "C:\Temp\omega-target" cargo +stable-x86_64-pc-windows-gnu test -p omega-protocol cargo +stable-x86_64-pc-windows-gnu build -p omega-server ``` -------------------------------- ### Run omega-server with config.toml Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/DEPLOY.md Run the OmegaRelay server with the configuration file config.toml. Set RUST_LOG=info to see logs. Verify it logs 'listening addr=0.0.0.0:8443 tls=true'. For production, run under systemd or supervisord. ```bash RUST_LOG=info ./omega-server config.toml ``` -------------------------------- ### Key files and directories Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/STATUS.md Lists the key files and directories in the project, including the Rust relay server, protocol crate, Android components, and the TEESimulator-RS-Online fork with the OmegaRelay extension package. ```text server/ Rust relay server protocol/ Rust protocol crate android/protocol Kotlin protocol port android/daemon-core Daemon shared logic (WebSocket + Engines + LeafBuilder) android/daemon-provider Desktop CLI test harness (JVM) android/daemon-provider-app Android APK (Provider, on Device B) ✅ vps/install.sh One-shot VPS installer ✅ ../TEESimulator-RS-Online/ Fork of TEES-RS (Consumer side) app/src/main/java/.../relay/ OmegaRelay extension package RelayClient.kt RelayConfigLoader.kt RelayEngine.kt protocol/ Auth/Codec/Messages (re-packaged) app/.../config/ConfigurationManager.kt ← Mode.RELAY added app/.../interception/keystore/Keystore2Interceptor.kt ← RELAY branch module/module.prop ← renamed OMEGA_INTEGRATION.md ← integration notes ``` -------------------------------- ### Build omega-server with cargo Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/DEPLOY.md Build the OmegaRelay server on a Windows host using the stable-x86_64-pc-windows-gnu toolchain. Sets the PATH to include MSYS2 mingw64 and Cargo, sets CARGO_TARGET_DIR to C:\Temp\omega-target, and runs cargo build --release -p omega-server. The resulting binary is at C:\Temp\omega-target\release\omega-server.exe on Windows or target/release/omega-server on Linux. ```powershell # On your build host (Windows shown; Linux is similar with `cargo` from rustup). cd OmegaRelay $env:Path = "C:\msys64\mingw64\bin;$env:USERPROFILE\.cargo\bin;$env:Path" $env:CARGO_TARGET_DIR = "C:\Temp\omega-target" cargo +stable-x86_64-pc-windows-gnu build --release -p omega-server # Binary lives at: # C:\Temp\omega-target\release\omega-server.exe (Windows) # target/release/omega-server (Linux) ``` -------------------------------- ### Build provider module with package.ps1 Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/DEPLOY.md Build the provider module for Device B. Sets ANDROID_HOME to the default Android SDK location, changes to the provider module directory, and runs package.ps1. The output ZIP is at ..\..\dist\omega-provider-v0.1.0.zip. ```powershell # Set ANDROID_HOME if not already. $env:ANDROID_HOME = "$env:LOCALAPPDATA\Android\Sdk" cd OmegaRelay\module\provider .\package.ps1 # Output: ..\..\dist\omega-provider-v0.1.0.zip ``` -------------------------------- ### Build Provider APK with Gradle Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md Build the Provider APK from the OmegaRelay/android directory using the Gradle wrapper. ```bash cd OmegaRelay/android ./gradlew :daemon-provider-app:assembleRelease ``` -------------------------------- ### Deploy relay server with TLS Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md Deploy the OmegaRelay relay server on a VPS with a randomly generated PSK and a domain for TLS. Requires Debian/Ubuntu/RHEL and root privileges. ```bash sudo OMEGA_PSK="$(openssl rand -hex 32)" \ OMEGA_DOMAIN=relay.example.com \ bash OmegaRelay/vps/install.sh ``` -------------------------------- ### Build relay server with Cargo Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md Build the relay server from the OmegaRelay directory. The release binary is placed at target/release/omega-server. ```bash cd OmegaRelay cargo build --release -p omega-server # Binary: target/release/omega-server ``` -------------------------------- ### View VPS server logs with journalctl Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md View live VPS server logs, show the last 100 lines, or restart the omega-relay service. Useful for server-side debugging. ```bash journalctl -u omega-relay -f ``` ```bash journalctl -u omega-relay -n 100 --no-pager ``` ```bash sudo systemctl restart omega-relay ``` -------------------------------- ### Build the provider package with package.ps1 Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/module/provider/README.md PowerShell command to build the provider module from the repo root. Requires Java 17 and Android SDK build-tools. ```powershell cd OmegaRelay\module\provider .\package.ps1 ``` -------------------------------- ### Tail the provider log on the phone Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/module/provider/README.md Command to monitor the provider log and the expected startup messages. ```text adb shell su -c 'tail -f /data/adb/omega/logs/provider.log' # ... should show: # starting JVM # websocket open: 101 # Hello sent for device_id=device-b-1 # authenticated, session_id=... ``` -------------------------------- ### target.txt per-app routing configuration Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OMEGA_INTEGRATION.md Shows the target.txt file format for routing attestation requests per app. The '@' suffix forces RELAY mode, while other entries use original modes (PATCH, AUTO). The file is hot-reloaded via FileObserver. ```text # unchanged: original modes io.github.vvb2060.keyattestation! # force PATCH com.example.bar # AUTO (resolves to PATCH/GENERATE today) # new: force RELAY com.google.android.gms@ com.android.vending@ ``` -------------------------------- ### Build Consumer module with Gradle on Windows Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md Build the Consumer module on Windows. Set CARGO_TARGET_DIR to a non-ASCII-safe path before running the Gradle wrapper. The build produces out/TEESimulator-RS-*.zip. ```powershell # Windows (paths with non-ASCII need these env vars): $env:CARGO_TARGET_DIR = "C:\Temp\teesim-rust-target" .\gradlew.bat :app:zipRelease # Output: out/TEESimulator-RS-*.zip ``` -------------------------------- ### 架构总览图:Consumer A 与 Provider B 中继流程 Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/docs/protocol-v2-rfc.zh.md 架构总览图,展示 Consumer A 与 Provider B 之间的中继流程。图中标注了 GMS Unstable 调用、被 hook 的 keystore2、RelayClient 经 WSS 到服务器再到 Provider 的路径,以及 Provider B 中 RelayProvider 到原生 keystore2 和真 KeyMint TEE 的链路。 ```text ┌────────────────────────────────────────────────────────────────────────────┐ │ Consumer A (BL 已解锁) │ │ │ │ GMS Unstable │ │ │ generateKey / sign / getKeyEntry / deleteKey │ │ ▼ │ │ 被 hook 的 keystore2 (libTEESimulator) │ │ │ │ │ │ 按 caller_uid 分类: │ │ │ - 如果 uid 是 GMS 或在中继目标列表里:转发 │ │ │ - 否则:透传给本机 TEE(或 v1 forge) │ │ ▼ │ │ RelayClient ── KeyMintSession ──► WSS ──► 服务器 ──► Provider │ └────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────┐ │ Provider B │ │ (BL 锁定 + KSU │ │ 越狱模式) │ │ │ │ RelayProvider │ │ │ │ │ ▼ │ │ keystore2 原生 │ │ │ │ │ ▼ │ │ 真 KeyMint TEE │ │ (verifiedBoot= │ │ Verified, 真 │ │ RKP key) │ └─────────────────────┘ ``` -------------------------------- ### Hook points in Keystore2Interceptor and KeyMintSecurityLevelInterceptor Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/docs/protocol-v2-rfc.md Lists the existing and new hook points in the Keystore2Interceptor and KeyMintSecurityLevelInterceptor, showing which operations are already hooked and which are new in v2. ```kotlin Keystore2Interceptor.onPreTransact / onPostTransact ├─ getKeyEntry → already hooked, redirect via session ├─ deleteKey → already hooked, redirect via session ├─ updateSubcomponent → new └─ listEntries → already hooked, inject relay-managed aliases KeyMintSecurityLevelInterceptor ├─ generateKey → already hooked, route to KmSession ├─ importKey → new (less common, but GMS may use it) ├─ deleteKey → new └─ createOperation → new (entry to begin/update/finish) KeystoreOperationInterceptor (NEW) ├─ updateAad → forward ├─ update → forward ├─ finish → forward └─ abort → forward ``` -------------------------------- ### Run the server in dev and with explicit log level Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/server/README.md Runs the server in development mode, which auto-generates a self-signed certificate on first run. The second command sets the RUST_LOG environment variable to enable debug logging for the omega_server and omega_protocol crates. ```bash # In dev (auto-generates self-signed cert on first run): cargo run --release -- config.toml ``` ```bash # With explicit log level: RUST_LOG=omega_server=debug,omega_protocol=debug cargo run -- config.toml ``` -------------------------------- ### Hook points for Keystore2Interceptor and KeyMintSecurityLevelInterceptor Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/docs/protocol-v2-rfc.zh.md Lists the hook points in Keystore2Interceptor and KeyMintSecurityLevelInterceptor, marking which are already hooked and which are new in v2. The tree structure shows the interceptor hierarchy and the operations each handles. ```kotlin Keystore2Interceptor.onPreTransact / onPostTransact ├─ getKeyEntry → 已 hook,按 session 重定向 ├─ deleteKey → 已 hook,按 session 重定向 ├─ updateSubcomponent → 新增 └─ listEntries → 已 hook,注入中继管理的 alias KeyMintSecurityLevelInterceptor ├─ generateKey → 已 hook,路由到 KmSession ├─ importKey → 新增(少见,但 GMS 可能用) ├─ deleteKey → 新增 └─ createOperation → 新增(begin/update/finish 的入口) KeystoreOperationInterceptor(新文件) ├─ updateAad → 转发 ├─ update → 转发 ├─ finish → 转发 └─ abort → 转发 ``` -------------------------------- ### Run smoke test with PSK Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/server/README.md Runs the smoke test binary, connecting to the server at ws://127.0.0.1:8443 with the PSK from your config.toml. The test verifies end-to-end task round-trip; success is indicated by '✅ end-to-end task round-trip OK'. For TLS testing, the smoke test does not skip cert verification, so use enabled = false in [tls]. ```bash cargo run --release --bin smoke_test -- ws://127.0.0.1:8443 ``` -------------------------------- ### Run end-to-end smoke test with fake_external.exe Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/STATUS.md Runs the fake_external.exe client against the live VPS WebSocket endpoint. Expect a 6-cert chain with the message '✅ root cert5 is self-signed (Google attest root)'. ```powershell & "C:\Temp\omega-target\debug\fake_external.exe" ` "ws://178.22.26.156:8443" ` "" ``` -------------------------------- ### Server log for authenticated provider Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/DEPLOY.md Expected log line on the server when Device B authenticates successfully. Watch for this in the server logs to verify the provider is connected. ```text 2026-... INFO session authenticated peer=... device_id=device-b-1 role=Provider ``` -------------------------------- ### OpenKmSession and KmSessionOpened message flow Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/docs/protocol-v2-rfc.md Shows the session lifecycle messages for opening a KeyMint session. The Consumer sends OpenKmSession with its alias, forwarded UID, caller app ID, and optional provider pin; the Server forwards it with a session_id, and the Provider responds with KmSessionOpened containing the session_id, provider alias, and capabilities. ```text Consumer → Server: OpenKmSession { consumer_alias: String, // alias as seen by GMS on Consumer forwarded_uid: u32, // caller uid on Consumer (GMS = 10000+) caller_app_id: Vec, // GMS package signature digest pin_provider_device_id: Option, // if Consumer wants a specific Provider } Server → Provider: OpenKmSession (forwarded with session_id assigned by server) Provider → Server → Consumer: KmSessionOpened { session_id: Uuid, // unique per (consumer_alias, opened_at) provider_alias: String, // internal alias on Provider B (different from consumer_alias) capabilities: KmCaps, // what KeyMint version, supported algos, has_strongbox, etc. } ``` -------------------------------- ### Connection Handshake: Hello and HelloAck Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/docs/protocol.md Defines the Hello and HelloAck message structures exchanged during the connection handshake. The client must send Hello as the first frame within 5 seconds; the server responds with HelloAck and closes the connection if success is false. ```text Client → Server: Hello { role: "consumer" | "provider", device_id: String, auth_token: String, // HMAC of (device_id + nonce + timestamp) using PSK nonce: [u8; 16], timestamp: u64, // Unix seconds, must be within ±60s of server time protocol_version: u16, // currently 1 capabilities: Vec, // e.g. ["attest", "sign", "attest_key_pool"] } Server → Client: HelloAck { success: bool, session_id: Uuid, server_time: u64, error: Option, } ``` -------------------------------- ### Reboot Device A to apply config Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md Reboot Device A to apply the relay configuration changes. Required after editing the config file. ```bash adb reboot ``` -------------------------------- ### Update OmegaRelay Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/vps/README.md Update OmegaRelay to a new version. Reuses the existing PSK from the config file. The script is idempotent: it won't recreate the user, won't request a new cert if one exists, and won't change your config (apart from the build artifact and systemd unit). ```bash sudo OMEGA_PSK="$(grep ^psk /etc/omega-relay/config.toml | cut -d'"' -f2)" \ OMEGA_DOMAIN=relay.example.com \ bash <(curl -sSL https://raw.githubusercontent.com/Andrea-tb/OmegaRelay/main/vps/install.sh) ``` -------------------------------- ### Kotlin RealKeyMintEngine.handleGenerateKey() with GMS attestation forwarding Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/docs/protocol-v2-rfc.md Provider uses standard Android Keystore APIs to generate EC keys with attestation challenge. The ATTESTATION_APPLICATION_ID forwarding is essential so the leaf cert binds to GMS, not the Provider app, otherwise Google's backend mismatches. ```kotlin class RealKeyMintEngine : AttestationEngine { override fun handleGenerateKey(req: KmRequest.GenerateKey): KmResult { val params = KeyGenParameterSpec.Builder( providerAlias(req.sessionId), KeyProperties.PURPOSE_SIGN, ) .setAlgorithmParameterSpec(ECGenParameterSpec("secp256r1")) .setAttestationChallenge(req.attestationChallenge) // CRITICAL: forward the GMS attestation_application_id verbatim // so the leaf cert binds to GMS, not to Provider's app .also { applyAaid(it, req.attestationApplicationId) } .build() val kpg = KeyPairGenerator.getInstance("EC", "AndroidKeyStore") kpg.initialize(params) val kp = kpg.generateKeyPair() val chain = keyStore.getCertificateChain(providerAlias(req.sessionId)) return KmResult.GenerateKey( certChain = chain.map { it.encoded }, publicKeyDer = kp.public.encoded, keyMetadata = readMetadata(kp), ) } } ``` -------------------------------- ### Edit relay config on Device A Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md Open the relay configuration file on Device A for editing. Requires root access via su. ```bash adb shell "su -c 'vi /data/adb/modules/tricky_store/omega-relay.conf'" ``` -------------------------------- ### Deploy behind nginx Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/vps/README.md Deploy behind an existing nginx. Disables TLS and binds to localhost:18443. Then drop nginx-snippet.conf into /etc/nginx/sites-enabled/ (edit hostname). ```bash sudo OMEGA_PSK="..." OMEGA_NO_TLS=1 OMEGA_BIND_ADDR=127.0.0.1:18443 bash install.sh ``` -------------------------------- ### Check relay logs on Device A Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md Check relay logs on Device A to verify the relay connection and monitor activity. ```bash adb logcat -s TEESimulator:V | grep -i relay ``` -------------------------------- ### View Provider logs with adb logcat Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md View Provider APK logs by tag or filter by package PID. Use for debugging the Provider side. ```bash adb logcat -s OmegaRelay:V ``` ```bash adb logcat --pid=$(adb shell pidof org.ommega.relay.provider.app) ``` -------------------------------- ### Check relay connection status via logs Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md Check relay connection status on Consumer, Provider, and VPS sides by filtering logs for authentication and connection events. ```bash adb logcat -d -s TEESimulator:V | grep -iE "authenticated|connected|disconnect" ``` ```bash adb logcat -d -s OmegaRelay:V | grep -iE "authenticated|connected|disconnect" ``` ```bash journalctl -u omega-relay --since "5 min ago" | grep -i "hello\|disconnect" ``` -------------------------------- ### Tail provider log on device Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/DEPLOY.md Tail the provider log on Device B (in adb shell as root) to verify the WebSocket connection and authentication. Look for 'websocket open: 101', 'Hello sent for device_id=device-b-1', and 'authenticated, session_id=...'. ```bash tail -f /data/adb/omega/logs/provider.log # look for: # websocket open: 101 # Hello sent for device_id=device-b-1 # authenticated, session_id=... ``` -------------------------------- ### Test attestation manually with adb logcat Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md Manually trigger a key attestation and watch the relay in action. Clear logcat, then open the Key Attestation app on Device A and tap Attest, then filter logs for relay activity. ```bash adb logcat -c # Open Key Attestation app on Device A, tap "Attest" adb logcat -s TEESimulator:V | grep -iE "relay|task|chain|OK" ``` -------------------------------- ### Kotlin selfCheck() for Provider TEE status verification Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/docs/protocol-v2-rfc.md Provider verifies its own TEE status at startup using Android Keystore. If verifiedBootState is not Verified, Provider refuses to serve sessions and emits a clear error in its UI to prevent footguns after reboot. ```kotlin fun selfCheck(): SelfCheckResult { val keypair = keyStore.generateKeyPair("__omega_selfcheck__", attest=true) val chain = keyStore.getCertificateChain("__omega_selfcheck__") val leaf = X509Certificate.parse(chain[0]) val ext = leaf.getExtension(KeyDescription.OID) return SelfCheckResult( verifiedBootState = ext.teeEnforced.rootOfTrust.verifiedBootState, rkpAvailable = chain.last().issuer.matches(GoogleRkpRoot), // ... ) } ``` -------------------------------- ### KmRequest and KmResponse message flow Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/docs/protocol-v2-rfc.md Shows the request/response flow for KeyMint operations after a session is opened. The Consumer sends KmRequest with the session_id and operation, and the Provider replies with KmResponse containing the session_id and result. ```text Consumer → ... → Provider: KmRequest { session_id, op: KmOp } Provider → ... → Consumer: KmResponse { session_id, result: KmResult } ``` -------------------------------- ### Set RUST_LOG for logging verbosity Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/server/README.md Controls the verbosity of the tracing-based logging. The default is info; setting omega_server=debug enables debug for the crate while keeping info for dependencies; trace is very noisy. ```bash RUST_LOG=info # default RUST_LOG=omega_server=debug # debug for our crate, info for deps RUST_LOG=trace # very noisy ``` -------------------------------- ### Deploy relay server without TLS Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md Deploy the relay server without TLS, intended for use behind an nginx reverse proxy. Requires root privileges. ```bash sudo OMEGA_PSK="your-secret-key" OMEGA_NO_TLS=1 bash OmegaRelay/vps/install.sh ``` -------------------------------- ### Define KmOp enum for KeyMint operations Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/docs/protocol-v2-rfc.md Defines the KmOp tagged enum mirroring the AIDL IKeystoreSecurityLevel / IKeystoreOperation interfaces. Covers key generation, retrieval, subcomponent updates, and operation lifecycle (Begin, Update, Finish, Abort) plus DeleteKey. ```rust enum KmOp { GenerateKey { params: Vec, // tags: PURPOSE, ALGORITHM, // ATTESTATION_CHALLENGE, // ATTESTATION_APPLICATION_ID, etc. attestation_key_alias: Option, }, GetKeyEntry, // returns chain + metadata UpdateSubcomponent { public_cert: Option>, cert_chain: Option> }, Begin { purpose: KeyPurpose, params: Vec, // operation params (e.g. PADDING, DIGEST) }, Update { op_handle: u64, input: Vec, aad: Option>, }, Finish { op_handle: u64, input: Option>, signature: Option>, aad: Option>, }, Abort { op_handle: u64, }, DeleteKey, } ``` -------------------------------- ### Force reconnect relay (Consumer) with adb Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md Force reconnect the relay on the Consumer side. The relay client runs inside the keystore2 process; killing it triggers auto-restart and module re-injection. A full reboot is the most reliable method. ```bash adb shell "su -c 'killall keystore2'" ``` ```bash adb reboot ``` -------------------------------- ### Relay scope configuration in omega-relay.conf Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/docs/protocol-v2-rfc.md Configuration snippet for setting the relay scope in omega-relay.conf, controlling which callers are forwarded to the relay. ```ini relay_scope = gms-only # or "all", "uid-list:10000,10001" ``` -------------------------------- ### DeviceContext Struct Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/docs/protocol.md Defines the DeviceContext struct used by ReLeaf to forge attestation extension fields. All fields are optional and include device identifiers, OS versions, and verified boot state. ```rust struct DeviceContext { brand: Option, device: Option, product: Option, manufacturer: Option, model: Option, os_version: Option, os_patch_level: Option, vendor_patch_level: Option, boot_patch_level: Option, verified_boot_key: Option>, verified_boot_hash: Option>, verified_boot_state: Option, // 0=Verified, 1=SelfSigned, 2=Unverified, 3=Failed device_locked: Option, } ``` -------------------------------- ### Force reconnect relay (Provider) with adb Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/README.md Force reconnect the relay on the Provider side by stopping the Provider app service. Reopen the app or it will auto-restart via BootReceiver on next boot. ```bash adb shell "su -c 'am force-stop org.ommega.relay.provider.app'" ``` -------------------------------- ### Define KmResult enum for KeyMint responses Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/docs/protocol-v2-rfc.md Defines the KmResult enum returned by the Provider for each KmOp. Includes success variants with key material and metadata, acknowledgements for UpdateSubcomponent/Abort/DeleteKey, and an Error variant carrying a negative KeyMint ErrorCode and optional message. ```rust enum KmResult { GenerateKey { cert_chain: Vec>, public_key_der: Vec, key_metadata: KmKeyMetadata, }, GetKeyEntry { cert_chain: Vec>, public_key_der: Vec, key_metadata: KmKeyMetadata, }, UpdateSubcomponent, // ack Begin { op_handle: u64, params: Vec, // sometimes the HAL adds back nonce / iv }, Update { output: Vec, }, Finish { output: Vec, // signature for sign ops, ciphertext for crypt }, Abort, // ack DeleteKey, // ack Error { error_code: i32, // KeyMint ErrorCode (negative) message: Option, }, } ``` -------------------------------- ### Add v2 Payload variants for KeyMint sessions Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/docs/protocol-v2-rfc.md Defines the new top-level Payload variants added in protocol version 2 for KeyMint session management. Use this when extending the wire protocol to support OpenKmSession, KmSessionOpened, KmRequest, KmResponse, CloseKmSession, and unsolicited KmSessionEvent messages. ```rust enum Payload { // ... existing v1 variants ... // v2 additions: OpenKmSession(OpenKmSession), KmSessionOpened(KmSessionOpened), KmRequest(KmRequest), KmResponse(KmResponse), CloseKmSession(CloseKmSession), KmSessionEvent(KmSessionEvent), // unsolicited from provider (e.g. key invalidated) } ``` -------------------------------- ### OmegaRelay service operations Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/vps/README.md Common operations for the omega-relay service: check status, view logs, restart after config edits, and reload-or-restart (which restarts because reload is not supported). ```bash # Status systemctl status omega-relay ``` ```bash # Logs journalctl -u omega-relay -f ``` ```bash # Restart after editing /etc/omega-relay/config.toml systemctl restart omega-relay ``` ```bash # Reload only (NB: server doesn't currently support reload, so this restarts) systemctl reload-or-restart omega-relay ``` -------------------------------- ### Task Structure and TaskType Enum Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/docs/protocol.md Defines the Task structure and its TaskType variants for attestation, signing, and external key attestation. Includes supporting enums for key algorithms, purposes, and signing algorithms. ```rust struct Task { id: Uuid, task_type: TaskType, timeout_ms: u32, // max wait time on consumer side metadata: HashMap, } enum TaskType { /// Generate a new key with attestation Attest { challenge: Vec, // raw bytes alias_hint: String, // optional, used for telemetry algorithm: KeyAlgorithm, // EC_P256 | RSA_2048 purpose: KeyPurpose, // SIGN | ATTEST_KEY attestation_application_id: Option>, device_context: Option, }, /// Sign data using a key referenced by alias (rare, usually keys live on Device A) Sign { alias: String, data: Vec, algorithm: SignAlgorithm, }, /// Attest an externally provided public key (Android 12+, PURPOSE_ATTEST_KEY) /// This is the preferred mode: key lives on Device A, cert chain comes from Device B AttestExternalKey { challenge: Vec, external_public_key_der: Vec, // SubjectPublicKeyInfo DER attestation_application_id: Option>, device_context: Option, }, } enum KeyAlgorithm { EcP256, EcP384, Rsa2048, Rsa3072, Rsa4096, } enum KeyPurpose { Sign, AttestKey, // PURPOSE_ATTEST_KEY (API 31+) } enum SignAlgorithm { Sha256WithEcdsa, Sha256WithRsa, } ``` -------------------------------- ### TaskResult and TaskResultPayload Source: https://github.com/andrea-lyz/teesimulator-rs-online/blob/main/OmegaRelay/docs/protocol.md Defines the TaskResult structure and its payload variants for attestation, signing, and external key attestation results. Includes TimingInfo for server-side timing metrics. ```rust struct TaskResult { task_id: Uuid, success: bool, payload: Option, error: Option, server_timing: Option, } enum TaskResultPayload { Attest { cert_chain: Vec>, // DER-encoded X.509, leaf first public_key_der: Vec, }, Sign { signature: Vec, }, AttestExternalKey { cert_chain: Vec>, }, } struct TimingInfo { received_at_server_ms: u64, dispatched_to_provider_ms: u64, received_from_provider_ms: u64, } ```