APIリファレンス

OZeroSecurityManager OZeroSDK.Security

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

プロパティ

メソッド

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

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

CustomCallbackOnly で使用するプロジェクトコールバックを登録します。ネイティブコードが取り消せない致命的終了期限を設定した後にのみ呼び出されます。通知表示や短いクリーンアップは可能ですが、終了の取り消しや期限延長はできません。

登録済みのセキュリティ終了通知コールバックを解除します。

すでに保留中の致命的セキュリティ終了を直ちに完了します。通常は通知ダイアログの OK ボタンから呼び出し、保留中の終了がなければ何もしません。

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

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

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

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

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.

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

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

Removes a previously registered managed verification text provider.

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.

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

デリゲート

RegisterUserCallback で使うコールバックシグネチャです。警告 UI、独自サーバーログ、短い保存処理が必要なときは evt.Type、evt.AbortCodeHex、evt.MessageKey、evt.Message、evt.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}");
}

OZeroSecurityTerminationNoticeEvent class

ネイティブの致命的終了期限が設定された後にのみ発行されるユーザー向けペイロードです。元の安全なセキュリティイベントと、サポートへ報告できる安定したサポートコードを含みます。

OZeroSecurityEvent class

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

OZeroPolicyActionEvent class

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

ポリシーコールバック例

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 は、キャッシュ済みのオフライン実行がまだ許可されるか、オンライン再検証が必要かをこのイベントでゲームへ通知します。

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 が必要な場合だけです。

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

Security Config > Pro - License & Online Services > Online Verification UI > Ui Policy が OZero 内蔵ダイアログを使う場合、SDK は Build Integrity と Steam DRM の managed-verification UI、再試行、timeout 状態をすでに処理します。RegisterUserManagedVerificationStateCallback は Custom 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 を押して修正してください。

OZeroSecurityTerminationNoticePolicy enum

すでに設定された致命的セキュリティ終了の直前に表示する任意のユーザー通知を制御します。Standard と Pro の両方で利用できます。

OZeroManagedVerificationTimeoutAction enum

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

ModulationType enum

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

OZeroBootstrapper OZeroSDK.Security

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

OZeroSecurityConfigRuntime OZeroSDK.Security

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

プロパティ

メソッド

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

OZero Secure Variables OZeroSDK.Security

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

対応型一覧

対応演算子

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

OZeroSafePlayerPrefs OZeroSDK.Security

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

メソッド

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

OZeroSV_File OZeroSDK.Security

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

メソッド

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

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

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

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

ファイルパスではなく、すでにメモリに読み込まれた暗号化バイトバッファを復号します。リモートダウンロードやカスタムストレージから受け取ったデータを 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 が自動生成します。

検査内容

公開プロパティ

イベントとメソッド

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

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

オンラインアドオンでは OZeroOnlineAttestation.OnAttestationPassed です。サーバーアテステーションが成功し、OZeroOnlineAttestation.Token に有効なトークンがあるときに呼び出されます。

オンラインアドオンでは OZeroOnlineAttestation.RequestGameServerAttestation に移動しました。CustomerGameServer 専用で、ローカル検査が通った後、サーバーが発行した audience、hex 64 文字の challenge、session ID でアテステーションを開始します。トークンは OZeroOnlineAttestation.TokenReady で届きます。サーバー API キーでゲームサーバーと連携するを参照してください。

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

OZeroBuildAttestationToken

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

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

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

OZeroSpeedHackDetector OZeroSDK.Security

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

検知シグナル

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

OZeroWatchdog OZeroSDK.Security

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

メソッド

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

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

同期ロード処理のための便利な 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);
    }
}

OZeroInjectionDetector OZeroSDK.Security

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

検知対象

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

OZeroPCStoreAntiPiracy OZeroSDK.Security

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

OZeroPCStoreDetectionAction

メソッド

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

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

例

using OZeroSDK.Security;

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

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

最後の検証結果

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

QueryDlcOwnership

現在の Steam ユーザーが任意 DLC を所有しているかを照会します。ゲームを終了しない照会専用の API で、DLC コンテンツの解放などの判断に使います。requiredDlcAppIds に入れた必須 DLC は起動時に自動で確認されるため、この呼び出しは不要です。Steamworks.NET を直接呼び出す代わりにこの API を使ってください。

using OZeroSDK.Security;

// Optional DLC: unlock the content only when the account owns it.
OZeroDlcOwnership dlc = OZeroPCStoreAntiPiracy.QueryDlcOwnership(1234560);
if (dlc.Owned)
{
    UnlockExpansion();
}

OZeroInstallSourceValidator OZeroSDK.Security

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

メソッドとイベント

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

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

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

InstallSourceResult

AndroidInstallSource

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

OZeroDeviceBindingDetector OZeroSDK.Security

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

メソッド

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

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

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

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

この端末に保存された指紋を消去し、現在の端末を再登録します。プレイヤービルドで Pro ライセンスとサーバー設定がある場合、空でないトークンはバックグラウンドでサーバーが発行した Reset Token として検証されるため、解除はこの呼び出しが戻った後に行われます。結果を待つには ClearStoredFingerprintAsync を使ってください。それ以外の場合は認可コールバックが判断し、トークンを AuthorizationToken で受け取ります。サーバー Reset Token を使わない場合は RequestReset を使ってください。

ClearStoredFingerprint の await 可能な形式です。メインスレッドから呼び出して await し、指紋を消去した場合は true を返します。サーバー検査はメインスレッドをブロックしないため、HTTP がメインスレッドで動く環境(Windows・macOS の IL2CPP、WebGL)でもゲームが止まりません。

保存済みの指紋の消去を要求します。プレイヤービルドでは認可コールバックが判断し、reason はログ用にコールバックへ渡されます。承認されると指紋を消去し、同じセッションで現在の端末を再登録して true を返します。エディターでは常に解除されます。

プレイヤービルドで解除を承認(true)または拒否するゲームのコールバックを登録します。null を渡すと登録を解除します。コールバックは解除を要求したスレッドで同期的に呼ばれます。認可コールバックがない場合、プレイヤービルドは有効なサーバー Reset Token がない限り解除を拒否します。

OZeroDeviceBindingResetRequest

認可コールバックに渡される読み取り専用の構造体です。

RequestReset に渡した理由です。ない場合は空文字列です。

ClearStoredFingerprint に渡したトークンです。ない場合は空文字列です。

例

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

// Reset flow: register an authorizer that performs your own check.
OZeroDeviceBindingDetector.SetResetAuthorizer(request =>
    MyAccountService.HasVerifiedResetFor(request.Reason));
bool cleared = detector.RequestReset("ticket-1234");

OZeroSecurityConfig ScriptableObject

OZero モジュールのセキュリティ設定です。エディターでは Edit > Project Settings > OZero Security で編集し、ProjectSettings/OZeroSecuritySettings.asset(共有)と UserSettings/OZeroSecuritySecrets.json(ユーザーごとの秘密値)に保存され、ビルド時にプレイヤーへ焼き込まれます。コードで現在の設定を読むには OZeroSecurityConfig.Instance を使い、エディタースクリプトから変更するには OZeroSecurityProjectSettings(Load、LoadOrCreate、Save)を使います。

フィールド

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

WebTimeUnavailablePolicy

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

OZeroLicenseConfig OZeroSDK.Security.License

オンラインライセンス設定です。エディターでは ProjectSettings/OZeroLicenseSettings.asset に保存され、Window > OZero Security > Online Services ウィンドウまたは Edit > Project Settings > OZero Security の Pro カードで編集し、ビルド時に暗号化リソースとしてプレイヤーに含まれます。ライセンスティアを選択し、Pro ライセンスキーと Pro ランタイムサーバー設定を保持します。設定ファイルがないかキーが空の場合、Standard と同じ方法で動作します。エディタースクリプトから変更するには OZeroSDK.Security.License.OZeroLicenseProjectSettings(Load、LoadOrCreate、Save、Reload)を使います。

フィールド

ローカル時刻ポリシー

このポリシーは Customer Portal > License > Local clock で管理するため、Unity 側で同期する設定項目はありません。オンラインの Pro アクティベーションにはサーバー時刻が使われます。許容差は、保存済みの Pro アクティベーション情報をオフライン起動に使用できるか判断するときだけ適用されます。

OZeroDeclaredSecurityLevel

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

OZeroOfflineProPolicyMode

デバイスがサーバーに接続できないとき、ローカル Build Integrity が署名済み Pro ポータルブロックポリシーをどう扱うかを決める enum です。値は fail-open 運用、fail-closed ポリシー強制、テスト bypass を明確に分けます。

プロパティ

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

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

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

現在のプロジェクトで明示的な native variant 互換性オーバーライドが有効な場合のみ true です。

OZeroLicenseRuntime OZeroSDK.Security.License

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

プロパティ

メソッド

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

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

[Pro] ユーザー UUID(アカウント ID)をこのセッションに紐付けます。サインイン後に呼び出してください。値はデバイス内でハッシュ化され、ハッシュだけが送信されます。前後の空白を除いて空の場合、128 文字を超える場合、制御文字を含む場合は false を返します。有効化前に呼び出しても構わず、ハッシュは有効化後に送信されます。およそ 5 秒後にデバイスポリシー確認が実行されます(最短 30 秒間隔)。

[Pro] ユーザー UUID の紐付けを解除します。サインアウト時に呼び出してください。

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

Pro 機能は /v1 以下の HTTPS JSON API を使用します。OZA v2 は audience、256-bit challenge、session ID、build evidence に結合された1回限りの token です。/v1/validate は License Server API Key と同じ binding 値を必須とし、成功した token は常に原子的に consume されます。独自 backend がないチームは root-signed keyset と OZMS receipt を使用する OZero Managed を利用します。

POST /v1/activate contract

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

サーバー API キーでゲームサーバーと連携する

[Pro] サーバー API キーを使うと、ゲームサーバーは OZero と 3 つのことを行えます。サインイン時にプレイヤーのビルドが正規品か確認する(validate)、サポートや運用のためにユーザーとデバイスを照会する(read)、ユーザーをブロック・解除する(block)です。キーはゲームサーバーだけに置きます。ゲームクライアントはキーを持たず、OZero SDK を実行してトークンをお客様のサーバーに送るだけです。

概要

Game client (OZero SDK)          Your game server                         OZero API
-----------------------          ----------------                         ---------
sign-in request        ------->  issue audience, challenge, sessionId
RequestGameServerAttestation()
TokenReady: attestToken ------>  POST /v1/validate            [validate]  ----> valid / reason
                                 allow or refuse the sign-in
SetExternalUserId(uuid)          (the SDK sends only the hash h1 with policy checks)
                                 support tool: GET /customer-api/...  [read]  ---->
                                 sanctions: POST/DELETE user-blocks   [block] ---->
policy check: callback or end  <---------------------------------------------  rule applied

The server API key lives only on your game server. Never put it in the game client.

サーバー API キーのスコープ

この API は既存のサーバー API キー(Customer Portal > サーバー鍵 > サーバー API キー)にスコープを付けて使います。キーの発行時にスコープを選び、キー一覧に各キーのスコープが表示されます。以前に発行したキーは validate のみです。

• validate:/v1/validate によるトークン検証(従来の用途)。
• read:ユーザー、デバイス、イベント、ブロックルールの照会(すべての GET リクエスト)。
• block:ユーザーブロックルールの作成・更新・解除(ユーザーのゲームを終了させる強制終了ルールを含む)。
• config:セキュリティ設定ハッシュの照会・登録・解除(/v1/customer-api/config-hashes、すべてのメソッド)。CI 用です。CI のキーには config だけを与え、block は与えないでください。

発行画面で block にチェックを入れると read も一緒にチェックされます(外すこともできます)。block だけの場合、ブロックルールの作成・解除はできますが、ユーザー・デバイス・ルール一覧は照会できません。照会も行うには read + block を使ってください。

認証と制限

すべてのリクエストは https://api.ozerosecurity.com/v1 に Authorization: Bearer <サーバー API キー> を付けて送り、有効な Pro ライセンスだけが利用できます。POST /v1/validate には validate スコープが必要で、IP ごとの制限があります。/v1/customer-api/* は GET に read、ルール変更に block が必要で(例外:/v1/customer-api/config-hashes は GET を含むすべてのメソッドに config が必要です)、キーごとに毎分 120 回と IP ごとの制限が適用されます。一覧は limit と before(前のページの nextBefore)でページ分割します。

1. 検証(validate):正規のビルドか?

SDK がビルドの整合性の証拠を OZero に送り、お客様のサーバーが決めた値に結び付いた使い切りの OZA アテステーショントークンを受け取ります。POST /v1/validate は、そのトークンがこのライセンスの正規ビルドに対して OZero がこのサインイン用に発行し、まだ使われていないことをお客様のサーバーに伝えます。サインイン、ランク戦、購入の前に使ってください。Online Services > Build Integrity > Check Integrity With Server をオンにし、Attestation Verification Mode を CustomerGameServer に設定する必要があります。

1. ゲームサーバーがこのサインイン用のバインディングを発行します。audience(ゲーム固有の名前、英数字と ._:- で 3~128 文字)、challenge(毎回新しく作る 32 バイトの乱数を hex 64 文字で)、sessionId(同じ文字で 16~128 文字)です。
2. クライアントが OZeroOnlineAttestation.RequestGameServerAttestation(audience, challenge, sessionId) を呼び出します。上の設定がオフの場合、ローカル検査がまだ通っていない場合、実行中の場合、値が不正な場合は false を返します。
3. トークンは OZeroOnlineAttestation.TokenReady(または RegisterTokenCallback)で届きます。クライアントは context.AttestToken をゲームサーバーに送ります。
4. ゲームサーバーが validate スコープを持つキーで POST /v1/validate を呼び出します。本文は { attestToken, licenseKey, audience, challenge, sessionId, enforceVersionWhitelist } で、自分が発行した値をそのまま使います。
5. valid: true ならサインインを許可します。payload からプラットフォーム、SDK・アプリのバージョン、マニフェストハッシュなどが分かります。valid: false なら拒否して reason を記録します。トークンは一度しか検証できず、2 回目の呼び出しは TOKEN_REPLAYED を返します。

ゲームクライアント(Unity):

using OZeroSDK.Online;
using OZeroSDK.Security;
using UnityEngine;

public sealed class OZeroSignInAttestation : MonoBehaviour
{
    private void OnEnable() => OZeroOnlineAttestation.RegisterTokenCallback(OnToken);
    private void OnDisable() => OZeroOnlineAttestation.UnregisterTokenCallback(OnToken);

    // 1) Your game server answered the sign-in request with a binding.
    public void OnBindingReceived(string audience, string challenge, string sessionId)
    {
        if (!OZeroOnlineAttestation.RequestGameServerAttestation(audience, challenge, sessionId))
            Debug.LogWarning("OZero attestation did not start (check Security Config > Build Integrity > Pro - Online).");
    }

    // 2) The SDK issued a token bound to that binding: send it to your game server.
    private void OnToken(OZeroAttestationTokenContext context)
    {
        MyGameServer.SendAttestToken(context.AttestToken);   // your networking code
    }
}

リクエストとレスポンス:

POST https://api.ozerosecurity.com/v1/validate
Authorization: Bearer <server API key with the validate scope>
Content-Type: application/json

{
  "attestToken": "<header>.<payload>.<signature>",
  "licenseKey": "<your license key>",
  "audience": "my-game-login",
  "challenge": "<64 hex characters, new for every sign-in>",
  "sessionId": "4b1d6c2e-8f3a-4c55-9a0e-2f1b7d9c3e11",
  "enforceVersionWhitelist": false
}

200 OK (genuine build)
{
  "valid": true,
  "reason": null,
  "payload": {
    "licenseSubject": "...", "platform": "...", "sdkVersion": "1.2.0", "appVersion": "...",
    "manifestHash": "...", "integrityFlags": "...", "deviceBindingHash": "...",
    "deviceBinding": null, "installSource": null, "countryCode": null,
    "issuedAt": "...", "expiresAt": "...", "tokenId": "..."
  }
}

403 Forbidden (rejected)
{ "valid": false, "reason": "TOKEN_REPLAYED", "payload": null }

/v1/validate の主な結果:

4xx・5xx のレスポンスにも JSON の本文があります。エラーを投げる前に本文を読んでください。キーやリクエストのエラーは { "code", "message" }、拒否されたトークンは { "valid": false, "reason" } を返します。

2. 照会(read):ユーザーとデバイスを調べる

サポートでよくある質問:通報されたユーザーがどのデバイスでプレイしたか、OZero が最近何を検知したか、通報のデバイスにこのユーザーが紐付いているか。ユーザーの UUID とライセンスの salt で h1 を計算し、下の GET エンドポイントを呼び出してください。サーバーはキーのハッシュだけを保存するため、ユーザーの h1 の一覧は返せません。デバイス上の特定ユーザーを確認するには ?h1= を渡してください。

GET /users/{h1}/devices のレスポンス例:

{
  "userKeyPrefix": "a1b2c3d4",
  "devices": [
    { "deviceId": "...", "firstSeenAt": 1789900000000, "lastSeenAt": 1790000000000, "eventCount": 12 }
  ],
  "block": null
}

3. ブロック(block):制裁と解除

主な使い方:不正が確定したら自動でブロックする、運用ツールから期間付きの制裁をかける、異議申し立てが認められたら解除する。callback は対応をゲームコードに任せ、terminate はゲームを終了させます。同じユーザーに再度送ると、適用中のルールが更新されます。

ゲームで起きること:ゲームが SetExternalUserId を呼び出してからおよそ 5 秒後(最短 30 秒間隔)のデバイスポリシー確認でルールが適用されます。callback は Module = "user_policy" の policy action をゲームに送り、terminate は policy action を先に送ってから OZ-SEC-0E の案内を表示してセッションを終了し、OZeroLicenseRuntime.LastServerBlockCode が "USER_BLOCKED" になります。マニュアルのデバイス ID とユーザー UUIDを参照してください。

4. 設定(config):セキュリティ設定ハッシュ(CI)

リリースビルドごとにハッシュを登録すると、セキュリティレベル確認はお客様のビルドだけを通過させます(マニュアルのセキュリティ設定ハッシュの許可リストを参照)。すべてのメソッドに config スコープが必要です。ハッシュはビルドログの行 [OZero] Security config digest for this <Target> build: … の小文字 hex 64 文字です。

リクエストとレスポンス:

POST https://api.ozerosecurity.com/v1/customer-api/config-hashes
Authorization: Bearer <server API key with the config scope>
Content-Type: application/json

{
  "configHash": "<64 hex characters from the build log>",
  "label": "1.2.0 release (Windows)",
  "expiresInDays": 365,
  "acknowledgeEnforcement": true
}

201 Created
{
  "hash": {
    "configHash": "...", "label": "1.2.0 release (Windows)", "status": "active",
    "createdAt": 1790000000000, "createdBy": "api-key:...", "expiresAt": 1821536000000,
    "revokedAt": null, "revokedBy": null
  },
  "created": true,
  "enforcementStarted": true
}

409 Conflict (first approval without acknowledgeEnforcement)
{ "code": "ENFORCEMENT_ACK_REQUIRED", "message": "the first approved hash turns on enforcement: ..." }

GET https://api.ozerosecurity.com/v1/customer-api/config-hashes
{
  "policy": { "activeCount": 1, "mode": "enforced" },
  "approved": [ { "configHash": "...", "label": "...", "status": "active", "expiresAt": null, "...": "..." } ],
  "observed": [ { "configHash": "...", "firstSeenAt": 1789900000000, "lastSeenAt": 1790000000000, "seenCount": 3,
                  "lastDeclaredLevel": 2, "lastSdkVersion": "1.2.0", "lastPlatform": "...", "approval": "active" } ],
  "schemaReady": true
}

DELETE https://api.ozerosecurity.com/v1/customer-api/config-hashes/<configHash>
{ "hash": { "configHash": "...", "status": "revoked", "...": "..." },
  "policy": { "activeCount": 0, "mode": "compatibility" } }

CI の例(bash、Unity ビルドの次のステップ):ビルドログ(-logFile で指定したファイル)からハッシュを読み取って登録します。キーは CI のシークレットに保存してください。

#!/usr/bin/env bash
# CI step after the Unity build. BUILD_LOG is the file passed to Unity with -logFile.
# OZERO_CONFIG_API_KEY: a server API key with only the config scope, stored as a CI secret.
set -euo pipefail

BUILD_LOG="${BUILD_LOG:-build.log}"
LABEL="${BUILD_LABEL:-ci build}"   # letters, digits and spaces only (it goes into JSON as is)

HASH=$(grep -oE 'Security config digest for this [A-Za-z0-9]+ build: [0-9a-f]{64}' "$BUILD_LOG" \
  | tail -n 1 | awk '{print $NF}')
if [ -z "$HASH" ]; then
  echo "No security config digest in $BUILD_LOG" >&2
  exit 1
fi

STATUS=$(curl -sS -o ozero-response.json -w '%{http_code}' -X POST \
  "https://api.ozerosecurity.com/v1/customer-api/config-hashes" \
  -H "Authorization: Bearer ${OZERO_CONFIG_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{\"configHash\":\"${HASH}\",\"label\":\"${LABEL}\",\"expiresInDays\":365}")

case "$STATUS" in
  200|201) echo "Approved security config hash ${HASH}" ;;
  409) echo "First approval turns on enforcement: approve once in the Customer Portal," \
            "or send \"acknowledgeEnforcement\": true on purpose." >&2
       cat ozero-response.json >&2; exit 1 ;;
  *)   echo "OZero API returned HTTP ${STATUS}:" >&2   # the body has { "code", "message" }
       cat ozero-response.json >&2; exit 1 ;;
esac

お客様 API のエラー

4xx・5xx のレスポンスも本文に { "code", "message" } を返します。本文を読み、code で分岐してください。

API で作成したルールは Customer Portal のルール一覧にサーバー APIと表示され、操作履歴には server-api-key … とキーの末尾 4 文字で記録されます。

5. 例: ゲームサーバーの 1 ファイルで試す

validate、read、block をすべて扱う Node.js モジュール全体(18 以上、追加パッケージなし)と、同じ流れの C#・Python の例です。キー、ライセンスキー、salt は環境変数から読み込みます。ハッシュ関数は使用前にテストベクターで自己確認します。429 と 503 は指数バックオフで再試行します。

// ozero-server.js - Node.js 18+ (built-in fetch and crypto, no extra packages)
const crypto = require("crypto");

const API = "https://api.ozerosecurity.com/v1";
const VALIDATE_KEY = process.env.OZERO_VALIDATE_API_KEY; // scope: validate (sign-in servers)
const OPS_KEY = process.env.OZERO_SERVER_API_KEY;        // scopes: read + block (operations tools)
const LICENSE_KEY = process.env.OZERO_LICENSE_KEY;
const SALT = process.env.OZERO_EXTUID_SALT;              // Customer Portal > User UUID > Settings
const AUDIENCE = "my-game-login";

// h1 = SHA-256("OZERO-EXTUID-V1|" + salt + "|" + uuid) as lowercase hex.
function extUserHash(salt, uuid) {
  const id = uuid.replace(/^[ \t\n\v\f\r]+|[ \t\n\v\f\r]+$/g, "");
  return crypto.createHash("sha256").update("OZERO-EXTUID-V1|" + salt + "|" + id, "utf8").digest("hex");
}

// Self-check with the published test vector.
const TEST_SALT = Array.from({ length: 32 }, (_, i) => i.toString(16).padStart(2, "0")).join("");
if (extUserHash(TEST_SALT, "player-123") !== "2d5a23607064e6dbc02dc32dc96af8cf54862d2f51d778596cfbe9d6ba8f8a3a") {
  throw new Error("extUserHash does not match the test vector");
}

// 4xx and 5xx responses carry a JSON body with "code" (for example SCOPE_REQUIRED).
class OZeroApiError extends Error {
  constructor(status, data) {
    super(`OZero API ${status}: ${data.code ?? "HTTP_" + status} ${data.message ?? ""}`.trim());
    this.status = status;
    this.code = data.code ?? `HTTP_${status}`;
  }
}

// One request helper: reads the JSON body for every status and retries 429 and 503
// with exponential backoff (0.5, 1, 2, 4 s).
async function call(key, method, path, body, attempt = 0) {
  const res = await fetch(API + path, {
    method,
    headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
  });
  if ((res.status === 429 || res.status === 503) && attempt < 4) {
    await new Promise((resolve) => setTimeout(resolve, 500 * 2 ** attempt));
    return call(key, method, path, body, attempt + 1);
  }
  return { status: res.status, data: await res.json().catch(() => ({})) };
}

async function callOk(key, method, path, body) {
  const { status, data } = await call(key, method, path, body);
  if (status >= 400) throw new OZeroApiError(status, data);
  return { status, data };
}

// 1) validate --------------------------------------------------------------
function newSignInBinding() {
  return {
    audience: AUDIENCE,
    challenge: crypto.randomBytes(32).toString("hex"),
    sessionId: crypto.randomUUID(),
  };
}

async function validateSignIn(binding, attestToken) {
  const { status, data } = await call(VALIDATE_KEY, "POST", "/validate", {
    attestToken,
    licenseKey: LICENSE_KEY,
    ...binding,
    enforceVersionWhitelist: false,
  });
  if (data.valid === true) return { ok: true, payload: data.payload };
  if (data.valid === false) return { ok: false, reason: data.reason }; // e.g. TOKEN_REPLAYED: refuse
  throw new OZeroApiError(status, data); // e.g. SERVER_API_KEY_REQUIRED: fix the key or setup
}

// 2) read ------------------------------------------------------------------
async function lookUpUser(uuid) {
  const h1 = extUserHash(SALT, uuid);
  const devices = await callOk(OPS_KEY, "GET", `/customer-api/users/${h1}/devices`);
  const events = await callOk(OPS_KEY, "GET", `/customer-api/users/${h1}/events?limit=20`);
  return { devices: devices.data.devices, block: devices.data.block, events: events.data.events };
}

async function isUserOnDevice(uuid, deviceId) {
  const h1 = extUserHash(SALT, uuid);
  const { data } = await callOk(OPS_KEY, "GET",
    `/customer-api/devices/${encodeURIComponent(deviceId)}/users?h1=${h1}`);
  return data.linked === true;
}

// 3) block -----------------------------------------------------------------
async function blockUser(uuid, action, reason, days) {
  const body = { h1: extUserHash(SALT, uuid), action, reason }; // action: "callback" | "terminate"
  if (days) body.expiresInDays = days;                            // omit to keep it until lifted
  const { data } = await callOk(OPS_KEY, "POST", "/customer-api/user-blocks", body);
  return data.block.id; // 201 created, 200 updated the user's rule in effect
}

async function liftBlock(ruleId) {
  await callOk(OPS_KEY, "DELETE", `/customer-api/user-blocks/${ruleId}`);
}

// Branch on the error code, for example in your operations tool:
async function blockFromTool(uuid) {
  try {
    return await blockUser(uuid, "terminate", "Cheating", 30);
  } catch (e) {
    if (e.code === "SCOPE_REQUIRED") throw new Error("This key has no block scope: issue a read + block key.");
    if (e.code === "API_KEY_INVALID") throw new Error("The key was revoked: deploy the new key.");
    throw e;
  }
}

module.exports = {
  newSignInBinding, validateSignIn, lookUpUser, isUserOnDevice, blockUser, liftBlock, blockFromTool, OZeroApiError,
};

// C# (.NET 6+): the same flow
using System.Net;
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;

// 4xx and 5xx responses carry a JSON body with "code" (for example SCOPE_REQUIRED).
public sealed class OZeroApiException : Exception
{
    public OZeroApiException(int status, string code, string message)
        : base($"OZero API {status}: {code} {message}".Trim())
    {
        Status = status;
        Code = code;
    }

    public int Status { get; }
    public string Code { get; }
}

public sealed class OZeroServerClient
{
    // Leave out null fields such as expiresInDays when no expiry is given.
    private static readonly JsonSerializerOptions Json = new() { DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull };
    private static readonly Uri Api = new("https://api.ozerosecurity.com/v1/");
    private readonly HttpClient _validate = Create(Env("OZERO_VALIDATE_API_KEY"));
    private readonly HttpClient _ops = Create(Env("OZERO_SERVER_API_KEY"));
    private readonly string _licenseKey = Env("OZERO_LICENSE_KEY");
    private readonly string _salt = Env("OZERO_EXTUID_SALT");

    private static string Env(string name) =>
        Environment.GetEnvironmentVariable(name) ?? throw new InvalidOperationException(name + " is not set");

    private static HttpClient Create(string key)
    {
        var http = new HttpClient { BaseAddress = Api };
        http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", key);
        return http;
    }

    public static string ExtUserHash(string salt, string uuid)
    {
        var id = uuid.Trim(' ', '\t', '\n', '\v', '\f', '\r');
        var bytes = SHA256.HashData(Encoding.UTF8.GetBytes("OZERO-EXTUID-V1|" + salt + "|" + id));
        return Convert.ToHexString(bytes).ToLowerInvariant();
    }

    // Sends the request (retrying 429 and 503 with exponential backoff) and always reads the JSON body.
    private static async Task<(int Status, JsonElement Body)> Send(Func<Task<HttpResponseMessage>> request)
    {
        for (int attempt = 0; ; attempt++)
        {
            using var res = await request();
            bool retry = res.StatusCode is HttpStatusCode.TooManyRequests or HttpStatusCode.ServiceUnavailable;
            if (retry && attempt < 4)
            {
                await Task.Delay(500 * (1 << attempt));
                continue;
            }
            JsonElement body;
            try { body = await res.Content.ReadFromJsonAsync<JsonElement>(); }
            catch (JsonException) { body = default; } // not JSON (for example a proxy error page)
            return ((int)res.StatusCode, body);
        }
    }

    // Throws OZeroApiException with the server's code for 4xx and 5xx.
    private static JsonElement Ok((int Status, JsonElement Body) r)
    {
        if (r.Status < 400) return r.Body;
        string code = $"HTTP_{r.Status}", message = "";
        if (r.Body.ValueKind == JsonValueKind.Object)
        {
            if (r.Body.TryGetProperty("code", out var c)) code = c.GetString() ?? code;
            if (r.Body.TryGetProperty("message", out var m)) message = m.GetString() ?? "";
        }
        throw new OZeroApiException(r.Status, code, message);
    }

    // 1) validate: (true, payload) allows the sign-in, (false, reason) refuses it.
    public async Task<(bool Ok, JsonElement Result)> ValidateSignIn(
        string audience, string challenge, string sessionId, string attestToken)
    {
        var r = await Send(() => _validate.PostAsJsonAsync("validate", new
        {
            attestToken, licenseKey = _licenseKey, audience, challenge, sessionId, enforceVersionWhitelist = false,
        }));
        if (r.Body.ValueKind == JsonValueKind.Object && r.Body.TryGetProperty("valid", out var valid))
            return valid.GetBoolean() ? (true, r.Body.GetProperty("payload")) : (false, r.Body.GetProperty("reason"));
        Ok(r); // no "valid": a key or setup error such as SERVER_API_KEY_REQUIRED
        throw new OZeroApiException(r.Status, $"HTTP_{r.Status}", "unexpected response");
    }

    // 2) read
    public async Task<JsonElement> LookUpUser(string uuid) =>
        Ok(await Send(() => _ops.GetAsync($"customer-api/users/{ExtUserHash(_salt, uuid)}/devices")));

    // 3) block and lift
    public async Task<string> BlockUser(string uuid, string action, string reason, int? days = null)
    {
        var body = Ok(await Send(() => _ops.PostAsJsonAsync("customer-api/user-blocks", new
        {
            h1 = ExtUserHash(_salt, uuid), action, reason, expiresInDays = days,
        }, Json)));
        return body.GetProperty("block").GetProperty("id").GetString()!;
    }

    public async Task LiftBlock(string ruleId) =>
        Ok(await Send(() => _ops.DeleteAsync($"customer-api/user-blocks/{ruleId}")));

    // Branch on the error code, for example in your operations tool.
    public async Task<string?> BlockFromTool(string uuid)
    {
        try
        {
            return await BlockUser(uuid, "terminate", "Cheating", 30);
        }
        catch (OZeroApiException e) when (e.Code == "SCOPE_REQUIRED")
        {
            Console.Error.WriteLine("This key has no block scope: issue a read + block key.");
            return null;
        }
    }
}

# Python 3 + requests: the same flow
import hashlib
import os
import secrets
import time
import uuid as uuidlib

import requests

API = "https://api.ozerosecurity.com/v1"
VALIDATE_KEY = os.environ["OZERO_VALIDATE_API_KEY"]  # scope: validate
OPS_KEY = os.environ["OZERO_SERVER_API_KEY"]         # scopes: read + block
LICENSE_KEY = os.environ["OZERO_LICENSE_KEY"]
SALT = os.environ["OZERO_EXTUID_SALT"]


def ext_user_hash(salt: str, uuid: str) -> str:
    uid = uuid.strip(" \t\n\v\f\r")
    return hashlib.sha256(f"OZERO-EXTUID-V1|{salt}|{uid}".encode("utf-8")).hexdigest()


assert ext_user_hash(bytes(range(32)).hex(), "player-123") == \
    "2d5a23607064e6dbc02dc32dc96af8cf54862d2f51d778596cfbe9d6ba8f8a3a"


class OZeroApiError(Exception):
    """4xx and 5xx responses carry a JSON body with "code" (for example SCOPE_REQUIRED)."""

    def __init__(self, status, data):
        self.status = status
        self.code = data.get("code") or f"HTTP_{status}"
        super().__init__(f"OZero API {status}: {self.code} {data.get('message', '')}".strip())


def call(key, method, path, body=None):
    """Reads the JSON body for every status; retries 429 and 503 with exponential backoff."""
    for attempt in range(5):
        res = requests.request(method, API + path, json=body, timeout=10,
                               headers={"Authorization": f"Bearer {key}"})
        if res.status_code not in (429, 503) or attempt == 4:
            try:
                data = res.json()
            except ValueError:
                data = {}
            return res.status_code, data
        time.sleep(0.5 * 2 ** attempt)


def call_ok(key, method, path, body=None):
    status, data = call(key, method, path, body)
    if status >= 400:
        raise OZeroApiError(status, data)
    return data


# 1) validate
def new_sign_in_binding():
    return {"audience": "my-game-login", "challenge": secrets.token_hex(32), "sessionId": str(uuidlib.uuid4())}


def validate_sign_in(binding, attest_token):
    status, data = call(VALIDATE_KEY, "POST", "/validate", {
        "attestToken": attest_token, "licenseKey": LICENSE_KEY, **binding, "enforceVersionWhitelist": False})
    if "valid" not in data:
        raise OZeroApiError(status, data)  # e.g. SERVER_API_KEY_REQUIRED
    return data["valid"], data.get("payload") if data["valid"] else data.get("reason")


# 2) read
def look_up_user(uuid):
    return call_ok(OPS_KEY, "GET", f"/customer-api/users/{ext_user_hash(SALT, uuid)}/devices")


# 3) block and lift
def block_user(uuid, action, reason, days=None):
    body = {"h1": ext_user_hash(SALT, uuid), "action": action, "reason": reason}
    if days:
        body["expiresInDays"] = days
    return call_ok(OPS_KEY, "POST", "/customer-api/user-blocks", body)["block"]["id"]


def lift_block(rule_id):
    call_ok(OPS_KEY, "DELETE", f"/customer-api/user-blocks/{rule_id}")


# Branch on the error code, for example in your operations tool:
def block_from_tool(uuid):
    try:
        return block_user(uuid, "terminate", "Cheating", 30)
    except OZeroApiError as e:
        if e.code == "SCOPE_REQUIRED":
            raise RuntimeError("This key has no block scope: issue a read + block key.") from e
        raise

6. 運用のヒント

• 用途ごとにキーを分けてください。サインインサーバーには validate キー、運用ツールだけに read + block キーを置きます。そうすればサインイン用キーが漏れてもユーザーをブロックできません。
• CI には config スコープだけを持つ専用のキーを与えてください。そうすれば CI のキーが漏れてもユーザーの照会やブロックはできません。
• 停止なしでキーを交換:新しいキーを発行してサーバーに配備し、その後 Customer Portal で古いキーを失効させます。
• 制限に注意してください。お客様 API はキーごとに毎分 120 回です。サポートの照会はまとめて行い、429 ではバックオフしてください。
• サーバー API キー、salt、h1、元の UUID をログや分析データに残さないでください。h1 は仮名の個人識別子として扱ってください。

OZeroAbortCode とイベントメッセージ

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

Abort code とメッセージ表

ログや多言語 UI を作成する際は、OZeroAbortCode と MessageKey を基準値として使用してください。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 検査で信頼済みとして扱うモジュールを登録する 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 です。Type は pe、macho、so のいずれかでモジュール形式を示し、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; }
public bool EnableWindowsSystemModuleScan { get; }

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

Injection 設定の enableWindowsSystemModuleScan の値を返す読み取り専用プロパティです。変更するには、Unity の Injection 設定を調整するか、Low・Standard・Strict のセキュリティプリセットを適用してください。

見慣れないシステムモジュールが見つかっても、すぐにゲームを終了することはありません。まず確認対象として記録し、繰り返し検出されたことやファイルに署名がないことだけを理由にブロックしません。既存の許可ルールは維持され、ハッシュで明示的に拒否したモジュールにはブロック方針が適用されます。このオプションは Unity の Injection 設定で変更できます。Pro ポータルからのリモート変更には対応していません。他のプラットフォームには影響しません。