API 参考

OZeroSecurityManager OZeroSDK.Security

管理所有活动安全模块的中央单例。即使通过 DontDestroyOnLoad 切换场景，它也会被保留。使用静态 Instance 属性访问它。 OZeroBootstrapper 由 [RuntimeInitializeOnLoadMethod] 在运行时启动时自动创建 - 不要自己实例化它。

特性

方法

在用户链中注册第三方回调。内置的默认处理程序在单独的链中运行，因此当用户回调被释放时它不会被禁用。回调接收OZeroSecurityEvent，其中包含模块类型、公共Abort Code、消息密钥、安全诊断消息以及是否根据当前策略终止应用程序。

删除先前注册的用户回调。请务必从 OnDisable 或 OnDestroy 调用它，以避免内存泄漏。

代表

这是 RegisterUserCallback 使用的回调签名。在决定是否处理您自己的 UI、日志和存储时，请阅读 evt.Type、evt.AbortCodeHex、evt.MessageKey、evt.Message 和 evt.WillAbort。

例子

using OZeroSDK.Security;
using UnityEngine;

public class MySecurityListener : MonoBehaviour
{
    void OnEnable()
        => OZeroSecurityManager.Instance.RegisterUserCallback(OnThreat);

    void OnDisable()
        => OZeroSecurityManager.Instance.UnregisterUserCallback(OnThreat);

    void OnThreat(OZeroSecurityEvent evt)
        => Debug.Log(
            $"Threat={evt.Type}, Code={evt.AbortCodeHex}, Message={evt.Message}");
}

OZeroSecurityEvent class

客户披露的违规事件负载已发送至 RegisterUserCallback。我们只公开可靠且安全的诊断信息，而不是内部检测详细信息。

ModulationType enum

确定哪个安全模块发出了警报。传递给 OZeroSecurityEvent.Type。

OZeroBootstrapper OZeroSDK.Security

这是一个自动引导入口点，不需要额外的接线。您不需要直接调用此类。将 SDK 连接到您的 Unity 启动流程，加载经过验证的安全设置，并在游戏开始前自动准备活动探测器。本机运行时保护（如果可用）也会在此过程中初始化。

OZeroSecurityConfigRuntime OZeroSDK.Security

具有受保护的构建时安全设置的运行时加载程序。验证打包的设置，准备内存中 OZeroSecurityConfig 快照，并在验证失败时应用已建立的威胁响应策略。

特性

方法

幂等加载器——可以安全地重复调用。包配置在第一次访问时验证并加载，后续调用重用相同的快照。故障处理遵循全球威胁响应策略。

OZero Secure Variables OZeroSDK.Security

它是基本类型的加密替代品。值仅在 Native C++ 堆上存储和加密。每个帧都会应用一个额外的 48 字节 XOR 掩码，因此内存扫描器只能看到噪声。支持所有算术运算符和隐式转换 - 只需更改类型名称即可。

支撑类型

支持的运营商

数字类型（Int、Int64、UInt、UInt64、Short、UShort、Byte、Float、Double、Decimal）用于算术（+ - * / %）、比较（== != <） >) 支持 <= >=)、复合赋值 (+= -= *= /=)、递增/递减 (++ --) 运算符以及基本类型的隐式转换。 Vector2·Vector3支持算术和等式运算符，而Bool仅支持等式运算符。字符串支持 ==、!=、+。 Buffer可以通过索引操作符直接访问字节数组。

OZeroSafePlayerPrefs OZeroSDK.Security

Unity PlayerPrefs 的加密替代品。密钥名称通过消息认证进行哈希处理，值使用密钥派生功能Device Binding密钥进行加密（重复 100,000 次）。即使直接打开设备注册表（Windows）或设置plist（iOS）也无法读取保存的数据。

方法

所有方法在功能上等同于 PlayerPrefs。无需迁移步骤 - 只需替换类名称。

OZeroSV_File OZeroSDK.Security

使用内置完整性验证来加密和解密文件。关键是应用程序级别（无Device Binding），因此它与 Steam 云保存兼容。首先在读取时执行完整性验证，被篡改的文件会引发异常，而不是自动返回损坏的数据。

方法

加密contents并将结果（标头+密文+认证标签）写入path。该目录必须已经存在。

读取 path 中的文件，验证其完整性，并返回解密的字符串。如果文件已被篡改，则引发 InvalidDataException。

加密原始字节数组并将其写入 path。

读取并解密 WriteAllBytes 写入的文件。返回前验证标签的完整性。

示例代码

using OZeroSDK.Security;

string path = Application.persistentDataPath + "/save.json";
string json = JsonUtility.ToJson(saveData);

// Write (encrypts automatically)
OZeroSV_File.WriteAllText(path, json);

// Read (decrypts + integrity check)
try
{
    string loaded = OZeroSV_File.ReadAllText(path);
    saveData = JsonUtility.FromJson<SaveData>(loaded);
}
catch (System.IO.InvalidDataException)
{
    // File was tampered — handle accordingly
    Debug.LogError("Save file integrity check failed.");
}

OZeroBuildIntegrityValidator OZeroSDK.Security

运行时验证程序可处理构建篡改、调试器/计时异常、平台本机完整性检查、可选的 Pro Server 证明和 OZero 托管验证。当 OZeroSecurityConfig 中启用构建完整性时，由 OZeroBootstrapper 自动创建。

检查项目

公共财产

事件和方法

当所有启用的本地检查通过时调用。

当启用的本地检查或 Pro 证明拒绝构建时调用。

当 Pro 服务器证明成功并且在 AttestationToken 中收到有效令牌时调用。

开始手动验证。对于一般项目，建议使用仪表板的启动/定期验证设置。

OZeroSpeedHackDetector OZeroSDK.Security

使用五个独立的检测信号检测速度黑客和时间操纵。仅在信号相互确认时才报告威胁，从而减少误报。

检测信号

检测通过带有 ModulationType.SpeedHack 或 ModulationType.TimeHack 的 OZeroSecurityManager 回调进行。设置在 OZeroSecurityConfig 中。

OZeroInjectionDetector OZeroSDK.Security

观察异常运行时模块、挂钩、调试器和信任模块策略信号。定期扫描在适用的情况下使用抖动调度来减少可预测的扫描时序。

检测目标

检测通过带有 ModulationType.Injection 的 OZeroSecurityManager 回调进行。

OZeroSecurityConfig ScriptableObject

存储全局安全设置的 ScriptableObject 资产。当您在编辑器中编写时，构建管道会将其打包到受保护的运行时设置中以供播放器构建。实际应用程序设置通过 OZeroSecurityConfig.Instance 进行访问。

场地

这些字段分组为嵌套配置类（Response、Integrity、InstallSource、DeviceBinding、SpeedHack、Injection），并通过 OZeroSecurityConfig.Instance 中的同名属性进行访问。下面列出了经常调整的字段，请参阅资产的检查器工具提示以了解完整的详细信息。

OZeroLicenseConfig OZeroSDK.Security.License

ScriptableObject 从 Resources/OZeroLicenseConfig 加载。选择您的许可证层并设置 Plus/Pro 密钥和可选的 Pro 运行时功能。如果丢失或为空，它将作为标准/无服务器运行。

场地

特性

从资源加载运行时设置。将 null 视为标准/无服务器。

适用于 Standard、Plus 或空白许可证密钥。仅当需要 Pro 激活时才为 False。

在 Plus 和 Pro 上正确。用于构建预验证和本机变体绑定。

OZeroLicenseRuntime OZeroSDK.Security.License

读取当前许可证状态的运行时外观。它会在应用程序启动时自动初始化，因此大多数项目只需要读取状态或调用 HasCapability 即可。

特性

方法

这是一种幂等启动方法。通常由 SDK 自动调用，自定义引导可以在读取许可证状态之前等待。

返回活动权利是否具有以下功能：telemetry、signed_time、attestation_v1。这在标准/无服务器中是错误的。

许可证服务器运行时调用

Pro 功能使用 /v1 下的 HTTPS JSON 调用。大多数调用都是由 SDK 自动进行的。拥有自己的游戏服务器的团队可以直接使用 /v1/validate 验证 OZA 代币，并使用 consumeToken=true 防止 tokenId 重复用于高价值操作。没有服务器的团队可以通过托管验证设置使用 OZero 委托裁决。

OZeroAbortCode 和事件消息

当确认发生安全违规时，SDK 会生成 OZeroSecurityEvent。活动包括ModulationType、稳定公共OZeroAbortCode、MessageKey、安全英语Message 和WillAbort。

Abort Code和消息表

创建日志或多语言 UI 时，请使用 OZeroAbortCode 和 MessageKey 作为参考值。 Message 被组织成一个安全的表达式，以便开发人员可以了解情况，因此可以按原样显示在开发人员屏幕或 QA 日志上。

处理运行时的安全事件

如果您需要刷新分析队列、向开发人员显示警告或在 SDK 中止之前正常保存，请使用 OZeroSecurityManager.RegisterUserCallback 注册处理程序。您可以使用 evt.WillAbort 检查当前响应策略是否会终止应用程序。

using OZeroSDK.Security;

void OnEnable()
{
    OZeroSecurityManager.Instance.RegisterUserCallback(OnHack);
}

void OnHack(OZeroSecurityEvent evt)
{
    Debug.LogWarning(
        $"OZero: {evt.Type} {evt.AbortCodeHex} {evt.MessageKey} - {evt.Message}");

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

    Analytics.FlushSync();
}

Injection Detector API OZeroSDK.Security

哈希+签名者指纹白名单的编程表面。运行时使用OZeroDispatch，随游戏分发的信任项设置为OZeroLicenseConfig。

DTO — OZeroInjectionWhitelistEntry

[Serializable]
public class OZeroInjectionWhitelistEntry
{
    // SHA-256 of the matched module file. Lowercase 64-char hex. Required.
    public string HashHex { get; set; }

    // SHA-256 of the module's signing certificate. Lowercase 64-char hex.
    // Empty ("") means "match by hash only" (only mode for Android .so / Linux ELF).
    public string SignerHex { get; set; }

    // Module file format hint — "pe" | "macho" | "so". Defaults to "so".
    public string Type { get; set; }

    // Optional human-readable note (UI / audit only — never sent to native).
    public string Comment { get; set; }
}

这是 Unity 在需要播种本地信任模块条目时使用的 DTO。专业客户通常在门户中管理相同的策略。

运行时 API — OZeroDispatch

// Returns true when trusted-module policy support is available.
public static bool HasInjectionV3 { get; }

// Replace trusted module entries atomically. Pass null/empty to clear.
// Returns false when the runtime support is unavailable.
public static bool RegisterInjectionWhitelistHash(OZeroInjectionWhitelistEntry[] entries);

// Trusted-module aware scan. Returns true when a relevant runtime signal is observed.
// Output fields are diagnostic context for your review and may be empty.
public static bool DetectAssemblyInjectionV3(
    out bool   silencedByWhitelist,
    out string hashHex,
    out string signerHex,
    out string matchedModulePath);

所有三个方法都是静态助手。将其视为可选功能表面，首先检查可用性，并将本地信任条目保持在最低限度。

配置 — OZeroLicenseConfig

// Inspector array of OZeroInjectionWhitelistEntry — preferred surface.
public OZeroInjectionWhitelistEntry[] InjectionWhitelistEntries { get; }

public string[] InjectionWhitelistKeywords { get; }

InjectionWhitelistEntries 是信任模块策略的本地种子。仅在您自己部署或明确信任的模块中使用。