API 레퍼런스

OZeroSecurityManager OZeroSDK.Security

모든 활성 보안 모듈을 관리하는 중앙 싱글톤입니다. DontDestroyOnLoad를 통해 씬 전환 시에도 유지됩니다. 정적 Instance 프로퍼티로 접근하세요. OZeroBootstrapper가 런타임 시작 시 [RuntimeInitializeOnLoadMethod]를 통해 자동 생성합니다 — 직접 인스턴스화하지 마세요.

프로퍼티

메서드

서드파티 콜백을 유저 체인에 등록합니다. 내장 기본 핸들러는 별도 체인에서 동작하므로 유저 콜백을 해제해도 무력화되지 않습니다. 콜백은 모듈 타입, 공개 abort code, 메시지 키, 안전한 진단 메시지, 현재 정책상 앱 종료 여부를 담은 OZeroSecurityEvent를 받습니다.

이전에 등록한 유저 콜백을 제거합니다. 메모리 누수 방지를 위해 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에 전달되는 고객 공개용 위반 이벤트 payload입니다. 내부 탐지 세부 정보 대신 안정적이고 안전한 진단 정보만 노출합니다.

ModulationType enum

어떤 보안 모듈이 경보를 발생시켰는지 식별합니다. OZeroSecurityEvent.Type으로 전달됩니다.

OZeroBootstrapper OZeroSDK.Security

별도 와이어링이 필요 없는 자동 부트스트랩 진입점입니다. 이 클래스를 직접 호출할 필요는 없습니다. SDK를 Unity 시작 흐름에 연결하고, 검증된 보안 설정을 로드하며, 게임 시작 전에 활성 탐지기를 자동으로 준비합니다. 가능한 경우 Native 런타임 보호도 이 과정에서 초기화됩니다.

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은 동등 연산자만 지원합니다. String은 ==, !=, +를 지원합니다. Buffer는 인덱스 연산자를 통해 바이트 배열에 직접 접근할 수 있습니다.

OZeroSafePlayerPrefs OZeroSDK.Security

Unity의 PlayerPrefs를 암호화된 드롭인 대체제입니다. 키 이름은 message authentication으로 해시되고 값은 key-derivation function 기기 바인딩 키(100,000회 반복)를 사용한 암호화됩니다. 저장된 데이터는 기기 레지스트리(Windows)나 설정 plist(iOS)를 직접 열어봐도 읽을 수 없습니다.

메서드

모든 메서드는 PlayerPrefs와 기능적으로 동일합니다. 마이그레이션 단계가 필요 없습니다 — 클래스 이름만 교체하세요.

OZeroSV_File OZeroSDK.Security

내장 무결성 검증과 함께 파일을 암복호화합니다. 키가 앱 수준(기기 바인딩 없음)이므로 스팀 클라우드 세이브와 호환됩니다. 읽기 시 무결성 검증이 먼저 실행되며, 변조된 파일은 손상된 데이터를 자동으로 반환하는 대신 예외를 발생시킵니다.

메서드

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 서버 검증(attestation)과 OZero 대행 검증(Managed Verification)을 처리하는 런타임 검증기입니다. Build Integrity가 OZeroSecurityConfig에서 활성화되면 OZeroBootstrapper가 자동 생성합니다.

검사 항목

공개 속성

이벤트 및 메서드

활성화된 모든 로컬 검사가 통과하면 호출됩니다.

활성화된 로컬 검사 또는 Pro attestation이 빌드를 거부하면 호출됩니다.

Pro 서버 attestation이 성공하고 AttestationToken에 유효한 토큰이 들어오면 호출됩니다.

수동 검증을 시작합니다. 일반 프로젝트는 대시보드의 시작 시/주기적 검증 설정을 사용하는 편이 좋습니다.

OZeroSpeedHackDetector OZeroSDK.Security

5가지 독립적인 감지 신호를 사용하여 스피드핵과 시간 조작을 감지합니다. 신호들이 서로 확인할 때만 위협을 보고하여 오탐을 줄입니다.

감지 신호

감지는 ModulationType.SpeedHack 또는 ModulationType.TimeHack으로 OZeroSecurityManager 콜백을 통해 발생합니다. OZeroSecurityConfig에서 설정합니다.

OZeroInjectionDetector OZeroSDK.Security

비정상 런타임 모듈, 후킹, 디버거, 신뢰 모듈 정책 신호를 관찰합니다. 주기 검사는 적용 가능한 경우 Jitter 스케줄링을 사용해 예측 가능한 스캔 타이밍을 줄입니다.

감지 대상

감지는 ModulationType.Injection으로 OZeroSecurityManager 콜백을 통해 발생합니다.

OZeroSecurityConfig ScriptableObject

전역 보안 설정을 저장하는 ScriptableObject 에셋입니다. 에디터에서 작성하면 빌드 파이프라인이 플레이어 빌드용 보호된 런타임 설정으로 패키징합니다. 실제 적용 설정은 OZeroSecurityConfig.Instance로 접근합니다.

필드

필드는 중첩된 설정 클래스(Response, Integrity, InstallSource, DeviceBinding, SpeedHack, Injection)로 그룹화되어 있으며, OZeroSecurityConfig.Instance의 동일 이름 프로퍼티로 접근합니다. 자주 조정되는 필드를 아래에 나열했으며, 전체 항목은 에셋의 인스펙터 툴팁을 참고하세요.

OZeroLicenseConfig OZeroSDK.Security.License

Resources/OZeroLicenseConfig에서 로드되는 ScriptableObject입니다. 라이선스 티어를 선택하고 Plus/Pro 키와 선택적 Pro 런타임 기능을 설정합니다. 없거나 비어 있으면 Standard/serverless로 동작합니다.

필드

프로퍼티

Resources에서 런타임 설정을 로드합니다. null은 Standard/serverless로 처리하세요.

Standard, Plus 또는 빈 라이선스 키이면 true입니다. Pro 활성화가 필요한 경우에만 false입니다.

Plus와 Pro에서 true입니다. 빌드 사전 검증과 native Variant 바인딩에 사용됩니다.

OZeroLicenseRuntime OZeroSDK.Security.License

현재 라이선스 상태를 읽는 런타임 facade입니다. 앱 시작 시 자동 초기화되므로 대부분의 프로젝트는 상태를 읽거나 HasCapability만 호출하면 됩니다.

프로퍼티

메서드

멱등적인 시작 메서드입니다. 보통 SDK가 자동 호출하며, 커스텀 부트스트랩은 라이선스 상태를 읽기 전에 await할 수 있습니다.

활성 entitlement에 telemetry, signed_time, attestation_v1 같은 capability가 있는지 반환합니다. Standard/serverless에서는 false입니다.

라이선스 서버 런타임 호출

Pro 기능은 /v1 아래의 HTTPS JSON 호출을 사용합니다. 대부분의 호출은 SDK가 자동으로 수행합니다. 자체 게임 서버가 있는 팀은 /v1/validate로 OZA 토큰을 직접 검증하고, 고가치 액션에는 consumeToken=true로 tokenId 재사용을 막을 수 있습니다. 서버가 없는 팀은 Managed Verification 설정으로 OZero 위임 verdict를 사용할 수 있습니다.

OZeroAbortCode 및 이벤트 메시지

확정된 보안 위반이 발생하면 SDK는 OZeroSecurityEvent를 생성합니다. 이벤트에는 ModulationType, 안정적인 공개 OZeroAbortCode, MessageKey, 안전한 영문 Message, WillAbort가 포함됩니다.

Abort code 및 메시지 표

로그나 다국어 UI를 만들 때는 OZeroAbortCode와 MessageKey를 기준값으로 사용하세요. Message는 개발자가 상황을 이해할 수 있도록 안전한 표현으로 정리되어 있어, 개발자용 화면이나 QA 로그에 그대로 표시해도 괜찮습니다.

런타임에서 보안 이벤트 처리

SDK가 abort하기 전에 분석(analytics) 큐를 비우거나, 개발자용 경고를 표시하거나, 진행 중인 게임 데이터를 안전하게 저장해야 한다면 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

hash + signer-fingerprint 화이트리스트의 프로그래밍 표면입니다. 런타임에서는 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입니다. Pro 고객은 보통 같은 정책을 포털에서 관리합니다.

런타임 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);

세 메서드 모두 static helper입니다. 선택적 기능 표면으로 취급해 먼저 가용성을 확인하고, 로컬 신뢰 항목은 최소한으로 유지하세요.

Config — OZeroLicenseConfig

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

public string[] InjectionWhitelistKeywords { get; }

InjectionWhitelistEntries는 신뢰 모듈 정책의 로컬 seed입니다. 직접 배포하거나 명시적으로 신뢰하는 모듈에만 사용하세요.