시작하기

개요

OZero Security는 일반 해킹 툴이 접근하기 어려운 Native C++ 레이어에서 보안 로직을 실행하여 Unity 게임을 보호합니다. Unity 에디터 내 대시보드에서 모듈을 활성화하는 것만으로 핵심 보호 기능이 동작합니다. 씬 설정이나 별도 코드 작성은 필요하지 않습니다.

1 패키지 임포트

Unity 에디터를 열고 OZero Security 패키지를 임포트합니다. Unity Package Manager를 통하거나 .unitypackage 파일을 더블클릭하여 임포트할 수 있습니다.

Import Unity Package 다이얼로그가 나타나면 모든 항목이 체크된 상태로 Import를 클릭하세요. 필요한 스크립트, 네이티브 플러그인, 에디터 도구가 자동으로 추가됩니다.

2 대시보드 열기

임포트가 완료되면 Unity 메뉴바에서 OZero Security Dashboard를 엽니다:

커스텀 에디터 창이 열립니다. 이곳이 OZero 보안 모듈 전체를 제어하는 중앙 패널입니다. Project 하이라키는 건드릴 필요가 없습니다.

3 모듈 활성화

대시보드 안에서 보안 모듈 목록과 토글 스위치를 확인할 수 있습니다. 사용하려는 모듈을 활성화하세요. 아래는 권장 시작 구성입니다.

보안 프리셋 선택

먼저 프리셋을 선택한 뒤, 프로젝트에 맞춰 개별 모듈만 조정하세요. 일반적인 라이브 게임은 Standard부터 시작하는 것을 권장합니다. 보호 수준, 성능, 오탐 가능성의 균형이 가장 좋습니다.

별도의 "Auto Setup" 버튼을 누를 필요가 없습니다. 대시보드에서 사용할 모듈만 체크하고 OZeroSecurityConfig 에셋을 저장하면 됩니다. 플레이어 실행 시 SDK가 게임 시작 전에 활성 탐지기를 자동으로 준비합니다.

라이선스 모델 — Standard / Plus / Pro

OZero Security는 Standard, Plus, Pro 세 가지 티어로 제공됩니다. Standard는 공용 네이티브 모듈을 사용하는 완전 서버리스 구성입니다. Plus는 런타임 서버 없이 앱별 Native Variant 패키지와 매니페스트 / Bundle ID 바인딩을 추가합니다. Pro는 Plus 구성을 포함하고 Cloud Telemetry, Signed Time, 원격 정책, 서버 검증, 디바이스 한도 같은 운영 기능을 활성화합니다.

Plus / Pro 라이선스 키 등록

Standard 티어는 별도 설정이 필요 없습니다. Plus 또는 Pro는 ScriptableObject 에셋 1개를 추가하고 구매 후 받은 키를 붙여 넣습니다. Plus 키는 프로젝트별 Variant 검증과 포털 다운로드에 사용되고, Pro 키는 런타임 서버 활성화에도 사용됩니다.

1. 설정 에셋 생성

OZero Security Config & Dashboard (메뉴: OZero Security → Security → Config & Dashboard)를 열고 License & Server 섹션에서 Create OZeroLicenseConfig 버튼을 클릭합니다. 에셋이 자동으로 올바른 Resources/ 폴더에 생성되므로 수동으로 이동할 필요가 없습니다.

2. Inspector 필드 채우기

3. 빌드 & 검증

코드 변경은 필요 없습니다. OZeroLicenseBootstrap이 [RuntimeInitializeOnLoadMethod(AfterAssembliesLoaded)]로 자동 연결되어 앱 시작 시 에셋을 읽습니다. 첫 실행 시 Player 로그에서 [OZeroLicense] activated; tier=pro caps=5 같은 줄을 확인하세요. Pro 설정인데 [OZeroLicense] Standard / serverless mode.가 보이면, 에셋이 Resources/ 폴더 아래에 있고 이름이 OZeroLicenseConfig (확장자/이름 변경 접미사 없음)인지 다시 확인하세요.

서버 활성화 흐름

활성화는 앱 시작 시 백그라운드에서 진행됩니다. SDK는 절대 씬 로드를 블로킹하지 않습니다 — 6초 타임아웃이 발생해도 캐시된 entitlement (또는 Standard 폴백)를 사용해 플레이어가 검은 화면에서 HTTP를 기다리는 일이 없습니다.

부팅 시퀀스

1. SDK는 앱 시작 시 라이선스 런타임을 자동 초기화합니다.
2. Standard와 Plus는 런타임 서버 호출 없이 계속 진행됩니다.
3. Pro는 백그라운드에서 가벼운 활성화 요청을 보냅니다.
4. 활성화에 성공하면 텔레메트리, signed time, attestation 같은 Pro 서버 기능이 사용 가능해집니다.
5. 활성화 실패, 만료, 타임아웃이 발생해도 플레이어에게 오류를 표시하지 않고 Standard 모드로 계속 실행됩니다.

네트워크에 흐르는 데이터

활성화 요청은 작은 JSON POST입니다. 필수 필드는 licenseKey, deviceId, sdkVersion, platform입니다. appIdentifier, companyName, productName, webglOrigin은 Unity에서 비어 있지 않은 값을 제공할 때만 추가됩니다. 기기 식별자 소스는 OZeroLicenseRuntime.DeviceIdProvider로 오버라이드할 수 있습니다.

POST https://api.ozero.security/v1/activate
Content-Type: application/json

{
  "licenseKey":    "OZ-PRO-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX",
  "deviceId":      "<DeviceIdProvider result; default SystemInfo.deviceUniqueIdentifier>",
  "sdkVersion":    "<OZeroSdkVersion.ManagedVersion>",
  "platform":      "<android | ios | windows | macos | linux | webgl | ...>",
  "appIdentifier": "<Application.identifier>",
  "companyName":   "<Application.companyName>",
  "productName":   "<Application.productName>",
  "webglOrigin":   "<WebGL origin only>"
}

서버는 JWT 형태의 signedToken (header.payload.signature, base64url, no padding), 결정된 tier, capabilities 배열, serverFeaturesEnabled 플래그, (선택) expiresAt unix-ms를 포함한 JSON으로 응답합니다. SDK는 serverPublicKeyHex로 OZerodigital signature.VerifySignature를 호출해 signedToken을 검증한 후에만 entitlement를 받아들입니다 — 그 외는 모두 fail-closed.

Graceful degradation

서버 점검, 네트워크 타임아웃, 라이선스 만료/정지/폐기, Bundle mismatch는 조작으로 보지 않습니다. 해당 상태는 Pro 전용 기능을 Standard/serverless 모드로 강등해 플레이어 세션을 유지합니다. 반대로 빌드 불일치, 차단된 빌드, 인젝션, 디버거처럼 조작이 확정된 상태는 설정된 위협 대응 정책을 따릅니다.

오프라인 동작

OZero는 네트워크 상태와 무관하게 플레이어가 항상 게임을 실행할 수 있도록 설계되었습니다. 정확한 동작은 티어에 따라 다릅니다:

Standard — 항상 오프라인

서버는 절대 호출되지 않습니다. 10개 디텍터 모듈 모두 저하 없이 동작합니다. 라이선스 런타임은 IsServerless = true, HasEntitlement = false로 설정됩니다. OZeroTelemetryReporter는 attach되지만 모든 이벤트에서 no-op합니다.

Pro — TTL 내 오프라인 가능

지정 디바이스에서 /v1/activate가 처음 성공한 후, entitlement는 PlayerPrefs에 캐시됩니다 (기기 바인딩 키로 암호화 — 아래 캐시 보안 참조). 이후 실행에서는 네트워크 호출이 시작되기 전에 캐시가 동기적으로 읽히므로, 플레이어가 오프라인이어도 SDK는 어떤 티어이고 어떤 capability가 잠금 해제되었는지 알고 있습니다.

캐시된 entitlement는 활성화 시점에 기록된 cachedAtMillis로부터 tokenTtlSeconds 동안 신뢰됩니다. 기본 7일 (604800). 디바이스가 그 동안 계속 오프라인 상태로 TTL이 만료되면 캐시가 폐기되고, 다음 성공 활성화까지 SDK는 Standard 수준으로 강등됩니다. 디텍터는 계속 동작합니다 — 텔레메트리 전송과 signed-time 검증만 꺼집니다.

Pro — 서명된 오프라인 차단 정책

Graceful degradation은 라이선스, 네트워크, 서버 장애를 위한 동작입니다. 포털에서 명시적으로 차단한 빌드가 오프라인에서 허용된다는 뜻은 아닙니다. Pro 활성화가 성공하면 서버는 현재 포털 차단 정책을 활성화 토큰 안에 서명해 넣고, SDK는 이 정책을 entitlement와 별도로 캐시합니다.

권장값인 ApplyCachedBlockPolicies 모드에서는 서명된 정책이 유효한 동안 플레이어가 비행기 모드로 실행하더라도 차단된 manifest hash, SDK 버전, 앱 버전이 Build Integrity에서 계속 거부됩니다. 정책은 서명 토큰 TTL을 따르므로 포털에서 차단 규칙을 바꾼 뒤에는 한 번의 온라인 활성화가 필요합니다.

트러블슈팅

모든 라이선스 이벤트는 기본적으로 Unity의 Debug.Log로 라우팅되는 OZeroSecLog를 통해 기록됩니다 (OZeroSecurityConfig에서 설정 가능). Player 로그를 [OZeroLicense] 접두사로 필터링하여 부팅 시점의 결정을 확인하고, [OZeroTelemetry]로 리포터를 확인하세요. 일반적인 증상과 해결책:

프로젝트 설정

개별 보안 모듈을 조정하기 전에, 네이티브 플러그인과 스토어 빌드, 플랫폼 검증에 영향을 주는 Unity Player Settings를 먼저 확인하세요.

최소 빌드 타겟

Android ProGuard / R8 설정

OZero Security는 별도의 Java SDK 패키지를 요구하지 않습니다. 다만 Android 릴리스 빌드에서 Minify, ProGuard, R8을 활성화했다면 Unity Java 브리지와 프로젝트에서 사용하는 커스텀 Android 브리지 클래스를 보존해야 합니다. 그래야 패키지 정보, 설치 출처, APK 서명 인증서 검사, 부트 에셋 로딩에 필요한 JNI 호출이 난독화 이후에도 안정적으로 동작합니다.

# OZero Security - Unity Android ProGuard/R8 keep rules
-keep class com.unity3d.player.UnityPlayer { *; }
-keep class com.unity3d.player.UnityPlayerActivity { *; }
-keep class com.unity3d.player.UnityPlayerGameActivity { *; }
-keep class com.unity3d.player.UnityPlayerForActivityOrService { *; }
-keepattributes *Annotation*,InnerClasses,EnclosingMethod,Signature

# If your game adds custom Java/Kotlin bridge classes that OZero or your code
# calls through AndroidJavaClass / AndroidJavaObject, keep those classes too.
# Replace the package below with your own bridge package.
# -keep class com.yourcompany.yourgame.bridge.** { *; }

• libOZeroSecurity.so를 이름 변경, 삭제, 재패키징하지 마세요. 플러그인은 Assets/OZeroSDK/Plugins/Android/arm64-v8a 아래에 유지하고, 32비트 빌드를 배포한다면 armeabi-v7a도 함께 유지하세요.
• Build Integrity > Check Platform Native와 Android SHA Keys를 사용하는 경우, Minify/R8 적용 후 최종 서명된 APK 또는 AAB로 반드시 테스트하세요. 디버그 키스토어 지문과 릴리스 키스토어 지문은 서로 다릅니다.
• Minify를 켠 뒤에만 Android 로그에서 JNI 조회 실패, 설치 출처 감지 실패, APK 서명 검사 결과 비어 있음이 보인다면 먼저 커스텀 브리지 keep 규칙을 확인하세요.
• 스토어 배포용 빌드는 IL2CPP, 릴리스 서명, Android Sha Keys에 등록된 예상 Android SHA-256 지문, 그리고 최소 한 대 이상의 실제 기기 클린 실행 테스트를 기준으로 검증하세요.

5 OZeroSecurityConfig 설정

OZeroSecurityConfig ScriptableObject 에셋은 패키지 임포트 시 포함됩니다. Project 창에서 선택하여 모든 보안 모듈 설정을 확인하고 조정하세요. 런타임에서는 OZeroSecurityConfig.Instance로 접근합니다.

일반 설정

모든 모듈에 전역으로 적용되는 최상위 필드입니다.

응답 설정

보안 모듈이 탐지 이벤트를 발생시켰을 때의 동작을 제어합니다.

빌드 무결성 검증기 설정

수정된 게임 파일, 디버거 연결, 비정상적인 실행 환경을 감지하는 빌드 무결성 검사기를 구성합니다.

RSA 서명 키 생성 (빌드 무결성)

빌드 무결성을 활성화하고 Require Manifest Signature를 켠 경우, OZero는 public-key signature 비대칭 서명을 사용하여 무결성 매니페스트의 위변조 여부를 검증합니다. 릴리스 빌드를 만들기 전에 Unity 에디터에서 키 쌍을 반드시 생성해야 합니다.

매니페스트 서명 작동 방식

빌드 시점에 OZero는 개인 키로 어셈블리 매니페스트를 서명하고 그 결과 서명을 빌드에 포함시킵니다. 런타임에는 OZeroSecurityConfig에 저장된 공개 키로 서명을 검증합니다. 서명이 일치하지 않으면 — 즉 매니페스트 또는 바이너리가 변조된 경우 — 게임은 이를 변조로 간주하고 Response Settings에 따라 대응합니다.

키 쌍 생성하기

1. Unity 에디터에서 Project 창의 OZeroSecurityConfig를 선택합니다.
2. 인스펙터에서 Build Integrity 섹션을 펼칩니다.
3. Require Manifest Signature 체크박스를 활성화합니다.
4. Generate Key Pair 버튼을 클릭합니다.
5. OZero가 public-key signature 키 쌍을 생성합니다. 공개 키는 OZeroSecurityConfig에 직접 기록됩니다(Assets에 저장). 개인 키는 다음 경로에 저장됩니다:
   [ProjectRoot]/OZeroSigningKeys/manifest_private_key.pem
6. 개인 키 위치를 보여주는 확인 대화상자가 나타납니다. OK를 클릭하여 닫습니다.

⚠ 중요 — 개인 키 보안

• 개인 키 파일은 Unity가 빌드에 포함시키지 않도록 Assets/ 폴더 외부에 저장됩니다. 절대로 Assets/ 안으로 이동하지 마세요.
• OZeroSigningKeys/를 즉시 .gitignore에 추가하세요. 개인 키를 버전 관리에 커밋하는 것은 심각한 보안 위험입니다.
• 개인 키를 안전한 오프라인 장소(암호화된 USB 드라이브, 패스워드 매니저 등)에 백업하세요. 이 파일을 가진 사람은 누구든 유효한 매니페스트를 위조할 수 있습니다.
• 개인 키를 분실한 경우 새 키 쌍을 생성해야 합니다. 새 공개 키는 다음 빌드에 자동으로 포함됩니다. 기존에 출시된 빌드는 모두 새 공개 키로 매니페스트 검증에 실패하므로 업데이트를 배포해야 합니다.

사용자 지정 개인 키 경로 (CI/CD & 팀 환경)

인스펙터의 Manifest Signing — Editor Only 아래에 있는 Manifest Signing Private Key Path 필드에서 개인 키의 대체 위치를 지정할 수 있습니다. 다음 두 가지 상황에서 유용합니다:

• CI/CD 파이프라인 — 개인 키를 CI 시크릿으로 저장하고 빌드 시에 경로를 주입하면 빌드 머신이 키를 영구적으로 디스크에 보관하지 않아도 됩니다.
• 팀 환경 — 키를 공유 보안 서버나 시크릿 매니저에 보관하고 필드를 마운트 경로로 지정합니다. 릴리스 빌드를 실행하는 팀원만 접근 권한을 가지면 됩니다.

기존 키 쌍 유효성 검사

디스크의 개인 키와 OZeroSecurityConfig에 저장된 공개 키가 일치하는지 확인하려면 Validate Key Pair 버튼을 클릭하세요. OZero가 개인 키로 소규모 테스트 페이로드에 서명하고 공개 키로 검증합니다. 일치하면 성공 메시지가 표시되고, 일치하지 않으면 새 쌍을 생성해야 합니다.

키 쌍을 재생성해야 하는 경우

• 개인 키를 분실하거나 유출된 경우.
• Validate Key Pair에서 불일치를 보고하는 경우(키가 동기화되지 않음).
• 예정된 보안 정책의 일환으로 의도적으로 키를 교체하는 경우.

재생성 후에는 새 공개 키가 다음 빌드에 자동으로 포함됩니다. 기존에 출시된 빌드는 새 공개 키로 매니페스트 검증에 실패하므로 업데이트를 배포해야 합니다.

듀얼 핑거프린트 무중단 키 회전

Generate Key Pair 버튼은 공개 키를 두 곳에 동시에 저장합니다 — OZeroSecurityConfig (Assets 안의 ScriptableObject) 와 Assets/OZeroSDK/Scripts/Security/BuildIntegirity/OZeroManifestTrustAnchor.cs 안의 SHA-256 fingerprint 상수. 런타임에 SDK 는 RSA 서명 검증 전에 먼저 에셋의 공개 키가 어셈블리에 박힌 fingerprint 와 일치하는지 확인합니다. 일치하지 않으면 매니페스트 자체를 거부합니다. 이 핀닝이 "공격자가 에셋과 .sig 를 동시에 자기 키로 갈아끼우는 리패킹 공격"을 차단하는 핵심입니다.

두 fingerprint 슬롯

OZeroManifestTrustAnchor.cs 안에는 두 const 슬롯이 있습니다 — ExpectedPublicKeyFingerprintHex (현재 프로덕션 fingerprint) 와 PreviousPublicKeyFingerprintHex (회전 시에만 채우는 직전 fingerprint, 평소엔 비어 있음). Matches() 검증 함수는 실제 SPKI 해시가 둘 중 하나와 일치하면 true 를 반환하며, constant-time XOR 비교로 타이밍 공격을 차단합니다. 이 듀얼 슬롯 모델이 홈페이지에서 광고하는 "무중단 키 회전" 의 실체입니다 — 새 빌드가 새 키 (Expected) 와 옛 키 (Previous) 를 동시에 신뢰하므로 grace 기간 동안 옛 빌드는 옛 매니페스트를 그대로 검증할 수 있고, 그 사이 새 릴리스를 푸시할 수 있어요.

회전 절차 (수동이지만 5분이면 충분)

1. 현재 fingerprint 메모. Assets/OZeroSDK/Scripts/Security/BuildIntegirity/OZeroManifestTrustAnchor.cs 를 열어 ExpectedPublicKeyFingerprintHex 의 현재 값을 클립보드 (또는 임시 메모) 에 복사합니다.
2. Previous 슬롯에 옮겨 붙이기. 같은 파일에서 PreviousPublicKeyFingerprintHex (보통 "") 자리에 1단계에서 복사한 값을 붙여 넣고 저장합니다.
3. 새 키 쌍 생성. OZeroSecurityConfig 인스펙터에서 Generate Key Pair 클릭. "기존 매니페스트가 무효화됩니다" 경고에 Regenerate 선택. 새 private key 가 PEM 에 쓰이고, 새 public key 가 에셋에 갱신되고, 새 fingerprint 가 ExpectedPublicKeyFingerprintHex 에 자동 주입됩니다. 2단계에서 채워둔 PreviousPublicKeyFingerprintHex 는 그대로 유지됩니다.
4. 새 SDK 릴리스 빌드 + 출시. 평소 패치 / 스토어 채널로 푸시. 이 빌드의 새 매니페스트는 새 private key 로 서명됩니다.
5. Fleet 롤오버 대기. Grace 기간 동안 새 빌드는 두 kid 모두 신뢰, 옛 빌드는 (옛 fingerprint 만 Expected 로 박혀 있는 채로) 자신의 옛 매니페스트를 그대로 검증. 어느 쪽도 깨지지 않음. 라이브 게임 기준 보통 1 ~ 4 주.
6. Previous 슬롯 비우기. 텔레메트리에서 옛 빌드 점유율 0% 확인 후 PreviousPublicKeyFingerprintHex = "" 로 되돌리고 한 번 더 SDK 릴리스. 회전 완료.

왜 "강제 업데이트가 필요 없는가"

옛 빌드 바이너리는 옛 키로 서명된 옛 매니페스트와, Expected 슬롯에 박힌 옛 fingerprint 를 이미 함께 들고 있습니다. 새 키에 대해 아무것도 몰라도 자기 매니페스트를 자기 키로 검증하므로 그대로 동작합니다. 새 빌드의 Previous 슬롯이 필요한 이유는 단 하나 — 플레이어가 회전 도중 강제 재설치하거나 옛 버전으로 롤백했을 때, 캐시된 옛 매니페스트가 새 빌드의 트러스트 앵커로도 여전히 검증되어야 하기 때문입니다. Fleet 에서 옛 빌드가 사라지면 다음 릴리스에서 Previous 를 비우면 됩니다.

트러블슈팅

아래 5가지 증상은 모두 같은 방어 스택에서 비롯됩니다 — 빌드 타임 PreBuild 검증 (OZeroBuildPreflightValidator), 부트 타임 앵커 가드 (OZeroManifestTrustAnchor.ValidateConfigurationOrFail), 런타임 검증 (OZeroBuildIntegrityValidator.VerifyManifestSignature). 모든 케이스의 해결책은 세 산출물 (private key PEM, OZeroSecurityConfig 의 public key, OZeroManifestTrustAnchor 의 fingerprint) 을 다시 동기화하는 것입니다.

증상 1 — 릴리스 빌드가 실행 즉시 reason code 0x0E (TRUST_ANCHOR_MISSING) 로 종료

ExpectedPublicKeyFingerprintHex 가 빈 문자열입니다. Editor 와 Development 빌드는 경고만 띄우고 통과하지만 릴리스 빌드는 신뢰할 수 없는 매니페스트가 받아들여지기 전에 즉시 종료합니다. 해결: Editor 에서 Generate Key Pair 를 한 번 실행하면 fingerprint 가 const 에 자동 주입됩니다. const 가 채워져 있는데도 종료된다면 어셈블리 해시 blob (oz_ahash.bin) 이 오래되었을 수 있으니 클린 상태에서 재빌드하세요.

증상 2 — 빌드 시작 직전 "no manifest signing public key is configured" 로 빌드 중단

PreBuild 검증기 (callbackOrder 51) 가 OZeroSecurityConfig.Integrity.ManifestSigningPublicKey 비어 있음을 잡았습니다. 해결: 인스펙터에서 OZeroSecurityConfig 열기 → Build Integrity 펼치기 → Generate Key Pair 클릭 후 재빌드. 참고로 이 검증은 Android / iOS (OS 레벨 서명 사용) 와 IL2CPP Standalone (per-DLL 파일 자체가 없음) 에서는 자동 skip 되므로, 키 누락은 Mono Standalone 타겟만 막습니다.

증상 3 — 런타임 로그: "Manifest signing public key does NOT match the pinned trust anchor fingerprint — APK appears to have been repacked with attacker-controlled keys"

OZeroSecurityConfig 의 public key 문자열을 해싱한 값이 ExpectedPublicKeyFingerprintHex 도 PreviousPublicKeyFingerprintHex 도 일치하지 않습니다. 정상 빌드라면 수동 편집으로 두 산출물이 어긋난 경우입니다. 해결: Editor 에서 Tools → OZero → Validate Manifest Signing Keys 실행 — 키 쌍이 일관되면 도구가 const 를 자동으로 다시 써 줍니다. 불일치를 보고하면 Generate Key Pair 로 새 쌍을 발급. 변조된 바이너리에서 이 메시지가 뜨는 것은 의도된 fail-closed 신호 — APK / .exe 가 리패킹됐는지 점검해야 합니다.

증상 4 — 회전 후 옛 빌드 사용자가 매니페스트 검증에 실패

회전 절차의 2단계를 빠뜨렸습니다. 새 SDK 릴리스가 PreviousPublicKeyFingerprintHex = "" 인 상태로 출시되어, 옛 빌드를 캐시한 채 강제 재시작한 플레이어 (또는 강제 재설치로 옛 매니페스트가 새로 fetch 된 플레이어) 가 자기 트러스트 앵커로 매니페스트를 검증하지 못합니다. 해결: PreviousPublicKeyFingerprintHex 에 옛 fingerprint 를 채운 핫픽스 SDK 릴리스를 즉시 배포 — 이후 매니페스트 fetch 가 두 kid 중 하나로 검증됩니다.

증상 5 — 로컬 빌드는 성공하지만 CI 빌드가 "private key not found" 또는 잘못된 키로 서명

CI 머신에는 .gitignore 로 정상 차단된 OZeroSigningKeys/manifest_private_key.pem 이 없습니다. 해결: PEM 을 CI secret (GitHub Actions Secret, GitLab Variable, Jenkins Credentials 등) 에 보관하고, Unity 빌드 단계 직전에 파이프라인이 OZeroSigningKeys/manifest_private_key.pem 으로 복원하도록 구성하세요. 또는 OZeroSecurityConfig 의 Manifest Signing Private Key Path 를 CI 러너가 mount 가능한 경로 (예: secrets manager mount) 로 지정. 모든 CI 러너가 같은 PEM 을 써야 합니다 — public key 는 같아도 PEM 이 다르면 서명이 달라집니다.

설치 출처 설정

게임이 승인된 스토어 또는 경로에서 설치된 경우에만 실행되도록 제한합니다. 사이드로드 또는 재패키징된 APK 방지에 유용합니다.

Steam Anti-Piracy 설정

Steam으로 배포되는 PC 빌드에서 Steam 실행 경로, App ID, 권한 상태, 릴리스 설정을 확인합니다. Standard는 로컬 검증이며, Steam 서버를 통한 더 강한 소유권 검증은 Pro의 서버 Steam Attestation에서 제공합니다.

디바이스 바인딩 설정

하드웨어 지문을 사용해 게임 계정을 최초 기기에 바인딩합니다. 다른 하드웨어로의 계정 이전을 감지합니다.

상용 운영 목적

기기 바인딩은 Pro 운영 레이어로 가장 유용합니다. 라이선스를 서버에 등록된 하드웨어 지문과 연결해 위험 기기를 격리하고, 단순 라이선스 공유 비용을 높이며, 정상적인 기기 변경을 전체 라이선스 차단 없이 지원할 수 있습니다.

Reset Token 고객지원 흐름

1. 일반 고객지원 절차에 따라 플레이어 계정과 리셋 사유를 확인합니다.
2. Customer Portal → Device Binding에서 대상 기기를 찾고 Reset Token을 발급합니다.
3. 토큰은 인증된 고객지원 채널로만 전달합니다. 장기간 남는 공개 채팅이나 스크린샷에 보관하지 마세요.
4. 게임 또는 고객지원 UI는 토큰을 OZeroDeviceBindingDetector.Instance?.ClearStoredFingerprint(token.Trim())에 전달해야 합니다.
5. SDK가 토큰을 소비한 뒤 앱을 재시작하거나 보호 초기화 흐름에 다시 진입하면 현재 하드웨어 지문이 다시 등록됩니다.

스피드핵 감지기 설정

Unity Time.realtimeSinceStartup를 네이티브 플랫폼 타이머 및 선택적으로 신뢰할 수 있는 웹 시간 소스와 비교하여 타임 스케일 조작(스피드핵)을 감지합니다.

Physics Hack Detector

Injection Detector 설정

어셈블리 인젝션, DLL 하이재킹, IL2CPP 패칭 등 무단 코드 인젝션을 감지합니다.

PlayerPrefs 암호화

Unity의 PlayerPrefs에 저장되는 데이터(설정, 사용자 환경설정 등)를 보호하려면 PlayerPrefs를 OZeroSafePlayerPrefs로 교체하세요. API는 동일합니다.

using OZeroSDK.Security;

// Save a value
OZeroSafePlayerPrefs.SetInt("score", 4200);
OZeroSafePlayerPrefs.SetFloat("volume", 0.8f);
OZeroSafePlayerPrefs.SetString("username", "Hero");

// Read a value
int    score    = OZeroSafePlayerPrefs.GetInt("score", 0);
float  volume   = OZeroSafePlayerPrefs.GetFloat("volume", 1.0f);
string username = OZeroSafePlayerPrefs.GetString("username", "");

세이브 파일 암호화

세이브 파일을 암호화하려면 File.ReadAllText / File.WriteAllText 대신 OZeroSV_File을 사용하세요. 파일은 쓸 때 자동으로 암호화되고 읽을 때 복호화됩니다. 로드 시 변조 여부도 검사합니다.

using OZeroSDK.Security;

string path = Application.persistentDataPath + "/save.json";

// Write encrypted file
OZeroSV_File.WriteAllText(path, jsonString);

// Read and decrypt file
string json = OZeroSV_File.ReadAllText(path);

4 인게임 변수 보호 (Secure Types)

Secure Types는 일반 C# 변수 타입을 암호화된 타입으로 대체합니다. 값이 Native C++ 힙에 저장되어 Cheat Engine 같은 도구로는 메모리를 스캔해도 찾을 수 없습니다. 타입 이름만 바꾸면 되고 나머지 코드는 그대로 동작합니다.

지원 타입

예시 코드

// ── Before: plain C# variable ──────────────────────────────
using UnityEngine;

public class PlayerStats : MonoBehaviour
{
    public int   gold  = 0;
    public float speed = 5.0f;
    public int   hp    = 100;
}

// ── After: OZero Secure Types (only the type name changes) ──
using UnityEngine;
using OZeroSDK.Security;

public class PlayerStats : MonoBehaviour
{
    public OZeroSV_Int   gold  = 0;
    public OZeroSV_Float speed = 5.0f;
    public OZeroSV_Int   hp    = 100;

    // All arithmetic works exactly as before — no code changes needed
    void TakeDamage(int dmg) => hp -= dmg;
    void AddGold(int amount) => gold += amount;
}

7 보안 이벤트 처리 (선택)

기본적으로 OZero는 위협을 감지하면 설정된 대응 정책에 따라 앱을 종료하거나 로그만 남깁니다. 직접 경고 화면을 표시하거나, 자체 서버 로그를 보내거나, 종료 직전 저장 처리를 해야 한다면 콜백을 등록할 수 있습니다. 콜백은 OZeroSecurityEvent를 통해 변조 타입, abort code, 메시지 키, 상세 메시지, 종료 예정 여부를 함께 전달합니다.

using UnityEngine;
using OZeroSDK.Security;

public class SecurityHandler : MonoBehaviour
{
    void OnEnable()
    {
        // RegisterUserCallback runs on the user chain only.
        // The built-in default handler runs independently and cannot be silenced.
        OZeroSecurityManager.Instance.RegisterUserCallback(OnThreatDetected);
    }

    void OnDisable()
    {
        OZeroSecurityManager.Instance.UnregisterUserCallback(OnThreatDetected);
    }

    void OnThreatDetected(OZeroSecurityEvent evt)
    {
        // evt contains Type, AbortCode, AbortCodeHex, MessageKey, Message, and WillAbort.
        Debug.LogWarning(
            $"OZero threat: {evt.Type} {evt.AbortCodeHex} {evt.Message}");

        switch (evt.Type)
        {
            case ModulationType.SpeedHack:
                // e.g. kick the player, show warning, report to server
                break;

            case ModulationType.BuildIntegrity:
                // evt.WillAbort is usually true for fatal build integrity violations.
                break;

            case ModulationType.Injection:
                break;
        }

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

OZeroSecurityEvent, ModulationType, OZeroAbortCode의 전체 목록은 API 레퍼런스에 문서화되어 있습니다.

다음 단계

이제 OZero의 핵심 보호 기능이 실행 중입니다. API 레퍼런스에서 모든 클래스, 메서드, 설정 옵션을 자세히 확인해 보세요.