Get Started

Overview

OZero Security protects Unity games by running security logic in the Native C++ layer, where most hacking tools cannot reach. The SDK provides ready-to-use modules that you enable through a simple dashboard inside the Unity Editor. No manual scene setup or boilerplate code is required to get the core protection running.

1 Import the Package

Open the Unity Editor and import the OZero Security package. You can import it via the Unity Package Manager or by double-clicking the .unitypackage file.

In the Import Unity Package dialog that appears, leave all items checked and click Import. All required scripts, native plugins, and editor tools will be added to your project automatically.

2 Open the Dashboard

Once the import is complete, open the OZero Security Dashboard from the Unity menu bar:

A custom Editor window will open. This is the central control panel for all OZero security modules. You do not need to touch anything in the Project hierarchy — everything is managed here.

3 Enable Modules

Inside the Dashboard, you will see a list of available security modules with toggle switches. Enable the modules you want to use. The recommended starting set is shown below.

Security Presets

Choose a preset first, then adjust individual modules only when your project needs a custom policy. For most live games, start with Standard because it balances protection, performance, and false-positive risk.

You do not need to press any "Auto Setup" button. Toggle the modules you want enabled in the Dashboard and save the OZeroSecurityConfig asset. At player launch, the SDK prepares enabled detectors automatically before gameplay starts.

License Model — Standard / Plus / Pro

OZero Security ships in three tiers. Standard is fully serverless with the shared native module. Plus stays serverless but adds app-specific Native Variant packages bound by manifest and Bundle ID. Pro includes Plus and unlocks server-side capabilities such as Cloud Telemetry, Signed Time, remote policy, attestation, and per-device limits.

Registering a Plus / Pro License Key

Standard tier needs no setup. For Plus or Pro, add one ScriptableObject asset and paste the key you received after purchase. Plus uses the key for project-bound Variant validation and portal downloads; Pro also uses it for runtime server activation.

1. Create the config asset

In the Project window, Assets → Create → OZero → License Config. Place the asset under any folder named Resources/ and rename it to exactly OZeroLicenseConfig (case sensitive — the runtime calls Resources.Load<OZeroLicenseConfig>("OZeroLicenseConfig")).

2. Fill in the Inspector fields

3. Build & verify

No code change is required. OZeroLicenseBootstrap wires itself via [RuntimeInitializeOnLoadMethod(AfterAssembliesLoaded)] and reads the asset at app start. Watch the Player log on first launch for a line like [OZeroLicense] activated; tier=pro caps=5. If you see [OZeroLicense] Standard / serverless mode. with a Pro config in place, double-check that the asset is under a Resources/ folder and named OZeroLicenseConfig (no extension, no rename suffix).

Server Activation Flow

The activation flow runs in the background at app start. The SDK never blocks scene load on it — even on a 6-second timeout the cached entitlement (or Standard fallback) is used so your players never sit on a black screen waiting for HTTP.

Boot sequence

1. The SDK initializes the license runtime automatically at startup.
2. Standard and Plus continue without a runtime server call.
3. Pro sends a lightweight activation request in the background.
4. If activation succeeds, Pro server features such as telemetry, signed time, and attestation become available.
5. If activation fails, expires, or times out, gameplay continues in Standard mode without showing an error to players.

What goes over the wire

The activation request is a small JSON POST. Required fields are licenseKey, deviceId, sdkVersion, and platform. appIdentifier, companyName, productName, and webglOrigin are added only when Unity provides non-empty values. You can override the device id source via OZeroLicenseRuntime.DeviceIdProvider.

POST https://api.ozero.security/v1/activate
Content-Type: application/json

{
  "licenseKey":    "OZ-PRO-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX",
  "deviceId":      "<DeviceIdProvider result; default SystemInfo.deviceUniqueIdentifier>",
  "sdkVersion":    "<OZeroSdkVersion.ManagedVersion>",
  "platform":      "<android | ios | windows | macos | linux | webgl | ...>",
  "appIdentifier": "<Application.identifier>",
  "companyName":   "<Application.companyName>",
  "productName":   "<Application.productName>",
  "webglOrigin":   "<WebGL origin only>"
}

The server replies with a JSON body containing a JWT-shaped signedToken (header.payload.signature, base64url, no padding), the resolved tier, a capabilities array, a serverFeaturesEnabled flag, and (optionally) an expiresAt unix-ms. The SDK calls OZerodigital signature.VerifySignature on the signedToken using your serverPublicKeyHex and only then accepts the entitlement — anything else is fail-closed.

Graceful degradation

Server maintenance, network timeouts, license expiry, suspension, revocation, and bundle mismatch are not treated as tamper. They downgrade Pro-only features to Standard/serverless mode so the player session stays alive. Confirmed tamper states such as build mismatch, blocked build, injection, and debugger detection follow the configured threat-response policy.

Offline Behaviour

OZero is designed so your players can always launch your game, regardless of network state. The exact behaviour depends on the tier:

Standard — always offline

No server is contacted, ever. All nine detector modules run with no degradation. The license runtime sets IsServerless = true and HasEntitlement = false. OZeroTelemetryReporter attaches but no-ops on every event.

Pro — offline within TTL

After the first successful /v1/activate on a given device, the entitlement is cached in PlayerPrefs (encrypted with a device-bound key — see Cache Security below). On subsequent launches the cache is read synchronously before the network call even starts, so if the player is offline the SDK still knows what tier they are on and which capabilities are unlocked.

The cached entitlement is trusted for tokenTtlSeconds from the cachedAtMillis stamp written at activation time. Default is 7 days (604800). After TTL expiry on a device that has been offline the whole time, the cache is dropped and the SDK degrades to Standard capabilities until the next successful activation. Detectors keep working — only telemetry posting and signed-time validation turn off.

Pro — signed offline block policy

Graceful degradation is for license, network, and server availability failures. It does not mean that an explicitly blocked build becomes allowed offline. When Pro activation succeeds, the server signs the current portal block policy into the activation token and the SDK caches that policy separately from the entitlement.

With the recommended ApplyCachedBlockPolicies mode, blocked manifest hashes, SDK versions, and app versions are still rejected by Build Integrity while the signed policy is valid, even if the player turns on airplane mode. The policy follows the signed token TTL, so run one successful online activation after changing portal block rules.

Troubleshooting

Every license event is logged through OZeroSecLog, which routes to Unity's Debug.Log by default (configurable in OZeroSecurityConfig). Filter the Player log by the [OZeroLicense] prefix to see the boot-time decisions; [OZeroTelemetry] for the reporter. Common symptoms and fixes:

Project Settings

Before configuring individual security modules, check the Unity Player Settings that affect native plugins, store builds, and platform validation.

Minimum Build Targets

Android ProGuard / R8 Settings

OZero Security does not require a separate Java SDK package, but Android release builds that enable Minify, ProGuard, or R8 must preserve Unity's Java bridge and any custom Android bridge classes used by your project. This keeps JNI calls for package information, installer source, APK signing certificate checks, and boot asset loading stable after obfuscation.

# OZero Security - Unity Android ProGuard/R8 keep rules
-keep class com.unity3d.player.UnityPlayer { *; }
-keep class com.unity3d.player.UnityPlayerActivity { *; }
-keep class com.unity3d.player.UnityPlayerGameActivity { *; }
-keep class com.unity3d.player.UnityPlayerForActivityOrService { *; }
-keepattributes *Annotation*,InnerClasses,EnclosingMethod,Signature

# If your game adds custom Java/Kotlin bridge classes that OZero or your code
# calls through AndroidJavaClass / AndroidJavaObject, keep those classes too.
# Replace the package below with your own bridge package.
# -keep class com.yourcompany.yourgame.bridge.** { *; }

• Do not rename, remove, or repackage libOZeroSecurity.so. Keep the plugin under Assets/OZeroSDK/Plugins/Android/arm64-v8a and, if you ship 32-bit builds, armeabi-v7a.
• When Build Integrity > Check Platform Native and Android SHA Keys are enabled, test the final signed APK or AAB after Minify/R8. Debug keystore fingerprints and release keystore fingerprints are different.
• If Android logs show JNI lookup failures, installer-source detection failures, or APK signature checks returning empty results only after Minify is enabled, review your custom bridge keep rules first.
• For store releases, build with IL2CPP, release signing, the expected Android SHA-256 fingerprint registered in Android Sha Keys, and a clean launch test on at least one real device.

5 Configure OZeroSecurityConfig

The OZeroSecurityConfig ScriptableObject asset is included when you import the package. Select it in the Project window to inspect and adjust all security module settings. The config is a singleton — access it at runtime via OZeroSecurityConfig.Instance.

General Settings

These top-level fields apply globally across all modules.

Response Settings

Controls what happens when any security module fires a detection event.

Build Integrity Settings

Configures the build integrity validator that detects modified game files, debugger attachment, and suspicious runtime environments.

Generate RSA Signing Keys (Build Integrity)

If you have enabled Build Integrity with Require Manifest Signature turned on, OZero uses public-key signature asymmetric signing to guarantee that the integrity manifest has not been replaced or tampered with. Before making any release build you must generate a key pair from inside the Unity Editor.

How manifest signing works

At build time, OZero signs the assembly manifest with your private key and embeds the resulting signature in the build. At runtime, the public key stored in OZeroSecurityConfig verifies that signature. If the signature does not match — meaning the manifest or the binary was altered — the game treats it as tampering and responds according to your Response Settings.

Generating the key pair

1. In the Unity Editor, select OZeroSecurityConfig in the Project window.
2. In the Inspector, expand the Build Integrity section.
3. Enable the Require Manifest Signature checkbox.
4. Click the Generate Key Pair button.
5. OZero generates an public-key signature key pair. The public key is written directly into OZeroSecurityConfig (stored in your Assets). The private key is saved to:
   [ProjectRoot]/OZeroSigningKeys/manifest_private_key.pem
6. A confirmation dialog shows the private key location. Click OK to dismiss it.

⚠ Critical — private key safety

• The private key file is stored outside the Assets/ folder so Unity does not include it in builds. Never move it inside Assets/.
• Add OZeroSigningKeys/ to your .gitignore immediately. Committing the private key to version control is a critical security risk.
• Back up the private key to a secure, offline location (encrypted USB drive, password manager, etc.). Anyone with this file can forge a valid manifest for your game.
• If you lose the private key, you must generate a new key pair. The new public key will be embedded in the next build. All previously shipped builds that carry the old signature will fail manifest verification and must be replaced.

Custom private key path (CI/CD & teams)

The Manifest Signing Private Key Path field (visible in the Inspector under Manifest Signing — Editor Only) lets you specify an alternative location for the private key. This is useful in two scenarios:

• CI/CD pipelines — Store the private key as a CI secret and inject its path at build time so the build machine never needs the key on disk permanently.
• Team environments — Keep the key on a shared secure server or secrets manager and point the field at the mounted path. Only the team member running the release build needs access.

Validating an existing key pair

If you are unsure whether the private key on disk still matches the public key stored in OZeroSecurityConfig, click the Validate Key Pair button. OZero will sign a small test payload with the private key and verify it with the public key. If they match, a success notice appears. If not, you must generate a new pair.

When to re-generate the key pair

• Private key is lost or compromised.
• Validate Key Pair reports a mismatch (keys are out of sync).
• Deliberately rotating keys as part of a scheduled security policy.

After re-generating, the new public key is embedded in the next build automatically. Any existing shipped builds will fail manifest verification with the new public key — you will need to push an update.

Dual-fingerprint key rotation (zero-downtime)

The Generate Key Pair button stores the public key in two places at once: inside OZeroSecurityConfig (a ScriptableObject in your Assets), AND as a SHA-256 fingerprint constant inside Assets/OZeroSDK/Scripts/Security/BuildIntegirity/OZeroManifestTrustAnchor.cs. At runtime the SDK first checks that the public key in the asset matches the pinned fingerprint in the assembly — if they don't match, the manifest is rejected even before the RSA signature is checked. This closes the repacker attack where someone swaps both the asset and the .sig file with attacker-owned keys.

Two fingerprint slots

Inside OZeroManifestTrustAnchor.cs there are two const slots: ExpectedPublicKeyFingerprintHex (the current production fingerprint) and PreviousPublicKeyFingerprintHex (an optional second fingerprint, empty in steady state). The Matches() verifier returns true if the live SPKI hash equals either value, using a constant-time XOR compare. This dual-slot model is the foundation of the "zero-downtime key rotation" feature on the homepage: a freshly built SDK can trust BOTH the new key (Expected) AND the old key (Previous) for a bounded grace window, so old shipped builds keep verifying their old manifests while you push the new release.

Rotation procedure (manual, but takes 5 minutes)

1. Note the current fingerprint. Open Assets/OZeroSDK/Scripts/Security/BuildIntegirity/OZeroManifestTrustAnchor.cs and copy the value of ExpectedPublicKeyFingerprintHex into your clipboard (or a scratch file).
2. Move it into the previous slot. In the same file, paste the value into PreviousPublicKeyFingerprintHex (which is normally ""). Save.
3. Generate the new key pair. In the Inspector for OZeroSecurityConfig, click Generate Key Pair. The dialog will warn that this invalidates previously baked manifests — click Regenerate. The new private key is written to the PEM file, the new public key replaces the asset value, and the new SHA-256 fingerprint is auto-injected into ExpectedPublicKeyFingerprintHex. Your PreviousPublicKeyFingerprintHex from step 2 is left untouched.
4. Build and ship the new SDK release through your normal patch / store channel. New manifests in this build are signed with the new private key.
5. Wait for fleet rollover. During the grace window the new build trusts both kids; the old build (still pinning only the old fingerprint as Expected) keeps verifying its own old manifest. Neither path breaks. Typical window: 1–4 weeks for a live game.
6. Clear the previous slot. Once telemetry confirms the old build is at 0%, set PreviousPublicKeyFingerprintHex = "" and ship one more SDK release. Rotation complete.

Why "no forced update" works

The old shipped binary already contains an old manifest signed by the old key, AND an embedded copy of the old fingerprint as its Expected slot — it does not need to know anything about the new key to keep working. The new build needs the Previous slot only so that, if a player force-reinstalls or rolls back to an old version mid-window, the cached old manifest still verifies. Once the old build is gone from the field, you can clear Previous in the next release.

Troubleshooting

All five symptoms below come from the same defence stack — the build-time PreBuild validator (OZeroBuildPreflightValidator), the boot-time anchor guard (OZeroManifestTrustAnchor.ValidateConfigurationOrFail), and the runtime verifier (OZeroBuildIntegrityValidator.VerifyManifestSignature). The fix in each case is to bring the three artefacts (private key PEM, public key in OZeroSecurityConfig, fingerprint in OZeroManifestTrustAnchor) back into sync.

Symptom 1 — release build aborts immediately on launch with reason code 0x0E (TRUST_ANCHOR_MISSING)

ExpectedPublicKeyFingerprintHex is an empty string. Editor and Development builds tolerate this with a warning, but release builds fail-fast at boot before any untrusted manifest can be accepted. Fix: run Generate Key Pair once in the Editor — it auto-injects the fingerprint into the const. If the const is already populated but the build still aborts, the assembly hash blob (oz_ahash.bin) may be out of date — rebuild from a clean state.

Symptom 2 — build halts with "no manifest signing public key is configured" before compilation starts

The PreBuild validator (callbackOrder 51) caught that OZeroSecurityConfig.Integrity.ManifestSigningPublicKey is empty. Fix: open OZeroSecurityConfig in the Inspector → expand Build Integrity → click Generate Key Pair, then rebuild. Note: this check is skipped on Android / iOS (OS-level signing) and on IL2CPP Standalone (no per-DLL files to sign), so a missing key only blocks Mono Standalone targets.

Symptom 3 — runtime log: "Manifest signing public key does NOT match the pinned trust anchor fingerprint — APK appears to have been repacked with attacker-controlled keys"

The public key string in OZeroSecurityConfig hashes to a value that matches neither ExpectedPublicKeyFingerprintHex nor PreviousPublicKeyFingerprintHex. In a legitimately built binary this happens after a manual edit got the two artefacts out of sync. Fix: in the Editor, run Tools → OZero → Validate Manifest Signing Keys — if the key pair is consistent the tool will auto-rewrite the const for you. If it reports a mismatch, regenerate the pair via Generate Key Pair. In a tampered binary, this message is the intended fail-closed signal — investigate whether the APK / .exe was repacked.

Symptom 4 — after rotating, players on the OLD shipped build start failing manifest verification

You forgot step 2 of the rotation procedure. The new SDK release shipped with PreviousPublicKeyFingerprintHex = "", so a player who already had the old build cached and force-restarts hits a manifest signed under the new key (which their old build doesn't trust) — or, worse, a force-reinstall pulls down a freshly cached old manifest that the trust anchor in their old build can't verify because the PEM has rotated. Fix: ship a hotfix SDK release with PreviousPublicKeyFingerprintHex set to the old fingerprint; the next manifest fetch will verify under either kid.

Symptom 5 — local builds work, but CI builds fail with "private key not found" or sign with the wrong key

CI machines do not have OZeroSigningKeys/manifest_private_key.pem on disk because it is correctly excluded by .gitignore. Fix: store the PEM as a CI secret (GitHub Actions Secret, GitLab Variable, Jenkins Credentials, etc.) and have the pipeline write it to OZeroSigningKeys/manifest_private_key.pem in the workspace before the Unity build step. Alternatively, set Manifest Signing Private Key Path in OZeroSecurityConfig to a path the CI runner can mount (e.g. a secrets-manager mount). Make sure every CI runner uses the SAME PEM — different PEMs produce different signatures even when the public key matches.

Install Source Settings

Restricts the game to only run when installed from authorized stores or sources. Useful for preventing sideloaded or repackaged APKs.

Steam Anti-Piracy Settings

Checks Steam launch path, App ID, entitlement state, and release hygiene for PC builds distributed through Steam. Standard performs local validation; stronger ownership verification through Steam server evidence is provided by Pro server Steam Attestation.

Device Binding Settings

Binds a game account to the original device using a hardware fingerprint. Detects account transfers to different hardware.

Commercial operations purpose

Device Binding is most useful as a Pro operations layer: it connects a license to server-registered hardware fingerprints so your team can isolate risky devices, reduce casual license sharing, and support legitimate device changes without turning the entire license off.

Reset Token support flow

1. Confirm the player account and the reason for reset through your normal support process.
2. Open Customer Portal → Device Binding, find the target device, and issue a Reset Token.
3. Send the token only through an authenticated support channel. Do not store it in long-lived public chat or screenshots.
4. Your game or support UI should pass the token to OZeroDeviceBindingDetector.Instance?.ClearStoredFingerprint(token.Trim()).
5. After the SDK consumes the token, restart or re-enter the protected startup flow so the current hardware fingerprint is registered again.

Speed & Time Hack Settings

Detects time-scale manipulation (speed hacks) by comparing Unity Time.realtimeSinceStartup against native platform timers and optionally a trusted web time source.

Physics Hack Detector

Injection & Hooking Settings

Detects unauthorized code injection such as assembly injection, DLL hijacking, or IL2CPP patching.

Encrypt PlayerPrefs

To protect data stored in Unity's PlayerPrefs (settings, user preferences, etc.), replace PlayerPrefs with OZeroSafePlayerPrefs. The API is identical.

using OZeroSDK.Security;

// Save a value
OZeroSafePlayerPrefs.SetInt("score", 4200);
OZeroSafePlayerPrefs.SetFloat("volume", 0.8f);
OZeroSafePlayerPrefs.SetString("username", "Hero");

// Read a value
int    score    = OZeroSafePlayerPrefs.GetInt("score", 0);
float  volume   = OZeroSafePlayerPrefs.GetFloat("volume", 1.0f);
string username = OZeroSafePlayerPrefs.GetString("username", "");

Encrypt Save Files

To encrypt save files, use OZeroSV_File instead of File.ReadAllText / File.WriteAllText. The file is automatically encrypted on write and decrypted on read. Tampering is detected on load.

using OZeroSDK.Security;

string path = Application.persistentDataPath + "/save.json";

// Write encrypted file
OZeroSV_File.WriteAllText(path, jsonString);

// Read and decrypt file
string json = OZeroSV_File.ReadAllText(path);

4 Protect In-Game Variables (Secure Types)

Secure Types replace ordinary C# variable types with encrypted equivalents. Values are stored in the Native C++ heap so tools like Cheat Engine cannot find them by scanning memory. The replacement is a simple name swap — all operators and implicit conversions work the same way.

Supported types

Example

// ── Before: plain C# variable ──────────────────────────────
using UnityEngine;

public class PlayerStats : MonoBehaviour
{
    public int   gold  = 0;
    public float speed = 5.0f;
    public int   hp    = 100;
}

// ── After: OZero Secure Types (only the type name changes) ──
using UnityEngine;
using OZeroSDK.Security;

public class PlayerStats : MonoBehaviour
{
    public OZeroSV_Int   gold  = 0;
    public OZeroSV_Float speed = 5.0f;
    public OZeroSV_Int   hp    = 100;

    // All arithmetic works exactly as before — no code changes needed
    void TakeDamage(int dmg) => hp -= dmg;
    void AddGold(int amount) => gold += amount;
}

7 Handle Security Events (Optional)

By default, OZero force-quits the application when it detects a threat (if Force Quit On Detection is enabled). If you prefer to handle threats yourself — for example, to show a warning screen, log the event to your server, or apply in-game penalties — you can register a callback.

using UnityEngine;
using OZeroSDK.Security;

public class SecurityHandler : MonoBehaviour
{
    void OnEnable()
    {
        // RegisterUserCallback runs on the user chain only.
        // The built-in default handler runs independently and cannot be silenced.
        OZeroSecurityManager.Instance.RegisterUserCallback(OnThreatDetected);
    }

    void OnDisable()
    {
        OZeroSecurityManager.Instance.UnregisterUserCallback(OnThreatDetected);
    }

    void OnThreatDetected(OZeroSecurityEvent evt)
    {
        // evt contains Type, AbortCode, AbortCodeHex, MessageKey, Message, and WillAbort.
        Debug.LogWarning(
            $"OZero threat: {evt.Type} {evt.AbortCodeHex} {evt.Message}");

        switch (evt.Type)
        {
            case ModulationType.SpeedHack:
                // e.g. kick the player, show warning, report to server
                break;

            case ModulationType.BuildIntegrity:
                // evt.WillAbort is usually true for fatal build integrity violations.
                break;

            case ModulationType.Injection:
                break;
        }

        if (evt.WillAbort)
        {
            // Last chance to flush your own analytics or save state.
        }
    }
}

The full list of ModulationType values is documented in the API Reference.

Next Steps

You now have the core OZero protection running. Explore the full API Reference to learn about every class, method, and configuration option in detail.