入门

概述

OZero Security 通过在一般黑客工具难以访问的 Native C++ 层执行安全逻辑来保护 Unity 游戏。只需在 Unity 编辑器内的仪表板中激活模块，即可运行核心保护功能。无需场景设置或编写额外代码。

1 导入包

打开 Unity 编辑器并导入 OZero Security 包。您可以通过 Unity 包管理器或双击 .unitypackage 文件进行导入。

当出现 Import Unity Package 对话框时，在勾选所有项目的情况下点击 Import。所需的脚本、原生插件和编辑器工具将自动添加。

2 打开仪表板

导入完成后，从 Unity 菜单栏打开 Config Dashboard：

打开 Config Dashboard 后，可以在此屏幕上一次性管理预设、安全模块、许可证和构建完整性设置。无需在 Project 窗口中直接查找并修改文件。

Unity 编辑器菜单说明

OZeroSDK > Security 菜单集中提供 SDK 设置和诊断命令。安全预设有意放在 Config & Dashboard 中应用，而不是放在顶部菜单中，这样您可以在保存前确认实际变更的设置。

3 激活模块

在仪表板内可以查看安全模块列表及切换开关。请激活您要使用的模块。以下是推荐的初始配置。

选择安全预设

首先选择一个预设，然后根据项目进行个别模块调整。对于一般的实时在线游戏，建议从 Standard 开始。这能在保护级别、性能和误报率之间取得最佳平衡。

只需在仪表板中开启要使用的模块并保存 OZeroSecurityConfig 资产即可。播放器启动时，SDK 会自动准备已激活的模块。

许可证模型 — Standard / Plus / Pro

OZero Security 提供 Standard、Plus、Pro 三种等级。Standard 模式不与服务器联动，仅使用本地保护功能。Plus 模式在此基础上加入了各项目特定的 Native Variant 包及清单 / Bundle ID 绑定。Pro 模式包含 Plus 的配置，并增加了遥测、签名验证的服务器时间、远程策略、服务器校验以及设备限制等运营功能。

Plus / Pro 许可证密钥注册

Standard 级别无需额外设置。Plus 或 Pro 需要添加 1 个 ScriptableObject 资产并将购买后获得的密钥粘贴进去。Plus 密钥用于分项目的 Variant 校验与门户下载，而 Pro 密钥还会被用于运行时服务器激活。

1. 创建设置资产

打开 Config Dashboard (菜单: OZeroSDK → Security → Config Dashboard) ，在 License & Server 栏目点击 Create OZeroLicenseConfig 按钮。资产会自动生成到正确的 Resources/ 文件夹，无需手动移动。

2. 填写 Inspector 字段

3. 构建与验证

无需修改代码。应用启动时 SDK 将自动读取 OZeroLicenseConfig 资产。首次执行后，请在 Player 日志中寻找类似于 [OZeroLicense] activated; tier=pro caps=5 的输出。如果配置为了 Pro 却出现了在 Standard 模式下运行的日志，请再三确认资产是否放在 Resources/ 目录下且名为确切的 OZeroLicenseConfig。

服务器激活流程

激活会在应用开启的后台进行。即使服务器响应延迟或临时失败也不会阻断场景加载，并且有缓存即使用之。

引导序列

1. SDK 将在应用启动时自动初始化许可证的运行时。
2. Standard 与 Plus 将在无运行时服务器调用的状态下继续进行。
3. Pro 将在后台发出轻量的激活请求。
4. 一旦成功激活，遥测、签名时间以及认证（attestation）等 Pro 服务器功能将变为可用。
5. 发生激活失败、过期或超时等情况，它也会以不提示给玩家的形式继续在 Standard 模式下运行。

网络传输数据

激活请求是一个短小的 JSON POST。必须字段是 licenseKey、deviceId、sdkVersion 以及 platform。appIdentifier、companyName、productName、webglOrigin 会在 Unity 端给出非空值时加入。设备 ID 数据来源可借助 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>"
}

服务器以 JSON 格式返回带签名的令牌、确定的层级等级、可使用的权限列表以及过期时间。SDK 会先用提供的公钥来校验响应的签名，而后才会去激活 Pro 功能。

无法使用服务器功能时

服务器维护、网络超时、许可证的过期/暂停/废除或 Bundle ID 不符等问题不会被草率地认定为黑客攻击。在此类情况下，它将停用仅适用于 Pro 的功能而继续常规的防御功能。相对的，明显遭受如版本失配、被封禁、注入以及调试工具等篡改的场合，将遵循已设定的应对策略行动。

离线操作

OZero 被设计成无论网络条件如何，都能让玩家运行游戏。具体行为受级别的制约：

Standard — 永远支持离线

Standard 只负责本地防御且无需请求激活或遥测。在不连网时可以照常启动，这也就意味着不能享有特供 Pro 的功能。

Pro — TTL 内的离线运行支持

当某设备成功运行第一次 /v1/activate 后，Pro 激活数据就会保留在 PlayerPrefs (借设备绑定的钥匙加密 — 请参阅下方的缓存保障)。在随后的启用中它将在触发联网前读取留存数据，如此玩家即使断网，SDK 也能获取属于何种层级或拥有何等 Pro 功能的状况。

存下的 Pro 信息在其激落时点起算到指定的 tokenTtlSeconds 前会被采信。默认 7 天 (604800)。当持续断网走完了此时限，被保留的情报会被销毁，直到下次重新完成激活并被转作 Standard 水平运作。探测器则照常，而只有遥测和验证签名时间相关步骤将处于闭塞状态。

Pro — 具备签名的离线拦截策略

遭受连接失效仍带普通保护运行和默许于系统中被拉黑封杀的组件是截然不同的。倘使 Pro 获取成功，服务器会颁发以含签约格式返回的现行屏蔽策略供 SDK 存留。

采用建议的 ApplyCachedBlockPolicies 模式，凡是带有合格签名的策略存续期间，开启着飞行模式运行依旧对已被制裁的散列、SDK版本或是产品版本进行有效的阻挠。因为效能受制于附属时效，若需改变门户拦截规则，必须使之在线认证一回。

故障排除

大部分许可事件均被安排由 OZeroSecLog 将讯息打进原生的 Debug.Log 中 (借 OZeroSecurityConfig 定制)。于终端中依 [OZeroLicense] 探寻可洞悉起因，另外利用 [OZeroTelemetry] 查询回报实况。以下为典型情况以及相关应对措施：

项目设置

在调整各个安全模块之前，请先检查影响原生插件、商店构建和平台验证的 Unity Player Settings。

最低构建目标

Android ProGuard / R8 设置

OZero Security 不需要单独的 Java SDK 包。但是，如果您的 Android 部署版本启用了 Minify、ProGuard 或 R8，则必须保留 Unity Java 桥接以及项目中使用的自定义 Android 桥接类。这样才能确保获取包信息、安装来源、APK 签名证书检查和启动资产加载所需的 JNI 调用在混淆后依然稳定运行。

# 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.** { *; }

• 不要重命名、删除或重新打包 libOZeroSecurity.so。将插件保留在 Assets/OZeroSDK/Plugins/Android/arm64-v8a 下。如果您要分发 32 位版本，也请保留 armeabi-v7a。
• 如果您使用 Build Integrity > Check Platform Native 和 Android SHA Keys，请务必在应用 Minify/R8 后，使用最终签名的 APK 或 AAB 进行测试。调试密钥库的指纹与发布密钥库的指纹是不同的。
• 如果只有在开启 Minify 之后，Android 日志中才出现 JNI 查找失败、安装来源检测失败或 APK 签名检查结果为空的情况，请先检查您的自定义桥接的 keep 规则。
• 对于商店分发的构建版本，请基于 IL2CPP、Release 签名、Android Sha Keys 中注册的预期 Android SHA-256 指纹，并在至少一台真机上进行干净运行测试后再做判断。

5 OZeroSecurityConfig 设置

OZeroSecurityConfig ScriptableObject 资产会在包导入时包含。在 Project 窗口中选择它即可查看并调整所有安全模块设置。在运行时通过 OZeroSecurityConfig.Instance 进行访问。

Common Setting

这是全局应用于所有模块的顶级字段。

Global Threat Response

决定确认安全威胁后游戏的响应方式。在测试期间请先检查回调和日志，在实际部署构建中请根据项目的运营策略选择给玩家的提示时间和终止策略。

构建完整性验证器设置

配置构建完整性检查器，以检测被修改的游戏文件、调试器连接以及异常的运行环境。

生成 RSA 签名密钥（构建完整性）

如果启用了 构建完整性 (Build Integrity) 并且开启了 Require Manifest Signature，OZero 会使用基于公钥的签名来验证完整性清单是否未被更改。在制作发布构建之前，必须在 Unity 编辑器中生成密钥对。

清单签名运作方式

在构建时，OZero 会使用 私钥 对程序集清单进行签名，并将生成的签名嵌入到构建中。在运行时，它会使用保存在 OZeroSecurityConfig 中的 公钥 来验证签名。如果签名不匹配 — 即清单或二进制文件已被篡改 — 游戏会将其视为篡改并根据响应设置进行处理。

生成密钥对

1. 在 Unity 编辑器的 Project 窗口中选择 OZeroSecurityConfig。
2. 在检查器 (Inspector) 中展开 Build Integrity 选项卡。
3. 勾选 Require Manifest Signature 复选框。
4. 点击 Generate Key Pair 按钮。
5. OZero 将生成签名密钥对。公钥 存储在 OZeroSecurityConfig 中，私钥 则保存在以下路径：
   [ProjectRoot]/OZeroSigningKeys/manifest_private_key.pem
6. 将显示指示私钥位置的确认对话框。点击 OK 关闭它。

⚠ 重要提示 — 私钥安全

• 私钥文件存储在 Assets/ 文件夹 外部，以防止 Unity 将其打包进构建中。切勿将其移入 Assets/ 中。
• 请立即将 OZeroSigningKeys/ 添加到 .gitignore 中。将私钥提交到版本控制中是严重的安全隐患。
• 请将私钥备份到安全的离线位置（如加密 USB 驱动器、密码管理器等）。任何拥有此文件的人都可以伪造有效的清单。
• 如果您丢失了私钥，必须重新生成一个新的密钥对。新公钥将自动包含在下一次构建中。以前分发的所有构建都会因为新公钥而导致清单验证失败，因此您必须部署更新。

自定义私钥路径（CI/CD 和团队环境）

您可以在检查器的 Manifest Signing — Editor Only 下的 Manifest Signing Private Key Path 字段中指定私钥的替代位置。这在以下两种情况下很有用：

• CI/CD 管道 — 将私钥保存为 CI Secret，并在构建时注入路径，这样构建机器就不需要将密钥永久保存在磁盘上。
• 团队环境 — 将密钥保存到共享的安全服务器或机密管理器中，并将该字段指定为挂载路径。只需确保运行发布构建的团队成员具有访问权限即可。

验证现有密钥对

要验证磁盘上的私钥与存储在 OZeroSecurityConfig 中的公钥是否匹配，请点击 Validate Key Pair 按钮。OZero 会用私钥对一个小测试载荷签名，然后用公钥进行验证。如果匹配，将显示成功消息；如果不匹配，您需要生成一对新密钥。

何时应重新生成密钥对

• 当私钥丢失或泄露时。
• Validate Key Pair 报告不匹配（密钥未同步）时。
• 作为既定安全策略的一部分，有意轮换密钥时。

重新生成后，新的公钥将自动包含在下一次构建中。此前分发的构建使用新公钥将导致清单验证失败，因此必须部署更新。

双指纹无中断密钥轮换

点击 Generate Key Pair 按钮后，公钥不仅会保存在 OZeroSecurityConfig 中，同时识别相同密钥的 fingerprint 也会记录在 OZeroManifestTrustAnchor.cs 中。运行时将先验证这两个值是否匹配，然后再验证清单的签名。如果二者不匹配，它将不再信任该清单。

当前密钥与旧密钥

在 OZeroManifestTrustAnchor.cs 中，您可以记录当前使用的密钥 fingerprint，以及仅在密钥轮换期间临时允许的旧密钥 fingerprint。平时只使用当前密钥，仅在更换新密钥时才会暂时填入旧密钥槽。通过这种方式，您可以减少在部署新版本期间现有构建用户突然验证失败的情况。

密钥轮换步骤

1. 备份当前指纹。 打开 Assets/OZeroSDK/Scripts/Security/BuildIntegirity/OZeroManifestTrustAnchor.cs，复制 ExpectedPublicKeyFingerprintHex 的值。
2. 注册到旧密钥槽。 在同一文件中，将第 1 步复制的值粘贴到 PreviousPublicKeyFingerprintHex 中并保存。
3. 生成新密钥对。 在 OZeroSecurityConfig 检查器中点击 Generate Key Pair，在弹出的确认窗口中继续操作。新公钥与新指纹将被自动更新。
4. 部署新版本构建。 新的清单将使用新的私钥进行签名。
5. 预留更新过渡期。 在新旧版本共存期间，需同时允许使用旧密钥。对于在线游戏，通常设定在 1 至 4 周左右。
6. 清空旧密钥槽。 当旧版本的使用量足够低后，将代码改回 PreviousPublicKeyFingerprintHex = ""，再次发布后轮换即告完成。

为何需要旧密钥槽

在实时在线服务中，并非所有用户都会在同一时间迁移到新版本。通过暂时保留旧密钥槽，可以减少新旧构建共存期间引发的清单验证失败。经过充分的过渡期后，再清空旧密钥槽即可。

故障排除

大部分与密钥相关的错误，均因私钥、OZeroSecurityConfig 中的公钥以及 OZeroManifestTrustAnchor 中的 fingerprint 三者不匹配所致。请按顺序检查以下项目。

症状 1 — 部署构建在运行后立即退出

ExpectedPublicKeyFingerprintHex 可能为空。解决：在 Unity 编辑器中运行一次 Generate Key Pair，然后进行 Clean Build。若值已填写但仍失败，可能是因为以前构建的产物残留，请清空构建文件夹后重新构建。

症状 2 — 构建刚开始前就提示 "no manifest signing public key is configured" 并中断

当 OZeroSecurityConfig.Integrity.ManifestSigningPublicKey 为空时触发。解决：在检查器中打开 OZeroSecurityConfig，在 Build Integrity 选项卡中点击 Generate Key Pair，再重新构建。

症状 3 — 运行时日志："Manifest signing public key does NOT match the pinned trust anchor fingerprint — APK appears to have been repacked with attacker-controlled keys"

OZeroSecurityConfig 的公钥与代码中记录的 fingerprint 不匹配。解决：在 Unity 编辑器中运行 Tools → OZero → Validate Manifest Signing Keys。如果工具报告不匹配，请使用 Generate Key Pair 重新签发密钥对后再重新构建。如果该提示出现在分发版中，则还应检查 APK 或可执行文件是否被重新打包过。

症状 4 — 轮换后，老构建版本的用户遭遇清单验证失败

极有可能是因为在部署新密钥之前，未将旧 fingerprint 填入 PreviousPublicKeyFingerprintHex 中。解决：发布一个将旧指纹放入 Previous 槽的热修复版本，并在经过充分过渡期后再将其清空。

症状 5 — 本地构建成功，但 CI 构建时提示 "private key not found" 或使用错误的密钥签名

当 CI 机器上缺失 OZeroSigningKeys/manifest_private_key.pem 时发生。解决：将私钥保存在 CI Secret 中，并在 Unity 构建前恢复至相同路径；或者在 OZeroSecurityConfig 的 Manifest Signing Private Key Path 中指定 CI 可访问的安全路径。所有发版机器必须使用相同的私钥。

安装来源设置

限制游戏仅在通过已批准的商店或途径安装时才能运行。这有助于防止侧载或重新打包的 APK。

Steam 防盗版配置

对在 Steam 发售的 PC 端查明 Steam 调用通道、App ID、权限情况、发布档设定。Standard 是局端核实，要想通过 Steam 取得牢固权证唯有依赖 Pro 级别之内的 Steam Attestation 来供给。

设备绑定设置

使用硬件指纹将游戏账号与首次运行的设备绑定。检测账号向其他硬件的转移。

商用运营目的

设备绑定作为 Pro 的运营层最为有用。通过将许可证与服务器记录的硬件指纹关联，可以隔离风险设备，增加随意共享许可证的代价，并在不阻断整个许可证的前提下支持合法的设备更换。

Reset Token 客户支持流程

1. 按照正常的客服流程确认玩家账号及重置原因。
2. 进入 Customer Portal → Device Binding，找到目标设备并发放 Reset Token。
3. 令牌应仅通过已认证的客户支持渠道发送。切勿将其存放在长期保留的公开聊天或截图中。
4. 游戏或客服 UI 需将令牌传递给 OZeroDeviceBindingDetector.Instance?.ClearStoredFingerprint(token.Trim())。
5. SDK 消耗令牌后，重启应用或重新进入保护初始化流程，即可重新注册当前的硬件指纹。

速度黑客检测器设置

通过将 Unity 的 Time.realtimeSinceStartup 与原生平台计时器，甚至可选的受信任 Web 时间源进行对比，以检测时间缩放操控 (速度黑客)。

防止长时间加载时 Watchdog 意外终止应用

OZero 的原生 Watchdog 会通过定期 heartbeat 确认 Unity 主线程是否仍在正常运行。在发布构建中，非 Android 平台大约使用 6 秒 heartbeat deadline，Android 在启动宽限后大约使用 10 秒 deadline。如果在该时间内没有收到 heartbeat，应用可能会被判定为卡死，并按配置的响应策略终止。

大型场景加载、同步资源解压、shader warmup 或 Addressables 准备等正当工作，也可能因为主线程被有意阻塞数秒而触发这种情况。

请使用 OZeroWatchdog.BeginLoadingGrace(maxGraceMs) 包住这类可信加载边界。加载开始时 grace 开始，scope 被 dispose 或调用 End() 时会立即结束，因此不需要提前知道准确的加载时长。

using OZeroSDK.Security;
using UnityEngine.SceneManagement;

public void LoadLargeScene()
{
    using (OZeroWatchdog.BeginLoadingGrace(60000))
    {
        SceneManager.LoadScene("Battle", LoadSceneMode.Single);
        // Grace ends as soon as the using scope exits.
    }
}

public void WarmUpLargeAssets()
{
    OZeroWatchdog.RunWithLoadingGrace(() =>
    {
        BuildLargeRuntimeCache();
    }, 60000);
}

物理黑客检测器

注入检测器设置

检测程序集注入、DLL 劫持、IL2CPP 修补等未经授权的代码注入。

PlayerPrefs 加密

要保护存储在 Unity PlayerPrefs 中的数据（设置、用户偏好等），请将 PlayerPrefs 替换为 OZeroSafePlayerPrefs。API 完全相同。

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", "");

存档文件加密

要加密存档文件，请使用 OZeroSV_File 代替 File.ReadAllText / File.WriteAllText。文件在写入时自动加密，在读取时自动解密。加载时还会检查是否被篡改。

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 游戏内变量保护（Secure Types）

Secure Types 会将常规 C# 变量类型替换为加密类型。因为值存储在 Native C++ 堆中，诸如 Cheat Engine 的工具即使扫描内存也无法找到。只需更改类型名称，其余代码即可照常运行。

示例代码

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using OZeroSDK.Security;

public class PlayerStats : MonoBehaviour
{
    [SerializeField] OZeroSV_Int Gold = 5000;
    [SerializeField] OZeroSV_Float Speed = 3.5f;
    [SerializeField] OZeroSV_Int HP = 1000;
}

支持类型

7 安全事件处理（可选）

默认情况下，当 OZero 检测到威胁时，它会按照配置的响应策略来终止应用或只留存日志。如果您需要直接显示警告屏幕、发送您自己的服务器日志或在退出之前执行保存操作，则可以注册回调。该回调将通过 OZeroSecurityEvent 提供修改类型、中止代码、消息键、详细消息以及是否即将退出等信息。

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

OZeroSecurityEvent、ModulationType 以及 OZeroAbortCode 的完整列表已记录在 API 参考中。

下一步

现在 OZero 的核心防线已经在为您保驾护航了。翻查文档，全面探究每个接口，类、或控制选项的真谛。