시작하기

개요

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 에디터 메뉴 설명

OZeroSDK > Security 메뉴에는 SDK 설정과 진단 명령이 모여 있습니다. 보안 프리셋은 상단 메뉴가 아니라 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는 ScriptableObject 에셋 1개를 추가하고 구매 후 받은 키를 붙여 넣습니다. Plus 키는 프로젝트별 Variant 검증과 포털 다운로드에 사용되고, Pro 키는 런타임 서버 활성화에도 사용됩니다.

1. 설정 에셋 생성

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

2. Inspector 필드 채우기

3. 빌드 & 검증

코드 변경은 필요 없습니다. 앱이 시작되면 SDK가 OZeroLicenseConfig 에셋을 자동으로 읽습니다. 첫 실행 후 Player 로그에서 [OZeroLicense] activated; tier=pro caps=5 같은 줄을 확인하세요. Pro로 설정했는데 Standard 모드로 실행된다는 로그가 보이면 에셋이 Resources/ 폴더 아래에 있고 이름이 정확히 OZeroLicenseConfig인지 확인하세요.

서버 활성화 흐름

활성화는 앱 시작 시 백그라운드에서 진행됩니다. 서버 응답이 늦거나 일시적으로 실패해도 씬 로드를 막지 않고, 저장된 활성화 정보가 있으면 그 값을 사용합니다.

부팅 시퀀스

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>"
}

서버는 서명된 토큰, 결정된 티어, 사용할 수 있는 기능 목록, 만료 시각을 JSON으로 반환합니다. SDK는 설정된 공개키로 응답 서명을 확인한 뒤에만 Pro 기능을 활성화합니다.

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

서버 점검, 네트워크 타임아웃, 라이선스 만료/정지/폐기, Bundle ID 불일치는 곧바로 해킹으로 판단하지 않습니다. 이 경우 Pro 전용 기능만 비활성화하고 기본 보호 기능은 계속 실행합니다. 반대로 빌드 불일치, 차단된 빌드, 인젝션, 디버거처럼 변조가 명확한 상황은 설정된 대응 정책을 따릅니다.

오프라인 동작

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

Standard — 항상 오프라인

Standard는 서버 활성화나 텔레메트리 전송 없이 로컬 보호 기능만 실행합니다. 네트워크가 없어도 게임은 그대로 시작되며, Pro 전용 기능만 사용되지 않습니다.

Pro — TTL 내 오프라인 가능

지정 디바이스에서 /v1/activate가 처음 성공한 후, Pro 활성화 정보는 PlayerPrefs에 저장됩니다(기기 바인딩 키로 암호화 — 아래 캐시 보안 참조). 이후 실행에서는 네트워크 호출이 시작되기 전에 저장된 활성화 정보를 읽으므로, 플레이어가 오프라인이어도 SDK는 어떤 티어이고 어떤 Pro 기능이 사용 가능한지 알 수 있습니다.

저장된 Pro 활성화 정보는 활성화 시점에 기록된 cachedAtMillis로부터 tokenTtlSeconds 동안 신뢰됩니다. 기본 7일(604800)입니다. 그동안 계속 오프라인 상태로 시간이 지나면 저장된 정보는 폐기되고, 다음 온라인 활성화가 성공할 때까지 SDK는 Standard 수준으로 동작합니다. 디텍터는 계속 동작하며, 텔레메트리 전송과 signed-time 검증만 꺼집니다.

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

서버 장애 시 기본 보호로 계속 실행되는 것과, 포털에서 명시적으로 차단한 빌드를 허용하는 것은 다릅니다. Pro 활성화가 성공하면 서버는 현재 차단 정책을 서명된 형태로 내려주고, SDK는 이를 별도로 저장합니다.

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

트러블슈팅

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

프로젝트 설정

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

최소 빌드 타겟

릴리스 빌드의 IL2CPP와 Managed Stripping

Android, iOS, standalone 릴리스 빌드에서는 Unity가 지원하는 경우 IL2CPP를 우선 사용하세요. IL2CPP가 역분석을 불가능하게 만드는 것은 아니지만, 평문 managed metadata 노출을 줄이고 OZero의 native 무결성 검사가 더 강한 릴리스 기준에서 동작하게 해 줍니다.

Project Settings > Player > Other Settings > Scripting Backend를 IL2CPP로 설정하세요. 릴리스 빌드의 Managed Stripping Level은 Low 또는 Medium부터 적용하고, 대상 기기에서 클린 실행 스모크 테스트를 진행하세요. reflection, serialization, Addressables, 서드파티 SDK 흐름을 검증하기 전에는 더 강한 stripping 단계로 바로 올리지 마세요.

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

Common Setting

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

Global Threat Response

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

빌드 무결성 검증기 설정

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

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

빌드 무결성을 활성화하고 Require Manifest Signature를 켠 경우, OZero는 공개키 기반 서명으로 무결성 매니페스트가 바뀌지 않았는지 확인합니다. 릴리스 빌드를 만들기 전에 Unity 에디터에서 키 쌍을 반드시 생성하세요.

매니페스트 서명 작동 방식

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

키 쌍 생성하기

1. Unity 에디터에서 Project 창의 OZeroSecurityConfig를 선택합니다.
2. 인스펙터에서 Build Integrity 섹션을 펼칩니다.
3. Require Manifest Signature 체크박스를 활성화합니다.
4. Generate Key Pair 버튼을 클릭합니다.
5. OZero가 서명 키 쌍을 생성합니다. 공개 키는 OZeroSecurityConfig에 저장되고, 개인 키는 다음 경로에 저장됩니다:
   [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에 저장되고, 같은 키를 식별하는 fingerprint가 OZeroManifestTrustAnchor.cs에도 기록됩니다. 런타임에는 이 두 값이 맞는지 확인한 뒤 매니페스트 서명을 검증합니다. 값이 서로 맞지 않으면 매니페스트를 신뢰하지 않습니다.

현재 키와 이전 키

OZeroManifestTrustAnchor.cs에는 현재 사용할 키 fingerprint와, 키 회전 기간에만 임시로 허용할 이전 키 fingerprint를 기록할 수 있습니다. 평소에는 현재 키만 사용하고, 새 키로 교체할 때만 이전 키 슬롯을 잠시 채워 둡니다. 이렇게 하면 새 빌드를 배포하는 동안 기존 빌드 사용자가 갑자기 매니페스트 검증에 실패하는 일을 줄일 수 있습니다.

키 회전 절차

1. 현재 fingerprint를 백업합니다. Assets/OZeroSDK/Scripts/Security/BuildIntegirity/OZeroManifestTrustAnchor.cs를 열어 ExpectedPublicKeyFingerprintHex 값을 복사해 둡니다.
2. 이전 키 슬롯에 등록합니다. 같은 파일의 PreviousPublicKeyFingerprintHex에 1단계에서 복사한 값을 붙여 넣고 저장합니다.
3. 새 키 쌍을 생성합니다. OZeroSecurityConfig 인스펙터에서 Generate Key Pair를 클릭하고 재생성 확인창에서 진행합니다. 새 공개 키와 새 fingerprint가 자동으로 갱신됩니다.
4. 새 릴리스 빌드를 배포합니다. 새 매니페스트는 새 개인 키로 서명됩니다.
5. 업데이트 전환 기간을 둡니다. 기존 빌드와 새 빌드가 함께 쓰이는 기간에는 이전 키도 허용해야 합니다. 라이브 게임에서는 보통 1~4주 정도를 기준으로 잡습니다.
6. 이전 키 슬롯을 비웁니다. 옛 빌드 사용량이 충분히 낮아진 뒤 PreviousPublicKeyFingerprintHex = ""로 되돌리고 한 번 더 릴리스하면 회전이 완료됩니다.

왜 이전 키 슬롯이 필요한가

라이브 서비스에서는 모든 사용자가 동시에 새 버전으로 이동하지 않습니다. 이전 키 슬롯을 잠시 유지하면 기존 빌드와 새 빌드가 함께 있는 동안 매니페스트 검증 실패를 줄일 수 있습니다. 충분한 전환 기간이 지난 뒤 이전 키 슬롯을 비우면 됩니다.

트러블슈팅

대부분의 키 관련 오류는 개인 키, OZeroSecurityConfig의 공개 키, OZeroManifestTrustAnchor의 fingerprint가 서로 맞지 않을 때 발생합니다. 아래 항목을 순서대로 확인하세요.

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

ExpectedPublicKeyFingerprintHex가 비어 있을 수 있습니다. 해결: Unity 에디터에서 Generate Key Pair를 한 번 실행한 뒤 클린 빌드하세요. 값이 이미 채워져 있는데도 실패한다면 이전 빌드 산출물이 남아 있을 수 있으므로 빌드 폴더를 비우고 다시 빌드하세요.

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

OZeroSecurityConfig.Integrity.ManifestSigningPublicKey가 비어 있을 때 발생합니다. 해결: 인스펙터에서 OZeroSecurityConfig를 열고 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의 공개 키와 코드에 기록된 fingerprint가 맞지 않을 때 발생합니다. 해결: Unity 에디터에서 Tools → OZero → Validate Manifest Signing Keys를 실행하세요. 도구가 불일치를 보고하면 Generate Key Pair로 새 키 쌍을 발급한 뒤 다시 빌드하세요. 배포된 빌드에서 이 메시지가 보이면 APK 또는 실행 파일이 재패키징되었는지도 확인해야 합니다.

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

새 키를 배포하기 전에 이전 fingerprint를 PreviousPublicKeyFingerprintHex에 등록하지 않았을 가능성이 큽니다. 해결: 이전 fingerprint를 Previous 슬롯에 넣은 핫픽스 빌드를 배포하고, 충분한 전환 기간이 지난 뒤 Previous 슬롯을 비우세요.

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

CI 머신에 OZeroSigningKeys/manifest_private_key.pem이 없을 때 발생합니다. 해결: 개인 키를 CI Secret에 보관하고, Unity 빌드 직전에 같은 경로로 복원하세요. 또는 OZeroSecurityConfig의 Manifest Signing Private Key Path에 CI에서 접근 가능한 보안 경로를 지정하세요. 모든 릴리스 빌드 머신은 같은 개인 키를 사용해야 합니다.

설치 출처 설정

게임이 승인된 스토어 또는 경로에서 설치된 경우에만 실행되도록 제한합니다. 사이드로드 또는 재패키징된 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를 네이티브 플랫폼 타이머 및 선택적으로 신뢰할 수 있는 웹 시간 소스와 비교하여 타임 스케일 조작(스피드핵)을 감지합니다.

Time.timeScale 대신 OZeroTime.timeScale 사용

Speed & Time Hack 모듈이 활성화된 상태에서 Time.timeScale을 직접 수정하면 외부 시간 조작과 비슷한 신호로 보일 수 있습니다. 일시정지, 슬로우 모션, 컷신 속도 제어, 빠른 진행, 디버그 속도 조절처럼 게임이 의도적으로 속도를 바꿀 때는 OZeroTime.timeScale을 사용하세요.

OZeroTime.timeScale은 요청된 값을 OZero detector로 전달해 detector의 예상 game-time scale을 갱신한 뒤 Unity time scale을 안전하게 적용합니다. 이를 통해 SDK는 정상적인 게임플레이 속도 변경과 의심스러운 런타임 변조를 구분할 수 있습니다.

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 설정

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

예시 코드

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

다음 단계

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