OZero Security
APIリファレンス

APIリファレンス

OZeroSecurity SDKのすべての公開クラスとメソッドの完全なリファレンスです。特に記載がない限り、すべてのクラスはOZeroSDK.Security名前空間に属します。

OZeroSecurityManager OZeroSDK.Security

アクティブなセキュリティモジュールとセキュリティイベントを管理するグローバルマネージャーです。シーン遷移時も維持され、Instanceプロパティからアクセスできます。SDKがアプリ起動時に自動生成するため、直接インスタンス化する必要はありません。

プロパティ

名前 説明
Instance OZeroSecurityManager 静的シングルトンアクセサ。アクティブなインスタンスを返します。

メソッド

void RegisterUserCallback(DelegateSecurityViolation callback)

プロジェクト側でセキュリティイベントを受け取りたいときにコールバックを登録します。OZero の基本対応は別の流れで実行されるため、このコールバックを登録または解除しても SDK の保護動作は無効になりません。コールバックには、検出領域、公開 abort code、メッセージキー、診断メッセージ、アプリ終了予定の有無を含む OZeroSecurityEvent が渡されます。

void UnregisterUserCallback(DelegateSecurityViolation callback)

以前に登録したユーザーコールバックを削除します。メモリリーク防止のため、OnDisableまたはOnDestroyで必ず呼び出してください。

void RegisterUserPolicyActionCallback(Action<OZeroPolicyActionEvent> callback)

Pro device policy heartbeat を通じてサーバーから送られる policy action を受け取るコールバックを登録します。ポータルの Callback 対応ポリシーをゲームコードへ接続するための API で、ローカルのセキュリティ検知コールバックとは別に動作します。

void UnregisterUserPolicyActionCallback(Action<OZeroPolicyActionEvent> callback)

以前に登録した policy action コールバックを削除します。シーンオブジェクトで使う場合は OnEnable で登録し、OnDisable で解除してください。

void RegisterUserActivationStateCallback(Action<OZeroUserActivationStateEvent> callback)

ユーザー向けの Activation / DRM 状態変化を受け取るコールバックを登録します。OZero-managed Steam DRM と既定の Managed Verification UI を使う場合、SDK がオンライン必須、再試行、timeout、ブロック状態を表示します。カスタム UI、telemetry、ゲーム固有の session gate が必要な場合だけ登録してください。

void UnregisterUserActivationStateCallback(Action<OZeroUserActivationStateEvent> callback)

以前に登録した Activation 状態コールバックを削除します。シーンオブジェクトで使う場合は OnEnable で登録し、OnDisable で解除してください。

void RegisterUserManagedVerificationStateCallback(Action<OZeroUserManagedVerificationStateEvent> callback)

Registers a callback for the shared OZero Managed Verification state used by Pro Build Integrity and Steam DRM. The default SDK UI handles these states automatically when enabled; use this callback only for custom UI, custom telemetry, or game-specific session gates.

void UnregisterUserManagedVerificationStateCallback(Action<OZeroUserManagedVerificationStateEvent> callback)

Removes a previously registered managed verification state callback. Register in OnEnable and unregister in OnDisable when using a scene object.

void RegisterUserManagedVerificationTextProvider(IOZeroUserManagedVerificationTextProvider provider)

Replaces individual built-in verification UI strings at runtime. Use JSON files under Assets/OZeroSDK/Resources/OZeroLocalization for normal localization, and use this provider only when text must be supplied dynamically.

void UnregisterUserManagedVerificationTextProvider(IOZeroUserManagedVerificationTextProvider provider)

Removes a previously registered managed verification text provider.

bool RequestBuildAttestationRetry()

Retries SDK-managed Build Integrity attestation after an online-required or retry-timeout state. The default Managed Verification UI calls this automatically. If your own game server validates OZA tokens, retry your own login or session-refresh request instead.

bool RequestSteamActivationRetry()

OZero サーバーが管理する Steam Activation / DRM 検証を再試行します。既定の Managed Verification UI は必要な retry フローを SDK 内で呼び出します。ゲームコードから呼ぶのは既定 UI を意図的に置き換えるカスタム UI の場合だけです。自社ゲームサーバーが Steam 検証を行う構成では、このメソッドではなく自社のログインまたはセッション要求を再送してください。

デリゲート

delegate void DelegateSecurityViolation(OZeroSecurityEvent evt)

RegisterUserCallback で使うコールバックシグネチャです。警告 UI、独自サーバーログ、短い保存処理が必要なときは evt.Typeevt.AbortCodeHexevt.MessageKeyevt.Messageevt.WillAbort を確認してください。evt.WillAbort が true の場合、アプリ終了が予定されているため、時間のかかる処理は避けてください。

サンプルコード

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 に渡される顧客公開用の違反イベントです。内部の検知詳細情報の代わりに、安定して安全な診断情報のみを公開します。

名前 説明
TypeModulationType違反を発生させたセキュリティモジュールです。
AbortCodeOZeroAbortCode安定した公開中絶コードカテゴリです。
AbortCodeValueintサーバーログに使用するのに適した数字のコード値です。
AbortCodeHexstring0x0C のような16進数の文字列です。
MessageKeystringローカライズや analytics のグループ化に使用できる安定した英文メッセージキーです。
Messagestring顧客に公開可能な安全な英文診断メッセージです。
WillAbortboolコールバック返却後、または猶予時間が終わった後に現在の対応ポリシーがアプリを終了する予定であれば true です。

OZeroPolicyActionEvent class

RegisterUserPolicyActionCallback に渡されるサーバーポリシーのコールバックペイロードです。顧客ポータルのポリシーシステムから発行され、Pro device policy heartbeat により Unity メインスレッドで配信されます。

名前 説明
Modulestringvariantinjectionphysics などのポリシーモジュールです。
ActionIdstring配信を識別する一意の ID です。SDK はこの値で重複配信を防ぎ、サーバーへ ack を送ります。
PolicyIdstring利用可能な場合の顧客ポータル policy ID です。
Reasonstringポリシーに設定された理由、または一致した証拠から生成された理由です。
Scoreintポリシーが一致した時点のリスクスコアです。
EventCountintポリシー一致に反映されたイベント数です。
WindowMinutesintポリシー評価ウィンドウ(分)です。
IssuedAtUnixMslongサーバーが action を発行した UTC epoch milliseconds です。
ExpiresAtUnixMslongack されなかった action が期限切れになる UTC epoch milliseconds です。

ポリシーコールバック例

Customer Portal のセキュリティポリシーを Callback に設定した場合に使用します。SDK は policy action をゲームへ配信し、ゲーム側で通知、制限、画面遷移を決定します。

using OZeroSDK.Security;
using UnityEngine;

public sealed class OZeroPolicyListener : MonoBehaviour
{
    private void OnEnable()
        => OZeroSecurityManager.Instance.RegisterUserPolicyActionCallback(OnPolicyAction);

    private void OnDisable()
        => OZeroSecurityManager.Instance.UnregisterUserPolicyActionCallback(OnPolicyAction);

    private void OnPolicyAction(OZeroPolicyActionEvent evt)
    {
        Debug.LogWarning($"Policy={evt.PolicyId}, Module={evt.Module}, Score={evt.Score}, Reason={evt.Reason}");

        if (evt.Score >= 80)
        {
            ShowSecurityNotice(evt.Reason);
            DisableRankedMatchmaking();
        }
    }
}

OZeroUserActivationStateEvent class

RegisterUserActivationStateCallback に渡されるユーザー向け Activation / DRM 状態ペイロードです。Steam Activation / DRM は、キャッシュ済みのオフライン実行がまだ許可されるか、オンライン再検証が必要かをこのイベントでゲームへ通知します。

名前 説明
Providerstringsteam などの Activation provider です。
Statestringvalidrevalidatedonline_requiredoutage_fail_openrejected などの安定した状態値です。
Reasonstringsteam_activation_revalidate_unavailablesteam_activation_cache_expired などの reason code です。
Actionstring利用可能な場合、この状態に関連付けられたポータル policy action 値です。
OfflineAllowedbool現在のキャッシュトークンまたは猶予ポリシーでオフライン実行が許可される場合は true です。
OnlineRequiredbool保護セッションを許可する前に、ユーザーへネットワーク接続と再検証を求める必要がある場合は true です。
ExpiresAtUnixMslongActivation token が期限切れになる UTC epoch milliseconds です。
GraceUntilUnixMslongオフライン猶予時間が終了する UTC epoch milliseconds です。
OutageFailOpenUntilUnixMslong一時的なサーバー障害 fail-open を許可する UTC epoch milliseconds です。

Activation 状態コールバックの使用基準

OZero-managed Steam DRM と既定の Managed Verification UI を使う場合、activation callback コードは不要です。SDK がプレイヤーにオンライン必須、再試行、timeout、ブロック状態を表示します。このコールバックは、既定 UI を置き換える場合、独自 session gate を追加する場合、または顧客ゲームサーバー検証フローを運用する場合だけ登録してください。Steam Web API Key や OZero Server API Key をクライアントに入れないでください。

OZeroUserManagedVerificationStateEvent class

RegisterUserManagedVerificationStateCallback に渡されるユーザー向け managed verification ペイロードです。Build Integrity と Steam DRM の両方がこのイベントを使いますが、既定の Managed Verification UI はこれを自動的に処理します。ゲームコードで扱うのは、カスタム UI、追加 telemetry、ゲーム固有の session gate が必要な場合だけです。

名前 説明
ProviderOZeroManagedVerificationProviderSource module: BuildIntegrity or SteamDrm.
StateOZeroUserManagedVerificationStateCurrent state such as Checking, Allowed, Warning, OnlineRequired, RetryTimedOut, Blocked, or StandardFallback.
ReasonstringStable reason code suitable for custom UI text, analytics, or customer support logs.
VerdictstringServer verdict when available, such as allow, warn, block, or fallback.
CanRetryboolTrue when a Retry action is meaningful for the current provider and state.
TimestampUnixMslongUTC epoch milliseconds when the state was raised.

Managed verification コールバックの使用基準

managedVerificationUiPolicy が OZero 内蔵ダイアログを使う場合、SDK は Build Integrity と Steam DRM の managed-verification UI、再試行、timeout 状態をすでに処理します。RegisterUserManagedVerificationStateCallbackCustom UI / Callback Only、追加 telemetry、ゲーム固有の session gate の場合だけ登録してください。カスタム UI モードでは Provider に合う retry メソッドを呼び、自社ゲームサーバーモードでは SDK retry ではなく自社のログインまたはセッション要求を再送してください。

OZeroManagedVerificationUiPolicy enum

Build Integrity と Steam DRM で発生する managed verification 状態を SDK がプレイヤーへどのように表示するかを決めます。2 つの Built-In policy には TextMeshPro、TMP Essential Resources、optional OZero Built-In TMP Dialog package が必要です。これらがない状態で Built-In policy を選択すると build preflight が player build を停止します。Window > OZero Security > Check Setup で該当エラーの Import Package を押して修正してください。

説明
CustomCallbackOnlySDK は RegisterUserManagedVerificationStateCallback の状態だけを通知します。ゲーム側で独自 UI、再試行ボタン、timeout 処理、session gate をすべて実装する場合に使用します。
BuiltInBlockingDialogOZero の内蔵ブロッキングダイアログを使用します。オンライン再検証が必要な間、保護セッションを停止またはブロックすべきリリースビルドの推奨既定値です。
BuiltInNonBlockingDialogOZero の内蔵非ブロッキング通知を使用します。再試行や警告状態を案内している間もゲーム進行を安全に継続できる場合だけ使用してください。

OZeroManagedVerificationTimeoutAction enum

オンライン必須または再試行状態が設定された制限時間内に解決しない場合、内蔵 managed verification UI が行う動作を決めます。

説明
KeepDialogtimeout 後もダイアログを表示し続けます。プレイヤーに手動再試行を続けさせる必要があるフローでのみ選択してください。
BlockSessiontimeout 後に保護セッションをブロックします。オンライン検証は必須だがアプリは開いたままにする場合の推奨既定値です。
AbortApplicationtimeout 後にアプリケーションを終了します。未解決の検証失敗で即時終了するリリースポリシーの場合だけ使用してください。
InvokeCallbackOnly内蔵のブロックまたは終了動作を行わず、callback のみ呼び出します。完全なカスタム session control が必要な場合に使用します。

ModulationType enum

どのセキュリティモジュールが警告を発生させたかを示します。OZeroSecurityEvent.Type として渡されます。

説明
MemoryModulation Secure Type変数が不審な方法でアクセスされた
SpeedHack スピードハックまたは時間操作を検知
TimeHack システムクロックの異常を検知(逆行、NTP不一致)
Injection メモリインジェクションツール(Fridaなど)または不正DLLを検知
PhysicsHack 不可能な位置変化を検知 (OZeroPhysicsHackDetector により発生 — プレイヤーオブジェクトに直接コンポーネントをアタッチして初期化する必要があります)
DeviceBindingModulation セーブデータがバインドされたデバイスと異なるデバイスで読み込まれた
InstallSource アプリが公認ストア以外からインストールされた
BuildIntegrity アセンブリハッシュ不一致、デバッガー接続、またはプラットフォームチェック失敗
EnvironmentModulation エミュレーターまたは非標準ランタイム環境を検知
SteamAntiPiracy Steam の所有権またはチケット検証に失敗した場合に発生します。

OZeroBootstrapper OZeroSDK.Security

SDK初期化を担当する自動起動の起点です。プロジェクトコードから直接呼び出す必要はありません。Unityの起動フローに合わせてセキュリティ設定を読み込み、ゲーム開始前に有効なディテクターを準備します。

公開APIなし — 呼び出し側でこの型をインスタンス化したり継承したり参照したりしないでください。サポートされる連携サーフェスはOZeroSecurityConfigアセットのみです。

OZeroSecurityConfigRuntime OZeroSDK.Security

保護されたビルド設定をプレイヤー実行時に読み込んで検証する構成ローダーです。パッケージ化された設定を検証し、メモリ上のOZeroSecurityConfig実行設定を準備し、検証失敗時は設定された脅威対応ポリシーを適用します。

プロパティ

名前 説明
Current OZeroSecurityConfig プレイヤービルドに含まれる保護設定を読み込んで作成した設定スナップショットです。初回アクセス時にEnsureLoaded()を呼び出します。

メソッド

static void EnsureLoaded()

繰り返し呼び出しても安全なローダーです。最初の呼び出しでパッケージ化された設定を検証・ロードし、以降の呼び出しでは同じ設定スナップショットを再利用します。失敗時の処理は設定された対応ポリシーに従います。

この型は内部ローダーです。サポートされる連携面はOZeroSecurityConfigとUnityエディターウィンドウと考えてください。

OZero Secure Variables OZeroSDK.Security

通常の数値、文字列、ベクター型の代わりに使用できる暗号化タイプです。値は保護されたメモリ領域に保存され、ほとんどの算術演算子と暗黙的な変換をサポートします。既存のコードで型名を変更するだけで適用できます。

対応型一覧

クラス 置き換え対象
OZeroSV_Intint
OZeroSV_Int64long
OZeroSV_UIntuint
OZeroSV_UInt64ulong
OZeroSV_Shortshort
OZeroSV_UShortushort
OZeroSV_Bytebyte
OZeroSV_Floatfloat
OZeroSV_Doubledouble
OZeroSV_Decimaldecimal
OZeroSV_Boolbool
OZeroSV_Stringstring
OZeroSV_Vector2Vector2
OZeroSV_Vector3Vector3
OZeroSV_Bufferbyte[]

対応演算子

数値型(Int、Int64、UInt、UInt64、Short、UShort、Byte、Float、Double、Decimal)はすべての算術(+ - * / %)、比較(== != < > <= >=)、複合代入(+= -= *= /=)、インクリメント/デクリメント(++ --)演算子と、対応する基本型との暗黙的変換をサポートします。Vector2・Vector3は算術および等価演算子をサポートします。Boolは等価演算子のみサポートします。Stringは==!=+をサポートします。Bufferはインデックス演算子を通じてバイト配列に直接アクセスできます。

Secure Types は、サポートされる基本演算での繰り返しのアロケーションを減らすように設計されています。ただし、文字列/バッファ変換、ログ出力、ボクシング、LINQ、ユーザーコードのパターンによっては GC が発生する可能性があるため、毎フレームの大量更新に適用する前にプロファイリングを行ってください。

OZeroSafePlayerPrefs OZeroSDK.Security

UnityのPlayerPrefsと同じように使用できる暗号化ストレージです。キー名と値が保護されているため、WindowsのレジストリやiOSの設定ファイルを直接開いても元の値を読み取るのは困難です。

メソッド

static void SetInt(string key, int value)
static int GetInt(string key, int defaultValue = 0)
static void SetFloat(string key, float value)
static float GetFloat(string key, float defaultValue = 0f)
static void SetString(string key, string value)
static string GetString(string key, string defaultValue = "")
static void SetInt64(string key, long value)
static long GetInt64(string key, long defaultValue = 0L)
static void SetDouble(string key, double value)
static double GetDouble(string key, double defaultValue = 0.0)
static void SetBool(string key, bool value)
static bool GetBool(string key, bool defaultValue = false)
static int IncrementInt(string key, int defaultValue = 0)
static bool HasKey(string key)
static void DeleteKey(string key)
static void DeleteAll()
static void Save()
static void Initialize(string newPassword = "", string newSalt = "") // obsolete compatibility no-op

よく使う PlayerPrefs 形式のメソッドに加えて、Int64DoubleBoolIncrementInt ヘルパーを提供します。既存の plain PlayerPrefs 値は自動移行されないため、今後保護したい key から OZeroSafePlayerPrefs で保存してください。

OZeroSafePlayerPrefsで書き込まれたデータは標準のPlayerPrefsと互換性がありません。両者を切り替えると既存データが読めなくなります。

OZeroSV_File OZeroSDK.Security

内部の暗号化ロジックでファイルの読み書きを保護します。デバイスバインディングキーを使用しないため、Steamクラウドセーブのように複数のデバイスで同じセーブファイルを読み込む必要がある場合でも使用できます。ファイルを意図的に改ざんした場合、読み込み時に整合性チェックが失敗し、InvalidDataException が発生します。

暗号化されたファイルはSDK内部形式で保存されます。ファイル構造や特定位置を直接解析せず、読み書きは必ずOZeroSV_File APIを通して処理してください。

メソッド

static void WriteAllText(string path, string contents)

contentsを暗号化し、pathに保存します。親フォルダは自動作成されないため、必要な場合は保存前にDirectory.CreateDirectoryで作成してください。

static string ReadAllText(string path)

pathのファイルを読み取り、整合性を検証したうえで復号済み文字列を返します。ファイルが改ざんされている場合はInvalidDataExceptionを発生させます。

static void WriteAllBytes(string path, byte[] bytes)

データを暗号化し、pathに安全に保存します。

static byte[] ReadAllBytes(string path)

pathに指定されたファイルを読み込みます。読み込み時にファイル整合性を検証し、改ざんを検知します。

static string DecryptBytesToText(byte[] encryptedData)

ファイルパスではなく、すでにメモリに読み込まれた暗号化バイトバッファを復号します。リモートダウンロードやカスタムストレージから受け取ったデータを ReadAllText に渡せない場合に使用してください。

サンプルコード

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 サーバー attestation を処理する検証器です。Build Integrity が OZeroSecurityConfig で有効な場合、SDK が自動生成します。

検査内容

検査 説明
Assembly / Manifest対応ビルドターゲットで、生成された整合性マニフェストと managed assembly の状態を検証します。
Debugger / Timing接続されたデバッガー、異常なタイミングギャップ、ブレークポイントに近い遅延を検出し、一般的なフォーカス喪失の誤検知は抑制します。
Platform Native有効な場合、Android パッケージ/署名、iOS jailbreak、デスクトップランタイム状態などのプラットフォーム別検査を実行します。
Pro AttestationPro サーバー検証がオンになっている場合、ローカル検査の通過後にサーバーに検証トークンを要求します。自社のゲームサーバーがない場合、OZero サーバーが許可/警告/遮断の結果を一緒に返すこともできます。

公開プロパティ

名前 説明
InstanceOZeroBuildIntegrityValidatorモジュールが作成されている場合の現在の validator インスタンスです。
LastValidationResultbool?直近のローカル検証結果です。初回実行前は null です。
IsValidatingbool検証実行中は true です。
IsIntegrityVerifiedbool最近アクティブになったローカル検査を通過すると true です。
AttestationTokenOZeroBuildAttestationToken直近の Pro attestation トークンです。サーバー attestation が成功または失敗するまでは null であり、トークンには再利用追跡のための固有 ID が含まれます。

イベントとメソッド

UnityEvent OnValidationPassed { get; }

有効なすべてのローカル検査が通過したときに呼び出されます。

UnityEvent OnValidationFailed { get; }

有効なローカル検査または Pro attestation がビルドを拒否したときに呼び出されます。

UnityEvent OnAttestationPassed { get; }

Pro サーバー attestation が成功し、AttestationToken に有効なトークンが入った後に呼び出されます。

void Validate()

手動検証を開始します。通常のプロジェクトでは、ダッシュボードの起動時/定期検証設定を使用する方が良いでしょう。

OZeroBuildAttestationToken

Pro attestation の結果です。AttestToken をゲームサーバーへ渡し、ログイン、PvP、ランキング、財貨処理などのフローに使用する前に IsValid(nowMillis) で有効性を確認してください。

bool IsExpired(long nowMillis)

サーバーが発行した有効期限を過ぎている場合 true を返します。

bool IsValid(long nowMillis)

トークン発行が成功し、まだ期限切れでない場合 true を返します。

OZeroSpeedHackDetector OZeroSDK.Security

5つの独立した検知シグナルを使用してスピードハックと時間操作を検知します。シグナルが互いに確認し合った場合のみ脅威を報告し、誤検知を減らします。

検知シグナル

シグナル 説明
TimeScale ゲームの時間の流れが異常に変化していないか確認
API Clock プラットフォーム時間とネイティブ基準時間を比較し、大きな差を検知
Thread Drift Unityランタイム時間とネイティブ基準時間の流れの差を観察
Time Backward デバイスの時間が異常に巻き戻る状況を検知
NTP 任意 — 信頼できる外部基準時間との比較(ネットワーク必要)

検知はModulationType.SpeedHackまたはModulationType.TimeHackOZeroSecurityManagerコールバックを通じて発生します。OZeroSecurityConfigで設定します。

OZeroWatchdog OZeroSDK.Security

信頼できる長時間ロード処理のための public helper です。リリース時の deadline より長く Unity のメインスレッドを正当にブロックする同期処理の間、native Watchdog heartbeat deadline を限定的に猶予します。

メソッド

OZeroWatchdog.OZeroLoadingGraceScope BeginLoadingGrace(int maxGraceMs = 60000)

制限付きの loading grace scope を開始します。信頼できるロード処理が終わったら、返された scope の End() を呼ぶか dispose してください。ネストされた scope に対応し、最後の scope が終わると通常の Watchdog timing に戻ります。

void OZeroLoadingGraceScope.End()

この loading grace scope を手動で終了します。Dispose() も同じ処理を呼ぶため、using ブロックと明示的な End() は同じように動作します。

void RunWithLoadingGrace(Action work, int maxGraceMs = 60000)

同期ロード処理のための便利な wrapper です。loading grace scope を作成し、work を実行した後、using ブロックで安全に scope を終了します。

using OZeroSDK.Security;
using UnityEngine.SceneManagement;

public void LoadLargeScene()
{
    using (OZeroWatchdog.BeginLoadingGrace(60000))
    {
        SceneManager.LoadScene("Battle", LoadSceneMode.Single);
    }
}
この API は Watchdog deadline だけを猶予します。他の保護モジュールを無効化したり、native heartbeat を public に公開したりするものではありません。信頼できるロード境界にのみ使用し、keep-alive 目的では使わないでください。

OZeroInjectionDetector OZeroSDK.Security

実行中のゲームに疑わしいモジュールが付着していないか、またはフッキングやデバッガーの痕跡がないかを確認します。定期検査は可能な場合、検査タイミングを少しずつ変えて単純な回避試行を難しくします。

検知対象

Runtime module 予期しないランタイムモジュールまたはフッキングが疑われるシグナル
Debugger デバッガーまたは追跡ツールの接続が疑われるシグナル
Memory map 異常なランタイムメモリまたはモジュールの状態シグナル
Illegal DLL プロセスにロードされた許可されていない管理アセンブリシグナル(Windows/Unity Editor)

検知はModulationType.InjectionOZeroSecurityManagerコールバックを通じて発生します。

OZeroSteamAntiPiracy OZeroSDK.Security

Steam Anti-Piracy の検知後の動作を実行中に変更する API です。ほとんどのプロジェクトは Config Dashboard での設定で十分です。ゲーム内に運営者用メニューや QA 用スイッチを直接提供する場合にのみ使用してください。

この API は QA ビルドで一時的に観察モードに変更したり、ゲーム内の運営者メニューから基本設定に戻す用途に適しています。Pro サーバーのポリシーが別途適用されるプロジェクトでは、ポータルのポリシーが優先される可能性があるため、実際の遮断ポリシーはポータルの設定と一緒に確認してください。

OZeroSteamDetectionAction

説明
Offローカルの Steam Anti-Piracy 応答を適用しません。制限された問題分析の状況でのみ使用してください。
Observe診断情報だけを記録し、ゲーム実行は継続して許可します。
CallbackOZeroSecurityManager コールバックを発生させ、ゲームが UI 表示、ログ記録、独自の処理を行えるようにします。このオプションだけではアプリは自動終了せず、実際の終了可否は Global Threat Response 設定とプロジェクトのコールバック処理方法に従います。
Block違反を遮断ポリシーとして扱います。実際のアプリの終了可否は Global Threat Response 設定に従います。

メソッド

static void SetDetectionActionOverride(OZeroSteamDetectionAction action)

実行中の Steam Anti-Piracy の検知後動作を変更します。QA ビルドで一時的に Observe に下げたり、運営者用メニューで特定の動作を選択させる場合に使用します。

static void ClearDetectionActionOverride()

実行中に変更した Steam Anti-Piracy の動作を解除し、Config Dashboard または Pro ポータルに設定された基本動作に戻します。

using OZeroSDK.Security;

// QA session: observe Steam violations without blocking gameplay.
OZeroSteamAntiPiracy.SetDetectionActionOverride(
    OZeroSteamDetectionAction.Observe);

// Restore the dashboard/server policy.
OZeroSteamAntiPiracy.ClearDetectionActionOverride();

最後の検証結果

OZeroSteamAntiPiracyValidator.Instance.GetLastResult()

直近の Steam 検証スナップショットを返します。reported AppID、BuildID、SteamID、サーバー検証状態、soft signal、native score フィールドを含みます。デバッグ UI や QA レポートには使用できますが、ゲームプレイ権限の判断の唯一の基準として使用しないでください。

OZeroInstallSourceValidator OZeroSDK.Security

Android のインストール元検証器です。Install Source が有効な場合、コンポーネントは自動生成されます。顧客コードでは主にサポート UI、診断ログ、ストア別分岐処理のために最後の結果を読みます。

メソッドとイベント

event Action<InstallSourceResult> OnInstallSourceDetected

インストール元の確認が終わったときに呼び出されます。

InstallSourceResult GetLastResult()

直近の検査結果を返します。

InstallSourceResult GetAndroidInstallationSource()

必要に応じて初期化を行い、Android のインストール元結果を返します。

InstallSourceResult

DetectedSource解決されたインストール元です。型は AndroidInstallSource enum です。
RawInstallerPackageAndroid PackageManager が返した元の installer package name です。
IsAuthorizedローカル設定と、有効な場合は Pro サーバーポリシーがこのインストール元を許可しているなら true です。
ServerVerifiedPro 専用です。サーバー検証呼び出しが完了したなら true です。
ServerAuthorizedPro 専用です。ServerVerified が true の時のサーバー側の許可状態です。

AndroidInstallSource

InstallSourceResult.DetectedSource が返す正確な enum 値です。manual のストア名は読みやすい表示名であり、コードでは下記の enum 名で比較してください。

説明
GooglePlayStoreGoogle Play Store からインストールされた場合です。
SamsungGalaxyStoreSamsung Galaxy Store からインストールされた場合です。
AmazonAppstoreAmazon Appstore からインストールされた場合です。
HuaweiAppGalleryHuawei AppGallery からインストールされた場合です。
OneStoreONE Store からインストールされた場合です。
XiaomiGetAppsXiaomi GetApps からインストールされた場合です。
OppoAppMarketOPPO App Market からインストールされた場合です。
VivoAppStoreVivo App Store からインストールされた場合です。
Custom元の installer package が customAuthorizedPackages と一致した場合です。
ADBAndroid が空の installer package を返した場合です。通常は ADB または sideload 形式のインストールで発生します。
DetectionFailedJNI またはプラットフォーム API を利用できず、installer 照会そのものが失敗した場合です。ADB とは別です。
UnknownAndroid が package name を返したものの、標準リストにもカスタム許可リストにもない場合です。
EditorUnity Editor 内で実行中に返されます。
NotApplicableAndroid のインストール元という概念が適用されないプラットフォームで返されます。

OZeroDeviceBindingDetector OZeroSDK.Security

端末に紐づくセーブスロットとサポート用リセットフローのためのヘルパー API です。Device Binding が有効な場合、検証器は自動で開始されます。クラウドセーブ、アカウントセーブスロットなどを現在の端末に紐づけたい場合だけ、以下のトークンメソッドを直接呼び出してください。

メソッド

void Initialize()

ローカル端末フィンガープリントを準備し、登録または検証します。通常のプロジェクトでは SDK 起動時に自動で呼び出されます。

string BindToSaveSlot(string saveSlotKey)

セーブスロットキーを現在の端末に紐づけるトークンを作成します。トークンはセーブメタデータまたはサーバー記録に保存し、プレイヤーが直接編集できるセーブ本文には入れないでください。

bool ValidateSaveSlot(string saveSlotKey, string storedToken)

保存済みのセーブスロットトークンが現在の端末と一致するか確認します。一致しない場合、設定された Device Binding 違反応答が発生します。

string GetCurrentFingerprintHash()

現在の端末フィンガープリント hash を返すデバッグ/デモ用ヘルパーです。本番ゲームコードで表示、アップロード、保存しないでください。

void ClearStoredFingerprint(string authorizationToken = "")

この端末に保存されたフィンガープリントを削除します。Editor 以外のビルドではサーバー発行の Reset Token を渡す必要があり、正当なサポート用リセットフローでのみ使用してください。

using OZeroSDK.Security;

var detector = OZeroDeviceBindingDetector.Instance;
string slotKey = "account:1234:slot:main";

string token = detector.BindToSaveSlot(slotKey);
// Store token next to your save metadata.

bool ok = detector.ValidateSaveSlot(slotKey, token);

OZeroSecurityConfig ScriptableObject

OZero セキュリティモジュールの基本設定を保持する Unity の ScriptableObject アセットです。Config Dashboard や Inspector で値を変更すると、ビルド時にプレイヤーで使用される保護設定として含まれます。コードで現在の設定を確認する必要がある場合は、OZeroSecurityConfig.Instance を使用します。

フィールド

フィールドは ResponseIntegrity などのネストされた設定クラスにグループ化されます。この表は、コードから確認することが多い項目や統合時によく調整する項目の要約です。Inspector の全設定表は manual を参照してください。デフォルト値はコードに保存されたシリアライズ初期値を基準にしています。リリースビルドで実行時の値が強制的に変わる項目は * で示します。

フィールド デフォルト 説明
— トップレベル —
developerSecret string "" OZeroSV_FileOZeroSafePlayerPrefs のデータを保護するプロジェクト別 secret です。最初のリリース前に Config Dashboard の Generate Secure Secret で生成し、リリース後は変更しないでください。変更すると既存の保護データを新しいビルドで復号できません。
enableLog bool true SDK のデバッグログを有効にします。開発/QA の原因調査には役立ちますが、リリース時のログ公開ポリシーは別途確認してください。
enableFailureDiagnostics bool false セキュリティ失敗の診断ファイルを Application.persistentDataPath に保存します。QA またはカスタマーサポート調査中だけ有効にし、確認後は再度オフにしてください。
— Response —
response.forceQuitOnDetection bool true 脅威が確認されたときにアプリを自動終了するかどうかを決定します。QA中はオフにしてイベントだけを観察できますが、リリースビルドではプロジェクトポリシーに合わせて明確に選択してください。
response.fatalCallbackGraceSeconds float 10 脅威検知後、ゲーム側のセキュリティコールバック UI がプレイヤーへ案内できる最大時間(秒)です。即時終了したい場合だけ 0 に設定してください。
— Managed Verification UI —
managedVerificationUiPolicy (Pro) OZeroManagedVerificationUiPolicy BuiltInBlockingDialog OZero Managed Build Integrity と Steam DRM の状態をユーザーへ表示する UI フローを選択します。内蔵モードでは SDK が nonce/attest、managed session verification、オンライン必須通知、再試行、timeout UI を処理します。SDK ダイアログを置き換える場合だけ Custom UI / Callback Only を使ってください。
managedVerificationDialogPrefabResourcePath (Pro) string "" コピーしてカスタマイズした OZero Managed Verification UI prefab の Resources パスです。空のままにすると SDK の既定 prefab を使用します。
managedVerificationRetryTimeoutSeconds (Pro) int 15 プレイヤーが Retry を押してから retry-timeout として報告するまで待機する最大秒数です。
managedVerificationOnlineRequiredTimeoutSeconds (Pro) int 120 オンライン必須状態を維持し、設定された timeout action を適用するまで待機する最大秒数です。
managedVerificationTimeoutAction (Pro) OZeroManagedVerificationTimeoutAction BlockSession timeout 時にダイアログを維持する、保護セッションをブロックする、アプリを終了する、または callback のみ呼び出すかを選択します。
autoRetryManagedVerificationWhenNetworkRestored (Pro) bool false ネットワーク接続が復旧したときに managed verification を自動的に再試行します。明示的なプレイヤー操作なしで再試行しても安全なゲームフローでのみ有効にしてください。
managedVerificationLanguageCode (Pro) string auto 内蔵 UI 文字列に使用する言語コードです。autoApplication.systemLanguage に従います。
managedVerificationFallbackLanguageCode (Pro) string en 選択した JSON リソースが見つからない場合の fallback 言語です。カスタムリソースは ozero_ui_text_{code}.json 形式を使用します。
— Integrity —
integrity.useIntegrity bool true Build Integrity モジュールを有効にするマスタースイッチです。
integrity.validateOnStartup bool true Start()で完全な整合性チェックを実行します。
integrity.periodicCheckInterval float 300 定期的な再検証実行間隔(秒)です。コードのデフォルトは 300 で、0 以下にすると定期チェックを無効化します。
integrity.checkAssemblyHash bool true OZeroAssemblyManifestに対するコンパイル済みアセンブリのSHA-256 / 公開鍵トークン検証。
integrity.checkDebugger bool true アタッチされたマネージドデバッガー、Unityデバッグビルドフラグ、CPUタイミング異常を検知。
integrity.checkPlatformNative bool true プラットフォーム固有のネイティブチェック(Root、Jailbreak、APK署名、Authenticodeなど)を実行。
integrity.failIfManifestMissing bool false* manifest の欠落または読み込み失敗を違反として処理します。*development 以外のプレイヤービルドでは、シリアライズ値に関係なく true に強制されます。
integrity.failIfAssemblyHashBlobMissing bool false* 生成されたアセンブリハッシュブロブの欠落を違反として処理します。*development 以外のプレイヤービルドでは true に強制されます。
integrity.requireManifestSignature bool false* manifest に有効な署名を要求します。キーは Window → OZero Security → Config & DashboardGenerate Key Pair で生成してください。*リリースプレイヤービルドでは true に強制されます。
integrity.il2cppHashGlobalGameManagers bool false Windows IL2CPP ファイルハッシュに globalgamemanagers を含めます。Standard と Strict プリセットではオンになります。
integrity.il2cppHashSharedAssets bool false Windows IL2CPP ファイルハッシュに sharedassets* ファイルを含めます。Standard と Strict プリセットではオンになります。
integrity.il2cppHashSceneFiles bool false Windows IL2CPP ファイルハッシュに level* などの Unity シーンファイルを含めます。Standard と Strict プリセットではオンになります。
integrity.blockEmulator bool true (Android) エミュレーター検知を整合性違反として処理。
integrity.checkIntegrityWithServer (Pro) bool false Pro の nonce → attest フローを有効にします。OZero Managed と既定の Managed Verification UI を使う場合、SDK がビルド整合性証拠の送信、managed session 判定要求、ユーザー向け retry/timeout 状態表示をゲームコードなしで処理します。
integrity.attestationVerificationMode (Pro) enum CustomerGameServer OZA トークンを顧客ゲームサーバーで最終検証するか、OZero Managed 検証が SDK 管理セッションフローで判定を返すかを選択します。
integrity.attestationNetworkPolicy (Pro) enum BestEffort オフラインまたは再検証失敗時にローカル保護で継続するか、オンライン必須の再試行状態を通知するかを選択します。既定の Managed Verification UI モードではこの状態が自動表示されます。
— InstallSource (Android) —
installSource.useInstallSource bool true インストール元検証のマスタースイッチ。
installSource.allowGooglePlayStore bool true Google Playからのインストール許可(Galaxy Store、Amazon Appstore、AppGallery、OneStoreなど個別ストアフラグもトグル可能)。
installSource.enableServerSync (Pro) bool false ローカル検出後に /v1/install-source/verify を呼び出し、Pro サーバーの allowlist と監査ログを適用します。
installSource.allowDetectionFailed bool false Android installer 照会そのものが失敗しても起動を許可します。検証済みの端末別理由がない限り、リリースではオフにしてください。
installSource.allowUnknownSources bool false 標準リストにも customAuthorizedPackages にもない installer package を許可します。
— Steam Anti-Piracy —
steamAntiPiracy.useSteamAntiPiracy bool false Steam 起動、権限、DLC、リリース hygiene 検査の master switch です。
steamAntiPiracy.detectionAction OZeroSteamDetectionAction Callback Steam 検証失敗時に使うローカル応答です。Pro ポリシーがこの値を override する場合があります。
steamAntiPiracy.checkSteamDrmWithServer (Pro) bool false サーバー根拠を使った Steam DRM 検証を有効にします。OZero Managed と既定の Managed Verification UI を使う場合、SDK が Steam ticket 送信、activation token cache、オンライン必須 UI、再試行、timeout 状態を処理します。
steamAntiPiracy.steamDrmVerificationMode (Pro) enum OZero Managed OZero 管理検証または顧客ゲームサーバー検証のどちらで Steam DRM を運用するか選択します。OZero Managed は既定の Managed Verification UI と組み合わせると、自社バックエンドなしの統合経路になります。
steamAntiPiracy.steamDrmNetworkPolicy (Pro) enum Best Effort Steam DRM 再検証が必要な時点でサーバーへ接続できない場合のクライアント挙動を制御します。既定の Managed Verification UI モードではオンライン必須と再試行フローが自動表示されます。
— DeviceBinding —
deviceBinding.useDeviceBinding bool true SDK 起動時の Device Binding 検証を有効にします。
deviceBinding.hardwareChangeTolerance int (0–3) 1 端末フィンガープリントの構成項目がいくつ変わっても同じ端末とみなすかを決めます。
deviceBinding.enableServerSync (Pro) bool false Pro 専用です。/v1/device/register/v1/device/verify で端末フィンガープリントを登録・検証します。ネットワーク失敗だけではゲームを止めませんが、サーバーの明確な拒否は Device Binding 違反になります。
deviceBinding.maxDevices (Pro) int 0 1 つのライセンスに登録できる端末数を示す参考値です。実際の運用上限はサーバーのライセンス記録または Customer Portal のポリシーに従います。
— SpeedHack —
speedHack.useSpeedHack bool true スピードハックディテクターのマスタースイッチ。
speedHack.checkInterval float 1.0 検査間隔(秒)です。小さすぎる、または大きすぎる値は安全な範囲内に自動補正されます。
speedHack.requiredDetections int 3 違反と判断する前に必要な連続した疑わしいサンプルの数です。小さすぎる、または大きすぎる値は安全な範囲内に自動補正されます。
speedHack.detectSlowHack bool false 低速化による時間操作も検出します。意図的なスローモーションでの誤検知を減らすため、既定値はオフです。
speedHack.useWebTimeValidation bool true 外部エンドポイントとのHTTPS HEADベースのゲーム時間クロス検証を有効化。
speedHack.webTimeUrls[] string[] [] Web 時刻のクロスチェックに使う HTTPS アドレス一覧です。自分で管理する、または信頼できるアドレスを 2 つ以上設定してください。リストが空の場合、Web 時刻検証に使えるアドレスはありません。
speedHack.minSuccessfulEndpoints int 2 1 回の web-time 検査ラウンドを成功として扱うために、webTimeUrls のうち最低いくつが有効な Date ヘッダーを返す必要があるかを決めます。
speedHack.maxConsecutiveFailures int 6 web-time 検査ラウンドがこの回数だけ連続で失敗すると、onWebTimeUnavailable ポリシーを実行します。
speedHack.onWebTimeUnavailable WebTimeUnavailablePolicy WarnOnly Web/サーバー時刻を何度も確認できない場合のポリシーです。WarnOnly はログだけ残して継続します。Strict は繰り返し失敗後に SpeedHack イベントを発生させます。Silent はログも残さないため、特殊テスト用に留めてください。
speedHack.enableRemoteSpeedHackConfig bool false Pro サーバー機能です。有効にすると、/v1/speedhack-config が Speed & Time Hack の一部しきい値をアプリ再ビルドなしで上書きできます。実際の呼び出しには有効な Pro ライセンスとサーバー URL が必要です。
speedHack.remoteSpeedHackConfigInterval float 300 /v1/speedhack-config を再取得する間隔です。0 は起動時に一度だけ取得します。
speedHack.remoteSpeedHackConfigJitterPercent float 20 Pro リモート設定要求が多くの端末で重ならないよう、設定した更新周期の前後に呼び出し時刻を分散する比率です。075 に制限されます。
speedHack.enableSignedServerTime bool false Pro サーバー機能です。Pro アクティベーションが使えるとき、署名付き /v1/time を優先信頼時刻として使います。連続失敗後は設定済みの web-time endpoint に戻ります。
— PhysicsHack —
physicsHack.useGlobalPhysicsHackbooltrueすべての OZeroPhysicsHackDetector コンポーネントをまとめてオン/オフするグローバルスイッチです。オブジェクトごとの移動基準値は各コンポーネントの Inspector に残ります。
physicsHack.enableServerTelemetry (Pro)boolfalsePro 専用で、既定では無効です。プロジェクトが明示的に同意し、有効なライセンスに権限がある場合のみ、一般セキュリティイベントと詳細な PhysicsHack telemetry を送信します。無効化すると新しい telemetry 送信を停止し、サーバーポリシーはローカル同意なしに送信を有効化できません。
physicsHack.telemetryThrottlePerMinute (Pro)int30このクライアントが 1 分間に送信できる PhysicsHack telemetry 数です。0 は無制限のため、調整ミスのある detector がサーバーを呼びすぎる可能性があり推奨しません。
— Injection —
injection.useInjection bool true Injection & Hooking 全体のスイッチです。プレイヤービルドでは設定された応答ポリシーに従って処理し、開発ビルドでは原因確認のため警告中心の診断フローで動作し、エディターでは通常検査しません。
injection.injectionWhitelistEntries OZeroInjectionWhitelistEntry[] empty Injection Detector に登録するローカル信頼モジュールリストです。Pro 専用ではなく、すべてのティアで使用できます。ゲームと一緒に配布する、または QA、診断ファイル、Pro telemetry、OZero サポート案内で確認したモジュールだけ追加してください。

WebTimeUnavailablePolicy

設定済みの web-time アドレスが maxConsecutiveFailures ラウンド連続で失敗した後に適用されるポリシーです。一時的なネットワーク問題をログだけにするか、セキュリティコールバックへ上げるかを決めます。

説明
WarnOnly既定値です。警告ログだけを残し、ゲームは続行します。オフラインでも動作する必要があるゲームには最も安全な選択です。
Strict繰り返し失敗した後に SpeedHack コールバックを発生させます。ネットワーク品質が低い場合も web-time 失敗は起こり得るため、実際のサービス地域のネットワークでテストしてから使ってください。
Silentログもコールバックも発生させません。短い互換性テスト用に留め、リリースビルドでは推奨しません。
developerSecretは最初のリリース前に必ず設定し、その後変更してはいけません。変更すると既存のセーブデータ(PlayerPrefsおよびファイル)を新しいビルドで復号できません。

OZeroLicenseConfig OZeroSDK.Security.License

Resources/OZeroLicenseConfig からロードされる ScriptableObject です。ライセンスティアを選択し、Plus/Pro ライセンスキーと Pro ランタイムサーバー設定を保持します。アセットがないかキーが空の場合、Standard と同じ方法で動作します。

フィールド

フィールド 説明
tierOZeroLicenseTierStandard は完全オフラインで動作します。Plus はプロジェクトバインディング native variant を有効化します。Pro は Plus を含み、サーバーベースのランタイム機能を有効化します。
licenseKeystringプロジェクトに発行された Plus/Pro ライセンスキーです。Plus はプロジェクト専用 Native Variant の確認に使い、Pro はランタイム有効化とサーバー機能にも使います。空の場合は Standard と同じ方法で動作します。
serverBaseUrlstringPro ランタイムサーバーの Base URL です。有効化、テレメトリー、signed time、attestation、サーバーポリシー呼び出しに使います。Standard と Plus のランタイムはこの URL を呼び出しません。
serverPublicKeyHexstringPro 専用のサーバー署名公開キーです。Customer Portal > Server Key の Active publicKey をコピーして入力します。Pro ランタイムの signed activation、time、attestation、offline policy トークン検証に使います。Plus Variant manifest はこのフィールドではなく、SDK 内蔵の OZero Variant signing key で検証されます。
previousServerPublicKeyHexstringPro サーバーキーのローテーション猶予期間だけ使う以前の署名用公開キーです。通常は空のままにしてください。
tokenTtlSecondsintPro ランタイムのオフラインキャッシュ保持時間です。満了後は、再度有効化に成功するまで Pro サーバー機能が無効になります。
offlineProPolicyModeOZeroOfflineProPolicyModeデバイスがオフラインのとき、署名済みの Pro ポータルブロックポリシーをどう使うかを決めます。
activationTimeoutSecondsfloatPro ランタイム有効化のタイムアウトです。時間内に有効化が終わらない場合、利用できる Pro キャッシュを使うか、Standard/serverless 方式でゲーム起動を続行します。
enableLogboolOZeroSecLog を通じてライセンスフローの診断ログを出力します。Plus/Pro 設定中に特に役立ちます。
enableDevicePolicyHeartbeatboolPro 専用。現在のデバイスが引き続き許可されている状態か定期的に確認します。
devicePolicyHeartbeatIntervalfloatPro デバイスポリシー確認の基本間隔です。既定値は 300 秒で、0 にすると定期確認を無効にします。
devicePolicyHeartbeatJitterPercentfloat多くの端末が同時にデバイスポリシーを確認しないよう、設定周期の前後に確認時刻を少し分散する比率です。075 に制限されます。
enableSecurityLevelCheckboolPro 専用。ビルドが期待されるセキュリティレベルを宣言しているかサーバーで確認できるようにします。
declaredSecurityLevelOZeroDeclaredSecurityLevelこのビルドがサーバーに宣言するセキュリティレベルです。
failOnSecurityLevelRejectbooltrue の場合、サーバーが宣言されたセキュリティレベルまたは設定ハッシュを明示的に拒否すると、設定された強い対応を実行します。
securityLevelCheckIntervalfloatサーバー側セキュリティレベル再確認の間隔です。0 は起動時に一度だけ確認します。
securityLevelCheckJitterPercentfloat多くの端末が同時にセキュリティレベルを再確認しないよう、設定周期の前後に確認時刻を少し分散する比率です。075 に制限されます。

OZeroDeclaredSecurityLevel

セキュリティレベル検証を有効にしたとき Pro サーバーへ送信する enum です。サーバーはこの値がライセンスに設定された最小レベルを満たすか確認します。

説明
Lowプロトタイプまたは開発ビルド向けのレベルです。サーバーポリシーが低い保護宣言を明示的に許可する場合だけ使ってください。
Standard既定値で、通常の保護済みライブゲームビルドに推奨する宣言です。
Strict最大保護の宣言です。strict ポリシーでプロジェクトが正常動作することを QA で確認したあとに使ってください。

OZeroOfflineProPolicyMode

Pro ポータルで端末・バージョン・国などのブロックポリシーを配布したあと、プレイヤーが一時的にオフラインになった場合の扱いを決める enum です。初めて触る場合は既定値の ApplyCachedBlockPolicies を使ってください。

説明
ApplyCachedBlockPolicies推奨値です。最後に受け取った署名済みブロックポリシーをオフライン中も適用します。通常のライブゲームに適しています。
RequireFreshPolicy有効期限内の新しいポリシーが確認できない場合は Pro 保護を使いません。常時オンライン前提で、古いポリシーを許可できないゲームだけが選ぶ値です。
IgnoreCachedBlockPoliciesオフライン中はキャッシュ済みブロックポリシーを無視します。テストや特殊な移行用の値で、ライブビルドには推奨しません。

プロパティ

static OZeroLicenseConfig RuntimeInstance { get; }

Resources からランタイム設定をロードします。null の場合は Standard と同じ方法で処理してください。

bool IsServerlessMode { get; }

Standard、Plus または空のライセンスキーであれば true です。Pro アクティベーションが必要な場合にのみ false です。

bool IsVariantTier { get; }

Plus と Pro の場合 true です。Native Variant 検証対象の tier を識別し、private Variant の有無はインポート済みの署名 manifest から自動判定します。

OZeroLicenseRuntime OZeroSDK.Security.License

現在のライセンス状態を読み取る実行中 API です。アプリ起動時に自動初期化されるため、ほとんどのプロジェクトは状態を読み取るか HasCapability を呼び出すだけで十分です。

プロパティ

名前 説明
EntitlementOZeroLicenseEntitlement現在アクティベートされている Pro 権限情報です。Standard モードでは null です。
HasEntitlementbool現在の Pro アクティベーション情報が存在すれば true です。
IsServerlessboolSDK が Pro サーバー機能なしで実行中であれば true です。
Initializedboolライセンスランタイムの初回の起動処理が終わると true になります。
IsProDowngradedboolPro アクティベーション失敗または満了後、SDK が Standard として静かに実行を継続していれば true です。
DowngradeReasonstring直近の自動ダウングレード(基本保護の切り替え)の診断理由です。
DeviceIdProviderFunc<string>アクティベーションに使用する device id を選択的に変更できます。プロジェクトで独自の識別子を使用する必要がある場合は、初期化前に設定してください。

メソッド

static Task Initialize()

複数回呼び出しても安全な開始メソッドです。通常は SDK が自動で呼び出し、カスタムブートストラップではライセンス状態を読み取る前に await することができます。

static bool HasCapability(string cap)

現在のアクティベーション情報に telemetrysigned_timeattestation などの機能権限があるか返します。Standard では false です。

Standard と Plus はランタイムアクティベーションを必要としません。Pro がアクティベーションに失敗しても、ゲームプレイは Standard 機能で継続して動作し、Pro 専用機能のみ利用できなくなります。

ライセンスサーバーのランタイム呼び出し

Pro 機能は /v1 以下の HTTPS JSON API を使用します。ほとんどの呼び出しは SDK が自動で実行します。独自のゲームサーバーを持つチームは /v1/validate で OZA トークンを検証し、決済や財貨支給のような重要なアクションには consumeToken=true を使用して同じトークンの再利用を防ぐことができます。独自のサーバーがないチームは OZero サーバーの許可/警告/遮断の結果を使用できます。

エンドポイント 用途
POST /v1/activate現在のデバイスで Pro ライセンスをアクティベートし、ローカルのアクティベーション情報を更新します。
GET /v1/time有効になっている場合、Speed & Time Hack 検証に使用する signed server time を提供します。
POST /v1/attest有効になっている無결성(無欠性)検査の通過後、固有のトークン ID が含まれた Pro build attestation トークンを発行します。nonce は送信されたビルド証拠とアプリの識別情報に紐づけられます。
POST /v1/validateゲームサーバーで OZA トークンを検証します。ランキング、決済、財貨支給のような重要な1回限りのアクションは consumeToken=true を使用して同じトークンの再利用を遮断できます。
POST /v1/managed-session自社のバックエンドがないチームのために、OZero が Pro OZA トークンを検証し、許可/警告/遮断の結果と短いセッションを返します。SDK はセッション満了前に自動再検証を試み、同じトークンを再利用する流れは遮断されます。
POST /v1/telemetryPro テレメトリ権限がアクティブになっている場合、セキュリティイベントをサーバーに送信します。

POST /v1/activate contract

Unity SDK が Pro ライセンスを有効化するときに送信する基本リクエスト契約です。サーバーの schema はネイティブ検証用フィールドを追加で受け取れますが、現在の SDK の基本アクティベーション要求は以下のフィールドを送信します。

フィールド必須説明
licenseKeystringyes/v1/activate で使う Pro ライセンスキーです。サーバーはキー形式、状態、ティア、有効期限、端末数制限を確認します。
deviceIdstringyesデバイス識別子です。必要な場合は OZeroLicenseRuntime.DeviceIdProvider で独自に指定できます。
sdkVersionstringyesクライアント SDK のバージョンです。
platformenum stringyesUnity の実行プラットフォームです。サーバーは許可された platform 値だけを受け付けます。
appIdentifierstringoptionalUnity アプリケーション識別子です。空でない場合だけ送信されます。
companyNamestringoptionalUnity PlayerSettings の会社名です。空でない場合だけ送信されます。
productNamestringoptionalUnity PlayerSettings の製品名です。空でない場合だけ送信されます。
webglOriginstringoptionalWebGL ビルドで検出した origin です。値がある場合だけ送信されます。
フィールド説明
activatedboolアクティベーションが成功したかどうかです。正常応答では true です。
tierstringサーバーが認めたライセンス tier です。
capabilitiesstring[]このライセンスで使用できる機能一覧です。
serverFeaturesEnabledboolPro サーバー機能を使用できるかどうかです。
signedTokenstringサーバーが署名したアクティベーショントークンです。以降の Pro サーバー機能検証に使われます。
keyIdstring署名キーの識別子です。トークン検証キーのローテーションに使われます。
expiresAtnumberアクティベーション情報の有効期限です。
serverUnreachablePosturestringサーバーに一時的に到達できないとき、キャッシュをどう扱うかを決めるポリシーです。
失敗応答は codemessage を持つ JSON です。主なコードは BAD_JSON, BAD_REQUEST, LICENSE_NOT_FOUND, LICENSE_PENDING, LICENSE_SUSPENDED, LICENSE_REVOKED, LICENSE_EXPIRED, DEVICE_BLOCKED, ACTIVATION_LIMIT, SERVER_NOT_CONFIGURED, SIGN_FAILED です。SDK は、ライセンス・デバイス・identity の明示的な拒否と一時的なネットワーク失敗を分けて扱います。
ネットワーク障害、メンテナンス、ライセンスの期限切れはゲームプレイを直ちに中断しません。SDK は基本保護機能を維持し、次のアクティベーション可能なタイミングで Pro 機能を再試行します。

OZeroAbortCode とイベントメッセージ

OZero がセキュリティ脅威を確定すると、OZeroSecurityEvent を作成し、SDK の基本対応フローとプロジェクトで登録したコールバックへ渡します。イベントには ModulationType、安定した公開 OZeroAbortCodeMessageKey、安全な英語 MessageWillAbort が含まれます。

Abort code とメッセージ表

コード OZeroAbortCode ModulationType MessageKey メッセージ
0x01MemoryModulationMemoryModulationmemory_modulationProtected memory value changed unexpectedly.
0x02InjectionInjectioninjectionUnexpected module, hook, or runtime injection signal detected.
0x0ABuildIntegrityBuildIntegritybuild_integrityBuild integrity validation failed.
0x0CSpeedOrTimeHackSpeedHackspeed_hackSuspicious time scale or execution speed change detected.
0x0CSpeedOrTimeHackTimeHacktime_hackSystem clock or trusted time anomaly detected.
0x0EDeviceOrInstallPolicyDeviceBindingModulationdevice_bindingDevice binding policy rejected the current device.
0x0EDeviceOrInstallPolicyInstallSourceinstall_sourceApplication install source is not trusted.
0x0FPhysicsHackPhysicsHackphysics_hackAbnormal physics behavior exceeded the configured policy.
0x10EnvironmentModulationEnvironmentModulationenvironment_modulationUnsupported or unsafe runtime environment detected.
0x13SteamAntiPiracySteamAntiPiracysteam_antipiracySteam ownership or ticket validation failed.

ログや多言語 UI を作成する際は、OZeroAbortCodeMessageKey を基準値として使用してください。Message は開発者が状況を理解しやすい安全な表現にしているため、開発者向け画面や QA ログにそのまま表示しても問題ありません。

ランタイムでのセキュリティイベント処理

OZero は基本的に、Config Dashboard の Response 設定に従ってアプリを終了するか、ログだけを残します。独自の警告画面を表示する、サーバーログを送る、終了直前に短い保存処理を行う必要がある場合は OZeroSecurityManager.RegisterUserCallback でハンドラを登録してください。

evt.WillAbort が true の場合、現在の応答ポリシーではコールバック処理後にアプリが終了します。この時間は analytics flush や最後の保存など、短時間で終わる処理だけに使ってください。コールバックはイベント報告と終了前処理の接続点であり、OZero のセキュリティ対応を取り消すためのものではありません。

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

Injection Detector silenced -> Add to Whitelist workflow
流れ: 初回検出 -> 信頼モジュール項目を追加 -> 以降のスキャンで該当モジュールを許可処理できます。

Injection 検査で信頼済みとして扱うモジュールを登録する API です。ゲームと一緒に配布する overlay、録画ツール、運営用プラグイン、パートナーモジュールなど、正常動作だが検出される可能性があるものを例外にする場合に使います。HashHex は該当モジュールファイルの SHA-256 hash、SignerHex はモジュール署名証明書の SHA-256 hash です。値を推測して入力せず、実際の配布ファイルまたは診断結果で確認した値だけ登録してください。

データ構造 — 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 でローカル信頼モジュール項目を登録するときのデータ構造です。HashHex は必須の 64 文字 SHA-256 ファイル hash、SignerHex は任意の 64 文字 signer fingerprint です。Typepemachoso のいずれかでモジュール形式を示し、Comment は運用者向けメモです。

ランタイム 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);

実行中に信頼モジュールリストをネイティブ検査器へ渡す、または現在のプラットフォームでこの機能を使用できるか確認するときに使います。多くのプロジェクトでは Config Dashboard の Injection 設定だけで十分です。コードから直接呼び出す場合は、配布ファイル確定後に必要な項目だけ登録し、登録前後の結果を QA ログで確認してください。

Config — OZeroSecurityConfig.InjectionSettings

// Preferred local trusted-module surface in the Injection settings.
public OZeroInjectionWhitelistEntry[] InjectionWhitelistEntries { get; }

InjectionWhitelistEntries は Injection 設定に含まれるローカル信頼モジュールリストです。顧客 PC に偶然インストールされたプログラムを広く許可するための設定ではなく、開発会社が一緒に配布し、正常動作を確認したモジュールだけ登録する場所です。このローカルリストはすべてのティアで使えます。Pro 顧客はカスタマーポータルのサーバー管理 whitelist で、運用中に同じ性質のポリシーを更新できます。