시작하기

개요

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

1 패키지 임포트

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

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

2 대시보드 열기

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

Config Dashboard가 열리면 이 화면에서 프리셋, 보안 모듈, 라이선스, 빌드 무결성 설정을 한 번에 관리할 수 있습니다. Project 창에서 파일을 직접 찾아 수정할 필요는 없습니다.

Unity 에디터 메뉴 설명

OZeroSecurity는 설정 창은 Window > OZero Security, 진단 및 bake 명령은 Tools > OZero Security 아래에 제공합니다. 보안 프리셋은 Config & Dashboard에서 적용하도록 설계되어 있어, 저장 전에 변경될 설정을 확인할 수 있습니다.

3 모듈 활성화

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

보안 프리셋 선택

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

대시보드에서 사용할 모듈을 켜고 OZeroSecurityConfig 에셋을 저장하면 됩니다. 플레이어가 시작될 때 SDK가 활성화된 모듈을 자동으로 준비합니다.

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

OZero Security는 Standard, Plus, Pro 세 가지 티어로 제공됩니다. Standard는 서버 연동 없이 로컬 보호 기능을 사용합니다. Plus는 프로젝트별 Native Variant 패키지와 매니페스트 / Bundle ID 바인딩을 추가합니다. Pro는 Plus 구성을 포함하고 텔레메트리, 서명된 서버 시간, 원격 정책, 서버 검증, 기기 한도 같은 운영 기능을 제공합니다.

Plus / Pro 라이선스 키 등록

Standard는 별도 라이선스 설정 없이 바로 사용할 수 있습니다. Plus 또는 Pro를 사용하는 경우에는 Unity에서 OZeroLicenseConfig 에셋을 만들고 발급받은 라이선스 키를 입력하세요. Plus 키는 포털에서 프로젝트 전용 Native Variant 패키지를 내려받고, 빌드할 때 그 패키지가 현재 프로젝트와 맞는지 확인하는 데 사용됩니다. Pro 키는 여기에 더해 앱 실행 중 서버 활성화와 Pro 전용 서버 기능에도 사용됩니다.

1. 설정 에셋 생성

Unity 상단 메뉴에서 Window → OZero Security → Config & Dashboard를 엽니다. License & Server 섹션에서 Create OZeroLicenseConfig 버튼을 클릭하세요. 이 버튼을 사용하면 OZeroLicenseConfig 에셋이 올바른 Resources/ 폴더에 자동으로 생성됩니다. 직접 폴더를 만들거나 에셋을 옮길 필요가 없습니다.

2. Inspector 필드 채우기

3. 빌드 & 검증

별도 코드를 추가할 필요는 없습니다. 앱이 시작되면 SDK가 OZeroLicenseConfig 에셋을 자동으로 읽습니다. 첫 실행 후 Player 로그에서 [OZeroLicense] activated; tier=pro caps=5 같은 줄을 확인하세요. Pro로 설정했는데 Standard 모드로 실행된다는 로그가 보이면 에셋 위치와 이름을 먼저 확인하세요. 에셋은 Resources/ 폴더 아래에 있어야 하고, 이름은 정확히 OZeroLicenseConfig여야 합니다.

서버 활성화 흐름

Pro 라이선스는 앱이 시작될 때 SDK가 자동으로 확인합니다. 이 과정은 게임 시작 흐름을 강제로 막지 않도록 설계되어 있습니다. 서버 응답이 늦거나 네트워크가 잠시 끊긴 경우에는 먼저 저장된 활성화 정보를 확인하고, 사용할 수 있는 정보가 있으면 그 상태로 계속 실행합니다.

부팅 시퀀스

1. SDK는 앱 시작 시 라이선스 런타임을 자동으로 초기화합니다.
2. Standard와 Plus는 런타임 서버 활성화가 필요 없으므로 바로 로컬 보호 기능을 실행합니다.
3. 선택형 Pro 서버 기능을 구성한 경우 백그라운드에서 /v1/activate 요청을 보내 현재 라이선스와 기기 상태를 확인합니다.
4. 활성화에 성공하면 텔레메트리, 서명된 서버 시간(signed time), 빌드 검증(attestation) 같은 Pro 서버 기능을 사용할 수 있습니다.
5. 서버 점검, 일시적인 네트워크 오류, 타임아웃이 발생하면 SDK는 가능한 경우 저장된 활성화 정보를 사용합니다. 저장된 정보도 사용할 수 없거나 라이선스가 만료/정지/폐기된 경우에는 선택한 Pro 서버 기능만 사용 불가 또는 제한 상태가 됩니다. 이미 취득한 Native Variant와 로컬 보호는 그대로 유지됩니다.

전송되는 정보

활성화 요청은 작은 JSON POST입니다. 기본 요청에는 licenseKey, deviceId, sdkVersion, platform이 포함됩니다. Unity에서 값을 제공할 수 있는 경우 appIdentifier, companyName, productName, webglOrigin도 함께 전송됩니다. deviceId는 기본적으로 Unity 기기 식별자를 사용하지만, 필요하면 OZeroLicenseRuntime.DeviceIdProvider로 게임 계정 ID나 자체 UUID 방식으로 바꿀 수 있습니다.

POST https://api.ozerosecurity.com/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>"
}

서버는 서명된 토큰, 결정된 티어, 사용할 수 있는 기능 목록, 서버 기능 사용 여부, 토큰 만료 시각, 서버 연결 실패 시 정책을 반환합니다. SDK는 설정된 공개키로 서명된 토큰을 검증한 뒤에만 Pro 기능을 신뢰합니다.

서버 기능을 사용할 수 없을 때

서버 점검, 네트워크 타임아웃, 라이선스 만료/정지/폐기, Bundle ID 불일치는 곧바로 해킹으로 판단하지 않습니다. 이 경우 선택한 Pro 서버 기능만 사용 불가 또는 제한 상태가 되며, 이미 취득한 Native Variant와 로컬 보호는 그대로 유지됩니다. 반대로 빌드 불일치, 차단된 빌드, 인젝션, 디버거처럼 변조가 명확한 상황은 설정된 대응 정책을 따릅니다.

오프라인 동작

먼저 결론부터 보면, 네트워크가 끊겨도 게임과 로컬 보호는 멈추지 않습니다. Standard는 원래 서버를 쓰지 않고, Pro도 같은 오프라인 로컬 보호를 유지합니다. 명시적으로 선택한 서버 기능만 일정 기간 저장된 활성화 정보를 사용할 수 있습니다.

Standard — 인터넷 없이 바로 실행

Standard는 서버에 묻는 과정이 없습니다. 앱 안에 포함된 로컬 보호 모듈만 실행하므로, 플레이어가 오프라인이어도 게임은 시작됩니다. 텔레메트리, signed time처럼 Pro 서버가 필요한 기능만 사용되지 않습니다.

Pro — 로컬 보호는 오프라인 유지, 선택한 서버 기능은 캐시 사용

선택형 Pro 서버 기능을 켠 경우 온라인에서 /v1/activate를 통해 기기와 라이선스를 확인합니다. SDK는 결과를 암호화해 PlayerPrefs에 저장하여 해당 서버 기능이 일시적인 연결 끊김을 견디도록 합니다. 이 활성화는 이미 취득한 Native Variant의 빌드나 로컬 보호를 제한하지 않습니다.

tokenTtlSeconds는 저장된 서버 기능 결과의 유효 기간이며 기본값은 604800초, 즉 7일입니다. 오프라인에서 만료되면 텔레메트리 전송과 signed-time 검증 같은 서버 의존 기능만 다음 활성화 성공까지 사용할 수 없습니다. 게임, 취득한 Native Variant 및 로컬 디텍터는 그대로 유지되며, SDK가 제품 등급을 Standard로 조용히 전환하지 않습니다.

Pro — 포털에서 차단한 빌드는 오프라인에서도 막기

서버가 잠시 안 된다고 해서 기본 보호로 계속 실행하는 것과, 운영자가 포털에서 차단한 빌드를 허용하는 것은 다른 문제입니다. Pro 활성화가 성공할 때 서버는 현재 차단 목록(빌드 해시, SDK 버전, 앱 버전)을 서명해서 함께 내려줍니다. SDK는 이 차단 목록을 활성화 정보와 별도로 저장합니다.

권장값인 ApplyCachedBlockPolicies를 쓰면, 저장된 차단 목록이 아직 유효한 동안에는 플레이어가 비행기 모드로 실행해도 차단된 빌드는 Build Integrity에서 거부됩니다. 포털에서 차단 규칙을 새로 바꾼 경우에는 각 기기가 한 번 온라인으로 활성화되어야 새 규칙을 받아옵니다.

트러블슈팅

문제가 생기면 먼저 Unity Player 로그에서 [OZeroLicense]를 검색하세요. 이 로그는 SDK가 Standard로 시작했는지, Pro 활성화가 성공했는지, 실패했다면 왜 Standard로 내려갔는지를 알려줍니다. 보안 이벤트 전송 문제는 [OZeroTelemetry]도 함께 검색하세요.

프로젝트 설정

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

최소 빌드 타겟

릴리스 빌드 시 보안 및 용량 최적화 설정 안내

앱을 최종 출시(릴리스)할 때는 보안을 강화하고 빌드 용량을 줄이기 위해 다음 설정을 권장합니다.

보안 강화 (IL2CPP 설정): Android, iOS 등 Unity가 지원하는 환경에서는 빌드 방식을 IL2CPP로 선택하세요. IL2CPP는 역분석을 완전히 막지는 않지만, C# 코드와 메타데이터가 그대로 노출되는 범위를 줄이고 OZero 보안 검사가 더 단단한 릴리스 환경에서 동작하도록 도와줍니다. 경로: Project Settings > Player > Other Settings > Scripting Backend

용량 최적화 (Managed Stripping 설정): 사용하지 않는 managed code를 제거해 앱 용량을 줄이는 기능입니다. 처음부터 너무 강하게 제거하면 앱이 정상 실행되지 않을 수 있으므로 Low 또는 Medium 단계부터 시작하세요.

주의사항: 설정을 바꾼 뒤에는 화면 전환, 데이터 저장, Addressables, 결제/광고 같은 외부 SDK가 모두 잘 작동하는지 실제 기기에서 테스트한 다음 최적화 단계를 높이세요.

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로 접근합니다.

공통 설정

모든 보안 모듈에 공통으로 적용되는 최상위 설정입니다. 이 표의 기본값은 코드에 정의된 직렬화 기본값을 기준으로 합니다.

검증용 UI 관리

Pro Only 기능입니다. Build Integrity와 Steam DRM 등에서 온라인 재검증, 네트워크 재시도, 차단/종료 안내 팝업을 관리하도록 설정합니다. optional OZero TMP dialog package를 가져오기 전에 Package Manager에서 Unity UI와 TextMeshPro를 설치하세요. Unity 6에서는 TextMeshPro가 Unity UI 2.x에 포함됩니다. TextMeshPro를 쓰지 않는 프로젝트는 Custom UI / Callback Only를 사용하세요.

Global Threat Response

보안 위협이 확인되었을 때 게임이 어떻게 반응할지 정합니다. 테스트 중에는 콜백과 로그를 먼저 확인하고, 실제 배포 빌드에서는 플레이어에게 안내할 시간과 종료 정책을 프로젝트 운영 방식에 맞춰 선택하세요.

연동 문제 자가진단 가이드

OZero Security를 켠 뒤 앱이 종료되거나 특정 환경에서만 문제가 생긴다면, 먼저 로컬 진단 파일로 어느 모듈이 반응했는지 확인하세요. 원인을 추측하기보다 진단 파일의 module, subCode, reason 값을 기준으로 아래 표를 따라가면 됩니다.

앱이 계속 종료될 때 먼저 할 일

진단 파일에서 자주 보는 항목

자주 보이는 증상과 첫 확인 사항

빌드 무결성 검증기 설정

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

RSA 서명 키 생성 (Build Integrity Manifest)

Build Integrity는 빌드할 때 생성되는 manifest에 RSA 서명을 추가할 수 있습니다. 이 manifest에는 런타임에 검증할 assembly hash와 파일 무결성 정보가 들어 있습니다. 릴리스 빌드에서는 manifest 자체가 바뀌면 검증 기준을 믿을 수 없으므로, 배포 전에 Window > OZero Security > Config & Dashboard에서 Generate Key Pair를 실행해 manifest 서명 키 쌍을 생성하세요.

Manifest 서명이 필요한 이유

빌드 시점에 OZero는 개인 키로 manifest에 서명합니다. 플레이어 빌드에는 개인 키가 포함되지 않고, OZeroSecurityConfig에 저장된 공개 키만 포함됩니다. 런타임에는 SDK가 공개 키로 manifest 서명을 확인합니다. 서명이 맞으면 “빌드 때 만든 manifest가 그대로 유지되었다”고 보고, 그 manifest를 기준으로 assembly/file hash 검사를 진행합니다. 서명이 없거나 맞지 않으면 manifest가 교체되었거나 수정되었을 가능성이 있으므로 Build Integrity 실패로 처리합니다. 이후 동작은 Response Settings 설정에 따라 로그, 콜백, 앱 종료 등으로 이어집니다.

키 쌍 생성하기

1. Unity 에디터에서 Window > OZero Security > Config & Dashboard를 엽니다.
2. 인스펙터에서 Build Integrity 섹션을 펼칩니다.
3. Require Manifest Signature 체크박스를 활성화합니다.
4. Generate Key Pair 버튼을 클릭합니다.
5. OZero가 Build Integrity manifest signing용 키 쌍을 생성합니다. 공개 키는 OZeroSecurityConfig에 저장되고, 개인 키는 기본적으로 다음 경로에 저장됩니다:
   [ProjectRoot]/OZeroSigningKeys/manifest_private_key.pem
6. 개인 키 위치를 보여주는 확인 대화상자가 나타납니다. OK를 클릭하여 닫습니다.

중요 — 개인 키 보안

• 개인 키 파일은 Unity가 빌드에 포함시키지 않도록 Assets/ 폴더 외부에 저장됩니다. 절대로 Assets/ 안으로 이동하지 마세요.
• OZeroSigningKeys/는 버전 관리에서 제외하세요. Git을 사용한다면 .gitignore에, SVN을 사용한다면 svn:ignore에 추가합니다. 개인 키를 저장소에 커밋하는 것은 심각한 보안 위험입니다.
• 개인 키는 안전한 장소에 백업하세요. 이 파일을 가진 사람은 해당 프로젝트의 유효한 Build Integrity manifest를 만들 수 있습니다.
• 개인 키를 분실한 경우 기존에 출시된 빌드는 그대로 동작합니다. 다만 다음 업데이트 빌드에서는 기존 키로 새 manifest를 서명할 수 없으므로 새 키 쌍을 생성해야 합니다. 새 키를 만들었다면 integrity manifest를 다시 생성하고 clean build로 배포하세요. 공개 키, fingerprint, manifest, signature가 서로 맞지 않으면 Build Integrity 검증이 실패할 수 있습니다.

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

Manifest Signing Private Key Path 필드는 Generate Key Pair가 새 키를 생성할 위치를 고르는 옵션이 아닙니다. 빌드와 검증 도구가 읽을 PEM 개인 키 위치를 지정하는 옵션입니다. Generate Key Pair는 프로젝트 기본 경로에 키를 만들고 그 경로를 Config에 기록합니다. CI/CD나 팀 빌드에서는 같은 PEM을 안전한 위치에 복원한 뒤 이 필드가 그 경로를 가리키게 하세요.

• CI/CD 파이프라인 — PEM을 CI Secret에 보관하고 Unity 빌드 직전에 복원합니다. 빌드 러너가 개인 키를 디스크에 상시 보관할 필요는 없습니다.
• 팀 환경 — 릴리스 빌드 담당자나 빌드 러너만 접근할 수 있는 보안 마운트 경로 또는 시크릿 매니저를 사용합니다. 모든 릴리스 빌드 머신은 같은 PEM을 사용해야 합니다.

기존 키 쌍 유효성 검사

디스크의 개인 키와 OZeroSecurityConfig에 저장된 공개 키가 일치하는지 확인하려면 Validate Key Pair를 클릭하세요. OZero가 PEM에서 공개 키를 다시 계산해 Config의 공개 키와 비교합니다. 일치하지 않으면 맞는 개인 키를 복원하거나 새 키 쌍을 생성한 뒤 clean build를 만들어야 합니다.

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

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

재생성 후에도 기존에 출시된 빌드는 자기 빌드에 포함된 키와 manifest로 그대로 동작합니다. 다음 업데이트 빌드에서는 새 공개 키, fingerprint, manifest, signature가 한 세트로 맞아야 하므로 integrity manifest를 다시 생성하고 clean build로 배포하세요.

듀얼 핑거프린트 키 회전

Generate Key Pair 버튼을 누르면 공개 키가 OZeroSecurityConfig에 저장되고, 같은 키를 식별하는 fingerprint가 Assets/OZeroSDK/Scripts/Security/BuildIntegrity/OZeroManifestTrustAnchor.cs에도 기록됩니다. 런타임에는 먼저 asset의 공개 키가 신뢰된 fingerprint와 맞는지 확인한 뒤, 서명된 manifest를 받아들입니다.

현재 키와 이전 키

ExpectedPublicKeyFingerprintHex는 현재 빌드에서 사용할 키의 fingerprint이고, PreviousPublicKeyFingerprintHex는 키 회전 기간에만 쓰는 보조 슬롯입니다. 이 기능은 manifest 재생성을 대신하지 않으며, 서버에서 키를 자동 관리하는 기능도 아닙니다. OZeroSecurityConfig의 공개 키, fingerprint, manifest, signature는 여전히 같은 키 기준으로 한 세트를 이뤄야 합니다.

안전한 키 회전 절차

1. 현재 fingerprint를 백업합니다. Assets/OZeroSDK/Scripts/Security/BuildIntegrity/OZeroManifestTrustAnchor.cs를 열어 ExpectedPublicKeyFingerprintHex 값을 임시 메모에 복사해 둡니다.
2. 이전 키 슬롯에 등록합니다. 같은 파일의 PreviousPublicKeyFingerprintHex에 1단계에서 복사한 값을 붙여 넣고 저장합니다.
3. 새 키 쌍을 생성합니다. Window > OZero Security > Config & Dashboard를 열고 Build Integrity 섹션에서 Generate Key Pair를 클릭합니다. 새 공개 키와 Expected fingerprint가 자동으로 갱신됩니다. 2단계에서 넣은 Previous 값은 유지하세요.
4. integrity manifest를 다시 생성하고 clean build를 만듭니다. 새 manifest와 signature는 새 개인 키 기준으로 생성되어야 합니다.
5. 업데이트 전환 기간을 둡니다. 기존 출시 빌드는 자기 빌드에 포함된 키와 manifest로 계속 동작합니다. Previous 슬롯은 새 빌드 배포 중 롤백이나 산출물 혼재 상황을 줄이기 위한 안전장치입니다. 라이브 게임에서는 보통 1~4주 정도를 기준으로 잡습니다.
6. 이전 키 슬롯을 비웁니다. 옛 빌드 사용량이 충분히 낮아진 뒤 PreviousPublicKeyFingerprintHex = ""로 되돌리고 한 번 더 릴리스하면 회전이 완료됩니다.

Previous 슬롯이 하는 일

이미 출시된 옛 빌드는 새 키를 몰라도 계속 동작합니다. 옛 빌드에는 당시의 공개 키, fingerprint, manifest, signature가 함께 들어 있기 때문입니다. Previous 슬롯은 새 릴리스 라인에서 통제된 키 회전 기간 동안만 사용하는 안전장치입니다. 전환 기간이 끝나면 다음 릴리스에서 비워 두는 것이 좋습니다.

트러블슈팅

문제가 생기면 먼저 간단한 순서로 확인하세요. 키가 없으면 Generate Key Pair를 실행하고, 키가 있다면 Validate Key Pair를 실행한 뒤, integrity manifest를 다시 생성하고 clean build를 만듭니다. 대부분의 문제는 개인 키 PEM, OZeroSecurityConfig의 공개 키, OZeroManifestTrustAnchor의 fingerprint, 생성된 manifest/signature 파일 중 하나가 서로 맞지 않을 때 발생합니다.

증상 1 — 릴리스 빌드가 실행 직후 종료됨

ExpectedPublicKeyFingerprintHex가 비어 있을 수 있습니다. 릴리스 빌드는 fingerprint가 없으면 안전을 위해 바로 실패합니다. 해결: Generate Key Pair를 실행하고 Unity 재컴파일이 끝난 뒤 clean build를 만드세요. 값이 이미 채워져 있다면 Validate Key Pair를 실행하고 빌드 출력 폴더를 비운 뒤 다시 빌드하세요.

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

OZeroSecurityConfig.Integrity.ManifestSigningPublicKey가 비어 있을 때 발생합니다. 해결: Window > OZero Security > Config & Dashboard를 열고 Build Integrity 섹션의 Generate Key Pair를 클릭한 뒤 다시 빌드하세요.

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

OZeroSecurityConfig의 공개 키와 OZeroManifestTrustAnchor에 기록된 fingerprint가 맞지 않을 때 발생합니다. 일부 키 파일만 복원했거나 생성 파일을 수동으로 수정했을 때 자주 보입니다. 해결: Validate Key Pair를 실행하세요. 불일치가 보고되면 맞는 PEM을 복원하거나 새 키 쌍을 생성한 뒤 integrity manifest를 다시 만들고 clean build를 생성하세요. 배포된 빌드에서만 이 메시지가 보이면 APK 또는 실행 파일이 재패키징되었는지도 확인하세요.

증상 4 — 키 회전 후 새 빌드에서 manifest 검증 실패

회전한 키 세트 중 일부가 이전 값일 가능성이 큽니다. 공개 키, fingerprint, manifest, signature가 서로 같은 키 기준인지 확인하세요. 해결: 전환 기간이 필요할 때만 이전 fingerprint를 PreviousPublicKeyFingerprintHex에 유지하고, Validate Key Pair 실행, integrity manifest 재생성, 빌드 출력 폴더 정리, clean build 순서로 다시 빌드하세요.

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

CI에는 로컬 PC의 OZeroSigningKeys/manifest_private_key.pem 파일이 자동으로 존재하지 않습니다. 해결: PEM을 CI Secret에 보관하고 Unity 빌드 직전에 기본 경로 또는 Manifest Signing Private Key Path에 지정한 경로로 복원하세요. 모든 릴리스 러너가 같은 PEM을 사용해야 하며, 릴리스 환경에서도 Validate Key Pair를 한 번 실행해 확인하는 것을 권장합니다.

설치 출처 설정

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

Steam Anti-Piracy 설정

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

디바이스 바인딩 설정

처음 신뢰한 기기의 식별 정보를 저장하고, 이후 실행 때 같은 기기인지 비교합니다. 같은 계정이나 보호된 세이브 데이터가 다른 기기로 옮겨졌는지 확인하는 데 사용합니다.

운영에서 사용하는 방식

Pro에서는 Device Binding을 운영 도구로 사용할 수 있습니다. 서버가 라이선스별 기기 지문을 기억하므로, 반복적으로 위험 신호가 나오는 기기를 차단하고, 단순 라이선스 공유를 줄이며, 정상적인 기기 변경은 전체 라이선스를 막지 않고 지원할 수 있습니다.

Reset Token 지원 절차

1. 기기 초기화가 필요한 이유와 플레이어 계정을 일반 고객지원 절차로 먼저 확인합니다.
2. Customer Portal → Device Binding에서 대상 기기를 선택하고 Reset Token을 발급합니다.
3. 토큰은 인증된 고객지원 채널로만 전달하세요. 공개 채팅, 스크린샷, 오래 남는 티켓에 남겨두지 마세요.
4. 게임 또는 지원용 UI에서 토큰을 OZeroDeviceBindingDetector.Instance?.ClearStoredFingerprint(token.Trim())에 전달합니다.
5. SDK가 토큰을 승인한 뒤 앱을 다시 시작하거나 보호 초기화 흐름을 다시 실행하면, 현재 기기 지문이 다시 등록됩니다.

Speed & Time Hack 설정

Unity 시간, 네이티브 기준 시계, 백그라운드 타이머, 웹/Pro 서버 시간을 서로 비교해 게임 속도를 빠르게 또는 느리게 바꾸는 조작과 기기 시계 변경을 감지합니다.

Time.timeScale 대신 OZeroTime.timeScale 사용

Speed & Time Hack 보호 모듈이 활성화된 상태에서는 Unity의 기본 Time.timeScale을 프로젝트 코드에서 직접 수정하면 안 됩니다. OZero를 거치지 않고 직접 수정하면, OZero 디텍터는 이를 외부 치트 툴에 의한 의심스러운 런타임 시간 조작으로 판단하고 설정된 대응 정책을 실행할 수 있습니다.

OZeroSecurityConfig.TimeScaleTamperExemptions는 코드에서 Time.timeScale을 직접 수정해야 하는 스크립트를 등록하는 예외 처리 목록입니다. 이 목록은 최소한으로 유지해야 합니다.

구조상 직접 Time.timeScale에 접근할 수밖에 없는 검증된 외부 플러그인이나 레거시 어댑터 스크립트(adapter script)에만 제한적으로 할당하세요.

이를 제외한 프로젝트 내 모든 게임 로직에서는 예외 없이 OZeroTime.timeScale을 우선 사용해야 합니다. 일시정지, 슬로우 모션, 컷신 속도 제어, 배속 플레이 등 게임 내에서 의도적으로 속도를 변경할 때는 반드시 OZeroTime.timeScale을 사용하세요.

using OZeroSDK.Security;

// Correct: the detector knows this is an intentional game-side change.
OZeroTime.timeScale = 0.5f;

// Avoid: this bypasses OZero's expected time-scale tracking.
Time.timeScale = 0.5f;

장시간 로딩 시 Watchdog 의도치 않은 종료 방지하기

OZero의 네이티브 Watchdog은 Unity 메인 스레드가 정상적으로 살아 있는지 주기적인 heartbeat로 확인합니다. 릴리스 빌드에서는 비-Android 플랫폼은 약 6초, Android는 시작 유예 이후 약 10초 동안 heartbeat가 들어오지 않으면 앱이 멈춘 것으로 판단하고 설정된 대응 정책에 따라 종료할 수 있습니다.

대형 씬 로딩, 동기식 에셋 압축 해제, 셰이더 warmup, Addressables 준비처럼 메인 스레드가 의도적으로 몇 초 이상 막히는 정상 작업에서도 이 상황이 발생할 수 있습니다.

이런 신뢰 가능한 로딩 구간은 OZeroWatchdog.BeginLoadingGrace(maxGraceMs)로 감싸세요. 로딩이 시작될 때 grace가 시작되고, scope가 dispose되거나 End()가 호출되는 순간 즉시 종료되므로 실제 로딩 시간을 미리 정확히 알 필요가 없습니다.

using OZeroSDK.Security;
using UnityEngine.SceneManagement;

public void LoadLargeScene()
{
    using (OZeroWatchdog.BeginLoadingGrace(60000))
    {
        SceneManager.LoadScene("Battle", LoadSceneMode.Single);
        // Grace ends as soon as the using scope exits.
    }
}

public void WarmUpLargeAssets()
{
    OZeroWatchdog.RunWithLoadingGrace(() =>
    {
        BuildLargeRuntimeCache();
    }, 60000);
}

Physics Hack Detector

Injection Detector 설정

예상하지 못한 네이티브 모듈 로드, 실행 가능한 private memory, inline hook, 원격 thread 방식의 주입, 위험한 외부 프로세스 handle, WebGL 런타임 변조 신호를 감지합니다.

PlayerPrefs 암호화

Unity의 PlayerPrefs에 저장하던 값 중 보호가 필요한 새 key는 OZeroSafePlayerPrefs로 저장하세요. 자주 쓰는 Get/Set, HasKey, Delete, Save 형태는 익숙한 이름으로 제공되지만, 암호화된 데이터는 기존 plain PlayerPrefs 데이터와 호환되지 않습니다.

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 같은 도구로는 메모리를 스캔해도 찾을 수 없습니다. 타입 이름만 바꾸면 되고 나머지 코드는 그대로 동작합니다.

예시 코드

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using OZeroSDK.Security;

public class PlayerStats : MonoBehaviour
{
    [SerializeField] OZeroSV_Int Gold = 5000;
    [SerializeField] OZeroSV_Float Speed = 3.5f;
    [SerializeField] OZeroSV_Int HP = 1000;
}

지원 타입

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

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

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 레퍼런스에 문서화되어 있습니다.

포털 정책 콜백

고객 포털 정책은 단계적으로 운영할 수 있습니다. Observe는 근거만 기록하고, Callback은 서버에서 발행한 정책 액션을 게임으로 전달하며, Device Block은 이후 서버 검증에서 선택한 기기를 차단합니다. 강한 기기 차단을 쓰기 전에 게임에서 경고 표시, 매치메이킹 제한, 재로그인 요청, 고객지원 안내를 직접 처리하려면 Callback을 사용하세요.

using UnityEngine;
using OZeroSDK.Security;

public class PolicyActionHandler : MonoBehaviour
{
    void OnEnable()
    {
        OZeroSecurityManager.Instance.RegisterUserPolicyActionCallback(OnPolicyAction);
    }

    void OnDisable()
    {
        OZeroSecurityManager.Instance.UnregisterUserPolicyActionCallback(OnPolicyAction);
    }

    void OnPolicyAction(OZeroPolicyActionEvent evt)
    {
        Debug.LogWarning(
            $"Policy callback: {evt.Module}, score={evt.Score}, reason={evt.Reason}");

        if (evt.Score >= 80)
        {
            // Show your own UI, limit sensitive actions, or ask the player to reconnect.
        }
    }
}

다음 단계

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