XmobiTea AntiMod

Build-time checksum and integrity validation package for Unity Android/iOS builds.

AI Quick Contract

• Main runtime API: await CheckSumChecker.TryValidate()
• Main settings asset: Resources/XmobiTea AntiModSettings.asset
• This package depends heavily on editor-time generation and post-build hooks
• Runtime validation is meaningful mainly on Android and iOS
• In UNITY_EDITOR, validation always returns success
• On non-Android/non-iOS player targets, runtime currently falls back to the editor checker and also returns success
• Android build flow can require a rebuild because integrity.json is generated in post-process after the build output already exists
• iOS unknown-framework detection currently contains a runtime bug: it can return isValid = true even when it reports unknown files

What This Package Provides

• AntiModSettings: resource-backed config plus encoded secret fields
• CheckSumChecker: runtime entry point
• CheckSumUtils: hashing, signature, AES encode/decode helpers
• CheckSumGenerateEditor: post-build integrity generation and platform injection
• AntiModSettingsEditor: editor workflow for generating encoded settings

Exact Runtime Behavior

CheckSumChecker.TryValidate()

TryValidate() behaves like this:

1. In UNITY_EDITOR, it immediately returns new CheckSumResult(true, null).
2. On device, it resolves the integrity file name from CheckSumUtils.GetOriginNameIntegrityJsonFile().
3. It loads that file from StreamingAssets.
4. It deserializes integrity.json into CheckSumData.
5. It recomputes the signature over entries and compares it with the stored signature.
6. It dispatches to:
   • AndroidCheckSumCheckerInternal
   • iOSCheckSumCheckerInternal
   • fallback EditorCheckSumCheckerInternal on other runtime targets

Important consequence: this package is not a generic desktop anti-tamper solution. Outside Android/iOS, current runtime behavior is effectively permissive.

Android Runtime Validation

Android validation:

1. finds installed .apk files in the app install directory
2. detects whether the current install is arm64 or armeabi-v7a
3. decrypts each stored path from integrity.json
4. searches that path inside the installed APK files
5. computes SHA-256 and compares it with the stored hash

If any required entry is missing or mismatched, validation fails.

iOS Runtime Validation

iOS validation:

1. resolves the .app install root
2. decrypts each stored path from integrity.json
3. reads each file from the installed app bundle
4. compares SHA-256 with the stored hash
5. optionally validates UnityFramework when iOSCheckSumUnityFramework is enabled
6. optionally validates allowed framework names when iOSCheckKnownFileInFrameworks is enabled

Current quirk: the "unknown files in Frameworks" branch returns new CheckSumResult(true, "...") instead of failing. That is current runtime behavior, not intended design.

AntiModSettings

AntiModSettings is loaded from:

Resources/XmobiTea AntiModSettings.asset

It contains:

• toggle flags for iOS checks
• XOR keys for encoded fields
• encoded secret data used at runtime

Editor-only localSecretKeySettings is loaded from:

Assets/XmobiTea-constant/AntiMod_localSecretKeySettings.json

That JSON file is not the runtime source of truth. Runtime uses the encoded fields stored inside the asset.

Editor Workflow

Open/Create Settings

Menu:

XmobiTea Tools/AntiMod/Open Settings

If the resource asset does not exist, editor code creates it automatically.

Generate Encoded Secret Fields

Inspector button:

Fetch Encode Secret Key Settings

This action:

1. writes Assets/XmobiTea-constant/AntiMod_localSecretKeySettings.json
2. XOR-encodes the configured secret strings
3. AES-encodes the integrity file name and framework allowlist entries
4. writes the encoded byte arrays back into AntiModSettings

This step is required before runtime validation can work correctly.

Post-Build Hook

CheckSumGenerateEditor.OnPostprocessBuild(...) runs after build.

It:

1. computes hashes for configured important files
2. generates integrity.json
3. writes that file into Assets/StreamingAssets/
4. then performs platform-specific follow-up

Android follow-up:

• checks whether the built APK/AAB already contains the generated integrity file
• if not, it logs need rebuild

Practical consequence: Android workflow may require building again after the first generation pass.

iOS follow-up:

• copies integrity.json into Data/Raw/
• optionally injects an Xcode shell script that generates ufsignature.txt

Required Setup

1. Create/open Resources/XmobiTea AntiModSettings.asset.
2. Configure local secret values and important file lists in the custom inspector.
3. Click Fetch Encode Secret Key Settings.
4. Build the app so post-process generation can produce integrity data.
5. On Android, be prepared to rebuild after the first pass if the tool reports missing integrity data.
6. Call await CheckSumChecker.TryValidate() early at app startup on device.

Basic Usage

using System.Threading.Tasks;
using UnityEngine;
using XmobiTea.AntiMod;

public sealed class AntiModBootstrap : MonoBehaviour
{
    private async void Start()
    {
        var result = await CheckSumChecker.TryValidate();
        if (!result.isValid)
        {
            Debug.LogError("[AntiMod] Validation failed: " + result.error);
            Application.Quit();
        }
    }
}

Do / Don't

Do

• Do treat this package as a build-time plus runtime workflow.
• Do generate encoded settings before relying on runtime validation.
• Do call TryValidate() on real device builds, not just in editor.
• Do expect Android and iOS to behave differently.
• Do keep the important file lists aligned with the actual built output.

Don't

• Don't assume editor validation proves anything about a real build.
• Don't assume desktop or other non-mobile targets are meaningfully protected by the current runtime.
• Don't edit encoded runtime fields by hand.
• Don't forget that Android may need a rebuild after integrity generation.
• Don't assume the iOS known-framework check is currently reliable.

Common Mistakes

Mistake 1: Using editor success as real validation

In editor, TryValidate() always returns success.

Mistake 2: Forgetting to generate encoded settings

If Fetch Encode Secret Key Settings was never run, runtime secrets and file name decoding can be invalid.

Mistake 3: Expecting Android first build to already contain integrity.json

Current workflow generates that file in post-process, so the first Android build can legitimately ask for a rebuild.

Mistake 4: Assuming all player targets are protected

Current non-Android/non-iOS runtime path falls back to the permissive editor checker.

Namespace

using XmobiTea.AntiMod;

Package Metadata

• Package name: com.xmobitea.changx.antimod
• Version: 1.5.0
• Unity version: 2022.3+
• License: Apache-2.0