시작하기

개요

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

1 패키지 임포트

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

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

Welcome 창

OZero SDK 패키지를 import하면 Welcome 창(Window > OZero Security > Welcome)이 자동으로 열립니다. OZero SDK 패키지를 import할 때마다(같은 버전을 다시 import해도) 열리고, 새 SDK 버전이 처음 로드될 때도 열립니다. Built-in TMP 대화상자 패키지나 TMP 리소스를 import할 때는 열리지 않습니다.

창 위쪽에는 STEP 1 · Run Setup 큰 카드가 있습니다. Start setup을 누르면 Check Setup이 열려 프로젝트에 아직 필요한 설정을 보여 주고, Auto Setup이 변경마다 확인을 받으며 적용합니다. 그 아래에는 설정을 마친 뒤 쓰는 카드 두 장이 있습니다. Read the Manual에는 Online(OZero 웹사이트 매뉴얼)과 Offline(패키지에 포함된 HTML 매뉴얼, Assets/OZeroSecurity/Documentation/HTML/index.html) 버튼이 있으며, 포함된 매뉴얼이 없으면 Offline 버튼은 비활성화됩니다. Security Config(Open config)는 Edit > Project Settings > OZero Security를 열어, 설정을 마친 뒤 프리셋이나 개별 보호 기능을 바꿀 수 있게 합니다.

애드온이 설치된 프로젝트에서는 Online Services 행이 추가로 보입니다. Open을 누르면 Window > OZero Security > Online Services 창을 엽니다(설정이 없으면 만듭니다).

애드온이 설치되어 있으면 Offline 버튼은 애드온에 포함된 매뉴얼(Assets/OZeroSecurity/Online/Documentation/HTML/index.html)을 엽니다.

Don't show this window automatically again을 켜면 이 프로젝트에서는 더 이상 자동으로 열리지 않으며, 메뉴로는 언제든 열 수 있습니다. batch 모드이거나 OZERO_SUPPRESS_WELCOME 환경 변수가 설정돼 있으면 열리지 않으므로 CI와 자동 빌드는 멈추지 않습니다.

2 대시보드 열기

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

Config Dashboard가 열리면 이 화면에서 프리셋, 보안 모듈, 라이선스, 빌드 무결성 설정을 한 번에 관리할 수 있습니다. Project 창에서 파일을 직접 찾아 수정할 필요는 없습니다. 대시보드는 Edit > Project Settings의 OZero Security 페이지이며, 그곳에서 바로 열어도 됩니다.

Unity 에디터 메뉴 설명

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

• Window > OZero Security > Welcome: 시작 화면
• Window > OZero Security > Config & Dashboard: 보안 설정(Edit > Project Settings > OZero Security를 엽니다)
• Window > OZero Security > Check Setup: 설정 점검과 자동 설정(Auto Setup)

Check Setup과 Auto Setup

Window > OZero Security > Check Setup을 열거나 Welcome 창에서 Start setup을 누르세요. 패키지를 임포트한 직후와 출시 빌드 전에 한 번씩 실행하는 것을 권장합니다.

Check Setup은 프로젝트, 현재 빌드 대상, 보안 설정을 검사해 빌드를 막는 항목과 권장 항목을 보여 줍니다. 항목마다 Docs(설명)와 수정 버튼이 있으니, 빌드를 막는 항목부터 해결하세요.

Auto Setup을 누르면 권장 변경을 한 단계씩 보여 줍니다. 단계마다 현재 값과 바뀔 값을 확인하고 Apply 또는 Skip을 고르세요. 끝나면 적용한 항목과 건너뛴 항목, 남은 항목이 요약으로 표시됩니다. 빌드를 막는 항목과 Auto Setup이 적용할 변경이 모두 없어지면 Setup complete 상자와 Open Build Settings 버튼이 나오며, 평소처럼 빌드하면 됩니다.

Auto Setup이 바꾸는 항목: Development Build 끄기, IL2CPP 전환, Managed Stripping Low, Android API 24·ARM64, DeveloperSecret 생성, TMP 다이얼로그 패키지 임포트, manifest 서명 키 생성(Require Manifest Signature 켜기 포함), Android 디버그 SHA 등록.

서명 키 파일: Auto Setup이 만든 manifest 서명 개인 키 파일은 프로젝트와 버전 관리 밖에 두고, CI를 포함한 모든 빌드 머신에서 쓸 수 있게 하세요.

자세히: Auto Setup 단계와 동작

Check Setup(Window > OZero Security > Check Setup, 또는 Welcome 창의 Start setup)은 프로젝트, 활성 빌드 대상, 보안 설정, 플랫폼별 릴리스 설정을 점검해 차단 문제, 권장 사항, 정보를 보여 줍니다. 항목마다 Docs와 수정 버튼이 있고, 창 위쪽에 Auto Setup이 적용할 수 있는 권장 변경 수가 표시됩니다. 창 위쪽 버튼은 왼쪽부터 Auto Setup(적용할 변경 수 표시), Re-check(검사 다시 실행), Manual, Security Config입니다. Security Config는 Edit > Project Settings > OZero Security를 엽니다. 실제 플레이어 빌드 때도 빌드 검증은 그대로 실행됩니다.

OZero SDK 패키지를 import한 뒤 Check Setup을 처음 열 때, Auto Setup이 적용할 수 있는 변경이 있으면 Auto Setup을 시작할지 묻습니다(Start Auto Setup / Not now). 같은 버전을 다시 import해도 import할 때마다 다시 묻고, batch 모드에서는 묻지 않습니다. 나중에 Auto Setup 버튼으로 시작할 수도 있습니다.

Auto Setup은 먼저 적용할 단계 목록을 보여 줍니다. 프로젝트와 활성 빌드 대상에 필요한 단계만 나오며, Start(또는 Cancel)를 고릅니다. 단계마다 현재 값과 바뀔 값을 보여 준 뒤 Apply, Skip, Stop 중에서 고르게 합니다. 마지막 요약 화면에 적용한 항목, 건너뛴 항목, 아직 남은 항목이 나오며, Run Auto Setup Again으로 처음부터 다시 실행할 수 있습니다. 나올 수 있는 단계는 다음과 같습니다.

1. Development Build 끄기
2. Scripting Backend를 IL2CPP로 변경
3. IL2CPP일 때만: Managed Stripping Level을 Low로 설정
4. Android: 최소 API 레벨 24, 대상 아키텍처 ARM64
5. DeveloperSecret 생성
6. Built-in TMP 대화상자 패키지 import. 필요하면 TextMeshPro/Unity UI를 설치하고 TMP Essential Resources와 대화상자 패키지를 차례로 import합니다. 모두 끝날 때까지 Processing 화면에 진행 단계와 경과 초가 나오며, 끝나면 다음 단계로 넘어갑니다. 스크립트 리로드를 거쳐도 이어집니다.
7. 매니페스트 서명 키 쌍 생성(트러스트 앵커는 자동으로 갱신됩니다). 개인키 파일이 만들어질 위치는 단계 화면에 나옵니다. 결과 대화상자는 뜨지 않고, 개인키 위치와 지문은 콘솔 로그에 남습니다. 이미 키가 있으면 덮어쓸지 묻는 대화상자가 뜹니다. 다음 단계에서 Require Manifest Signature를 켭니다.
8. Android 디버그 SHA 추가. 결과는 콘솔 로그에 남습니다. 디버그 keystore가 없으면 만들지 묻는 대화상자가 뜹니다. Security Config나 Keystore SHA Extractor의 버튼으로 직접 실행하면 예전처럼 결과 대화상자가 뜹니다.

보안 설정의 Fail Build on Setup Warnings가 켜져 있으면(기본값) 키 생성과 Require Manifest Signature도 일반 단계입니다. 건너뛰면 경고가 남아 플레이어 빌드가 preflight에서 실패하며, 단계 화면과 요약 화면에 이 안내가 나옵니다. 이 설정이 꺼져 있을 때만 "(optional, review first)" 표시가 붙은 선택 단계가 됩니다. 키 생성 단계는 개인키 파일이 만들어질 위치를 보여 줍니다. 개인키는 프로젝트 밖에 두고 버전 관리에서 빼며, CI를 포함한 모든 빌드 머신에서 쓸 수 있게 하세요.

이 에디터에서 적용할 수 없는 단계(예: Unity 에디터에 IL2CPP 모듈이 설치돼 있지 않을 때의 IL2CPP 단계)는 단계별로 진행하지 않고, 개요와 요약 화면의 Needs your action에 따로 표시됩니다. IL2CPP 모듈이 없으면 Unity Hub > Installs > Add modules에서 해당 플랫폼의 IL2CPP 모듈을 추가한 뒤 Auto Setup을 다시 실행하세요. Player Settings 변경은 Undo로 되돌릴 수 없으며, 적용한 변경은 모두 요약 화면에 표시됩니다.

다음 두 Check Setup 오류는 OZero의 네이티브 로드 앵커를 지킵니다(클라이언트 보호의 한계). OZero native plugins are not set to Load on startup: Auto Setup이 OZero 네이티브 플러그인의 Load on startup을 다시 켭니다. 이 설정은 끄지 마세요. Android boot provider library is missing: Mono 백엔드 Android 빌드에 필요한 라이브러리입니다. OZero Security 패키지를 다시 임포트해 Assets/OZeroSecurity/Plugins/Android/OZeroSecurityBoot.androidlib를 복구하세요.

온라인 애드온이 있으면 Auto Setup이 고객만 알 수 있는 값도 입력받아 설정합니다. 이런 단계에는 입력 칸이 나오며, 값을 입력하고 Apply를 누르면 됩니다. 값은 저장하기 전에 확인하며 Console이나 로그에 남기지 않습니다. 확인에 실패하면 단계에 이유가 표시되고 아무것도 저장하지 않으니, 값을 고쳐 다시 입력하거나 Skip을 누르세요.

• License Key: Pro license key is empty, Native Variant <NNNN> needs your license key, … is bound to a different license key 항목에 나옵니다. 프로젝트에 라이선스 전용 Native Variant가 있으면 저장하기 전에 그 Variant의 라이선스와 대조하며, 다른 라이선스의 키는 저장하지 않습니다.
• Server Public Key: Pro server signing public key is not configured 항목에 나옵니다. Customer Portal > Server Key에서 서명 공개키(16진수 64자)를 복사해 넣으세요. 다른 형식은 거부되며, 소문자로 저장됩니다.
• Application Identifier: Application identifier is not registered for Native Variant <NNNN> 항목에 나옵니다. 입력할 값은 활성 빌드 타깃에 따라 다르며 Customer Portal > Platform settings와 같습니다. Android는 Package Name, iOS는 Bundle Identifier를 입력하며, 입력 칸에는 현재 식별자가 미리 채워져 있습니다. 이 설정이 꺼져 있으면 Unity가 입력한 식별자를 무시하므로, Apply는 Player Settings의 Override Default Package Name / Bundle Identifier도 켭니다. Windows, macOS, Linux는 Customer Portal > Platform settings에 이 플랫폼용으로 등록한 Company Name과 Product Name(포털에는 Company / Product로 표시)을 각각의 칸에 입력합니다. 두 칸에는 현재 값이 미리 채워져 있으며, company.product 또는 com.company.product로 대조합니다. Apply는 Player Settings의 Company Name과 Product Name을 설정하며, Product Name은 빌드된 앱 이름이기도 합니다. WebGL은 포털에 등록한 페이지 origin(도메인)으로 식별하므로 프로젝트에서 바꿀 것이 없고, 이 단계는 사용할 수 없음으로 표시됩니다. 값은 라이선스에 등록된 것이어야 하며, 등록되지 않았으면 Customer Portal에서 등록한 뒤 패키지를 다시 받으라는 안내가 나옵니다.

3 모듈 활성화

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

보안 프리셋 선택

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

자세히: 프리셋이 바꾸는 값

Quick Preset 패널에는 현재 설정과 일치하는 프리셋이 Current: Standard처럼 표시되고, 해당 버튼이 굵은 글씨와 *로 표시됩니다. 적용 후 값을 직접 바꾸면 Current: Custom으로 표시되고 어느 버튼에도 표시가 붙지 않습니다. 권장값은 Standard이며 버튼에 Standard (Recommended)로 표시됩니다. 프리셋 이름은 Low / Standard / Strict 그대로입니다. 각 버튼 아래에 프리셋 설명이 나오고, 버튼의 툴팁에도 같은 설명이 보입니다.

Windows 시스템 모듈 검사(enableWindowsSystemModuleScan): Low OFF / Standard·Strict ON. 라이선스 등급이 아닌 보안 프리셋 기준입니다. 호환성과 관측 정책은 Injection 설정을 확인하세요.

설정 다운로드는 enableRemoteSpeedHackConfig, enableRemoteInjectionConfig, enableRemotePhysicsConfig로 제어합니다. 보안 프리셋은 프로젝트의 라이선스 등급(Online Services 설정)이 Pro일 때만 이 옵션을 켜고, Standard이거나 라이선스 설정이 없으면 Pro 전용 서버 옵션을 모두 끈 상태로 둡니다(등급을 Pro로 바꾼 뒤에는 프리셋을 다시 적용하세요). 이 옵션은 Pro에서만 동작합니다. 원격 설정 옵션 자체는 BIV 서버 검증·설치 출처 동기화·서버 화이트리스트·텔레메트리를 켜지 않으며, 프리셋은 이와 별도로 이 값들을 바꿉니다(위 프리셋 표 참고).

• Low: 가벼운 핵심 검사만 유지합니다. 테스트 환경이 너무 일찍 차단되지 않도록 플랫폼 네이티브 검사와 강제 종료 정책을 완화합니다.
• Standard: 핵심 보호 세트, 시작 시 검증, 런타임 재검증, 에뮬레이터 검사, 권장 IL2CPP 파일 커버리지를 켭니다. 호환성과 보호 수준의 균형을 맞춘 구성입니다.
• Strict: 가장 넓은 커버리지를 적용하고 더 많은 실패를 치명적 위반으로 처리합니다. 플랫폼, 서명, 스토어 배포 흐름을 충분히 테스트한 뒤 적용하세요.

라이선스 모델 — Standard / Pro

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

이 앱은 부정 행위와 변조를 방지하기 위해 OZero Security SDK(오제로시큐리티 주식회사)를 사용합니다. 보안 검사는 기기 안에서 이루어지며, [Pro 서버 기능이 켜진 경우] 보안 이벤트가 발생하면 다음 정보가 OZero 서버로 전송됩니다: 앱별로 해시된 기기 식별자, 플랫폼·운영체제, 앱 버전, 탐지된 보안 이벤트의 종류와 결과, 탐지에 관련된 외부 프로그램 모듈의 파일명·서명자·해시, 접속 국가. [물리 검증을 켠 경우: 캐릭터 위치·속도·씬 이름.] [Steam 확인을 켠 경우: Steam 인증 티켓과 SteamID(해시로 저장).] 기기의 원문 식별자, IP 주소, 채팅·닉네임·결제 정보는 전송되지 않습니다. 전송된 기록은 90일 후 삭제되며, 외부 프로그램 모듈 정보는 개인·기기와 연결되지 않는 형태로 OZero의 부정 프로그램 판별 기준을 개선하는 데 사용됩니다. 자세한 내용: https://www.ozerosecurity.com/privacy.html

This app uses the OZero Security SDK (OZero Security Inc.) to prevent cheating and tampering. Security checks run on the device. [When Pro server features are enabled] the following is sent to OZero servers when a security event occurs: an app-specific hashed device identifier, platform and OS, app version, the type and result of the security event, the file name, signer and hash of third-party modules involved in the detection, and the country of connection. [Physics validation: character position, velocity and scene name.] [Steam verification: the Steam auth ticket and SteamID, stored hashed.] The raw device identifier, IP address, chat, nicknames and payment data are not sent. Records are deleted after 90 days. Module information is used, in a form not linked to any person or device, to improve OZero's cheat-program classification. Details: https://www.ozerosecurity.com/privacy.html

本アプリは不正行為と改ざんを防ぐために OZero Security SDK（OZero Security Inc.）を使用しています。セキュリティ検査は端末内で行われ、[Pro サーバー機能が有効な場合] セキュリティイベント発生時に次の情報が OZero サーバーへ送信されます：アプリごとにハッシュ化した端末識別子、プラットフォーム・OS、アプリのバージョン、検知したイベントの種類と結果、検知に関係した外部モジュールのファイル名・署名者・ハッシュ、接続国。[物理検証：キャラクターの位置・速度・シーン名。][Steam 確認：Steam 認証チケットと SteamID（ハッシュで保存）。] 端末の生の識別子、IP アドレス、チャット・ニックネーム・決済情報は送信されません。記録は 90 日後に削除され、モジュール情報は個人や端末と結び付かない形で OZero の不正プログラム判定基準の改善に使われます。詳細：https://www.ozerosecurity.com/privacy.html

本应用使用 OZero Security SDK（OZero Security Inc.）防止作弊与篡改。安全检查在设备内进行，[启用 Pro 服务器功能时] 发生安全事件时会向 OZero 服务器发送以下信息：按应用哈希处理的设备标识符、平台与操作系统、应用版本、安全事件的类型与结果、与检测相关的第三方模块的文件名·签名者·哈希、连接国家。[物理验证：角色位置、速度与场景名。][Steam 验证：Steam 认证票据与 SteamID（以哈希保存）。] 不会发送设备原始标识符、IP 地址、聊天、昵称与支付信息。记录在 90 天后删除；模块信息以不关联个人或设备的形式用于改进 OZero 的作弊程序判定标准。详情：https://www.ozerosecurity.com/privacy.html

Online Services 설정

Security Config는 애드온 설정을 두 곳에 보여 줍니다. Protection Modules 그룹 끝, 즉 페이지 맨 아래(Steam Anti-Piracy (PC Only) 다음)의 Pro - License & Online Services 카드는 License(티어, 라이선스 키)로 시작합니다. Tier가 Pro이면 Server Connection, Offline & Device Policy, Security Level Enforcement(Security Config Hash (build allowlist) 목록 포함), Telemetry, Online Verification UI, Validate License Now도 표시되고, 각 탐지 모듈 섹션(Build Integrity, Install Source (Android Only), Device Binding, Speed & Time Hack, Injection & Hooking, Steam Anti-Piracy (PC Only))에 그 모듈의 온라인 설정을 담은 Pro - Online 영역이 생깁니다. 모듈의 Activate가 꺼져 있으면 이 영역은 비활성입니다.

값은 ProjectSettings/OZeroLicenseSettings.asset에 저장되며, 이 파일을 버전 관리에 커밋합니다. Project 창에는 설정 에셋이 없습니다. 같은 설정을 독립 화면에서도 편집할 수 있습니다. Security Config와 Welcome 창의 Online Services 버튼은 Window > OZero Security > Online Services 창을 열고(설정이 없으면 만들고), 이 창에는 Select Settings Asset과 Validate License Now 버튼이 있습니다. 창 위쪽의 Security Config와 Check Setup 버튼으로 해당 화면으로 이동할 수 있습니다. 이 절의 나머지는 독립 화면 기준이며, 항목 이름은 Security Config에서도 같습니다.

티어는 License 섹션에서 고릅니다. License Key 칸은 두 티어 모두에 표시됩니다. Standard를 고르면 License 섹션만 보이고, Standard는 서버 없이 동작하므로 온라인 서비스가 꺼져 있고 OZero 서버로 아무것도 보내지 않는다는 안내가 나옵니다. License Key는 Native Variant가 포함된 패키지를 쓸 때만 입력하며, 로컬에서만 확인합니다. Pro를 고르면 서버 연결과 온라인 서비스 설정이 나타납니다.

설정은 Security Config처럼 구성되며, 순서는 Quick Preset, License, Server Connection, Offline & Device Policy, Security Level Enforcement(헤더의 Enable로 켬), 모듈 섹션 Build Integrity, Install Source, Device Binding, Speed & Time Hack, Injection & Hooking, Steam Anti-Piracy, 그리고 Telemetry, Online Verification UI입니다.

프리셋은 SDK 전체에서 하나입니다. 여기의 Low / Standard / Strict 버튼은 Security Config와 같은 프리셋을 적용하므로 어느 쪽에서 적용해도 결과가 같습니다. 여기서도 Standard가 권장값이며 Standard (Recommended)로 표시되고, 각 버튼 아래에 설명이 나옵니다. 프리셋을 적용하면 탐지 모듈, 온라인 서비스 기본값, Declared Security Level이 함께 바뀌고 라이선스·서버 URL·키는 유지됩니다. 패널에는 Current: Standard 같은 현재 상태가 표시되고 해당 버튼이 굵은 글씨와 *로 표시되며, 적용 후 온라인 설정을 직접 바꾸면 Current: Custom이 되고 어느 버튼에도 표시가 붙지 않습니다. Declared Security Level이 적용한 프리셋과 다르면 Security Level Enforcement 섹션에 경고가 나옵니다.

모듈 섹션은 Security Config와 이름·순서가 같습니다. 헤더에는 Security Config의 모듈 상태(Active / Inactive, 읽기 전용)가 보이고, 섹션 맨 위에 온라인 서비스가 그 모듈에 더하는 것을 한 줄로 설명합니다. 서버 스위치는 섹션의 첫 줄에 있습니다.

• Build Integrity: Check Integrity With Server
• Install Source: Check Installer With Server
• Device Binding: Verify Device With Server
• Speed & Time Hack과 Injection & Hooking은 서버 기능이 여러 개라 단일 스위치가 없습니다.
• Steam Anti-Piracy: Check Steam DRM With Server

Security Config에서는 모듈이 꺼져 있으면 그 모듈의 Pro - Online 영역이 Activate this module to use its online settings. 안내와 함께 비활성으로 표시됩니다. 독립 화면에서는 비활성 모듈의 섹션에 모듈을 켜기 전까지 이 온라인 설정은 효과가 없다는 안내와 Open Security Config 버튼이 나옵니다.

Telemetry와 Online Verification UI는 온라인 전용입니다. Telemetry는 Customer Portal로 보내는 보안 이벤트와 원격 물리 설정을 다룹니다. Online Verification UI는 서버 검증 중에 나오는 화면(검증 중, 재시도, 온라인 필요, 시간 초과)의 동작을 정합니다. 설정 항목은 UI 정책, 재시도·온라인 필요 시간, 시간 초과 동작, 네트워크 복구 시 자동 재시도입니다. 대화상자 디자인과 언어는 Security Config > Player Notice (Managed UI)를 따릅니다. Check Integrity With Server와 Check Steam DRM With Server가 모두 꺼져 있으면 사용되지 않는다는 안내가 나옵니다.

애드온에는 별도 로그 스위치가 없으며, 로그는 Security Config의 Enable Debug Logs를 따릅니다.

Pro 패키지와 Native Variant

Pro 고객은 Customer Portal 다운로드에서 Pro 통합 패키지를 받습니다. 라이선스용으로 만든 .unitypackage 하나에 Standard SDK, 온라인 애드온, 모든 플랫폼의 Native Variant가 들어 있습니다. 카드에는 두 가지 옵션이 있습니다.

• Native Variant 포함: 이 라이선스에 배정된 전용 네이티브입니다. 카드에 배정 번호(Variant · Native · ABI)가 표시되고, 패키지는 라이선스(라이선스 키와 등록된 Bundle ID / 패키지 이름)에 바인딩됩니다.
• Standard variant(0000) 포함: Standard SDK의 공용 네이티브 그대로이며 라이선스 바인딩이 없습니다.

Variant를 교체(회전)할 때: 교체해도 이전 Variant로 만든 기존 빌드는 계속 동작합니다. 새 Variant는 교체 후 새로 다운로드한 패키지로 만든 빌드부터 적용됩니다. 교체하면 회전 횟수를 하나 사용하며, 교체 후에는 환불을 받을 수 없습니다.

Native Variant가 포함된 패키지를 Tier Standard로 쓰려면 Tier는 Standard 그대로 두고 Security Config > Pro - License & Online Services > License에 License Key만 입력하면 됩니다. 빌드와 플레이어는 키를 로컬에서만 확인하며, Tier Standard는 OZero 서버와 통신하지 않습니다. 이 동작은 기본으로 켜져 있는 Allow Standard Build With Premium License를 따릅니다. 꺼져 있으면 Check Setup이 이 옵션을 켜거나 Tier를 Pro로 바꾸라고 안내합니다.

라이선스 키 없이 빌드하려면 Standard variant(0000)가 포함된 패키지를 받으세요.

Unity Asset Store에서 SDK를 구매했다면 SDK는 Asset Store에서 설치하고, Customer Portal에서는 Pro 확장 패키지만 받습니다. 카드에서 고른 SDK 버전에 맞춘 온라인 애드온과 배정된 Native Variant가 들어 있으며, SDK 자체는 들어 있지 않습니다.

Check Setup의 Native Variant 항목

패키지에 Native Variant가 들어 있으면 Check Setup이 빌드 전에 프로젝트가 맞는지 알려 줍니다. 플레이어 빌드도 같은 이유로 중단됩니다.

게임 서버 연동: 기기 ID와 사용자 UUID

Pro에서는 게임 서버가 OZero가 쓰는 ID와 함께 동작할 수 있습니다. OZero 기기 ID를 읽어 플레이어 계정과 함께 저장하고, 게임의 사용자 UUID(계정 ID)를 연결하면 Customer Portal에서 그 사용자가 쓴 기기를 찾고 사용자를 차단할 수 있습니다.

기기 ID 읽기

OZeroLicenseRuntime.CurrentDeviceId를 읽으세요. 기본 설정에서는 Customer Portal과 텔레메트리에 보이는 값과 같습니다. 계정을 연결하려고 DeviceIdProvider를 바꾸지 마세요. 서버가 아는 기기 ID가 바뀝니다. 대신 아래의 사용자 UUID API를 쓰면 기기 ID는 그대로 유지됩니다.

사용자 UUID 연결

• 플레이어가 로그인한 뒤 OZeroLicenseRuntime.SetExternalUserId(uuid)를 호출합니다. 앞뒤 공백을 지운 뒤 비어 있거나, 128자를 넘거나, 제어 문자가 있으면 false를 돌려주고 값을 무시합니다.
• 로그아웃할 때 OZeroLicenseRuntime.ClearExternalUserId()를 호출합니다. HasExternalUserId로 사용자가 연결되어 있는지 확인할 수 있습니다.
• UUID는 기기 안에서 라이선스별 salt와 SHA-256으로 해시됩니다. 텔레메트리, 물리 이벤트, 기기 정책 확인에는 해시만 보내고 서버에도 해시만 저장합니다. 원래 UUID는 기기 밖으로 나가지 않으며 디스크에도 저장하지 않습니다.
• 활성화가 끝나기 전에 호출해도 됩니다. SDK가 UUID를 메모리에 두었다가 활성화 뒤부터 해시를 보냅니다.

사용자 차단

Customer Portal에서 사용자 차단 규칙은 두 가지 동작 중 하나를 가집니다.

• 콜백만: 게임이 policy action(Module = "user_policy", PolicyId = 규칙 ID, Reason = 운영자 사유)을 세션당 한 번 받고 처리 방법을 정합니다. 세션은 끝나지 않습니다.
• 강제 종료: 게임이 먼저 policy action(Module = "user_policy", ActionId = "user_blocked", Reason = "terminate")을 받습니다. 그다음 SDK가 기기 정책 차단과 같은 종료 안내(OZ-SEC-0E)를 보여 주고 세션을 끝냅니다.

사용자 차단과 기기 차단은 OZeroLicenseRuntime.LastServerBlockCode로 구분합니다. 사용자는 "USER_BLOCKED", 기기는 "DEVICE_BLOCKED"입니다. 판정은 SetExternalUserId 호출 뒤 약 5초 안에 실행되며(기기 정책 heartbeat가 꺼져 있어도), 최소 30초 간격입니다. 네트워크가 실패하면 세션을 끝내지 않고 다음 확인에서 판정합니다.

Customer Portal: 사용자 UUID 페이지

Customer Portal에서 운영 정보 > 사용자 UUID를 엽니다(Pro). 페이지에는 탭이 세 개 있습니다.

• 사용자 검색: 게임이 SetExternalUserId에 넘긴 UUID를 입력합니다. 브라우저가 전송 전에 해시하므로 원래 값은 서버에 가지 않습니다. 결과에는 그 사용자가 쓴 기기(처음·마지막 관측, 이벤트 수), 최근 이벤트(텔레메트리, 물리 이벤트, 정책 차단), 차단 상태와 차단 규칙 만들기·수정·해제 버튼이 나옵니다. 기기로 검색은 기기 ID(CurrentDeviceId)로 연결된 사용자 수와 사용자 키 앞 8자를 보여 줍니다. 원래 UUID는 표시할 수 없으므로, 사용자를 확인하려면 UUID로 검색하세요.
• 차단 규칙: 규칙 목록(적용 중 또는 전체)을 봅니다. 새 규칙에서는 사용자 UUID, 동작(콜백만 또는 강제 종료), 게임 콜백에도 전달되는 사유, 만료(만료 없음(기본값, 해제할 때까지), 7·30·90일, 직접 지정)를 정합니다. 이미 규칙이 있는 사용자에 저장하면 기존 규칙이 갱신됩니다. 규칙마다 만든 곳(포털, 서버 API, 운영자)이 표시됩니다.
• 설정: 라이선스의 salt, 계산식, UUID 정규화 규칙, 현재 연결 수, 고객 서버에서 같은 해시(h1)를 계산하는 C#·Node.js·Python 예제를 보여 줍니다. 고객 서버는 이 h1로 서버 API를 호출합니다. 게임 클라이언트에는 salt가 필요 없습니다(SDK가 활성화 때 받습니다).

salt 재발급(설정 탭)을 하면 기존 연결이 끊깁니다. 이전 salt로 만든 사용자 연결과 차단 규칙은 더 이상 사용자와 일치하지 않고, 기존 규칙은 옛 키로 남습니다. 게임은 다음 활성화 때 새 salt를 받으며, 고객 서버도 새 salt로 h1을 다시 계산해야 합니다.

차단 규칙 저장·해제와 salt 재발급은 운영 이력의 사용자 UUID 분류에 기록됩니다.

Customer Portal은 단일 페이지 앱입니다. 업데이트 뒤 화면이 예전 그대로이거나 이상하면 페이지를 새로고침하세요.

설정 탭과 같은 예제입니다. API 레퍼런스(OZeroLicenseRuntime)의 테스트 벡터로 구현을 확인하세요.

// C#
using System.Security.Cryptography;
using System.Text;

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

// Node.js
const crypto = require("crypto");

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

# Python
import hashlib

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

예제: 로그인, 로그아웃, policy 콜백

using OZeroSDK.Security;
using OZeroSDK.Security.License;
using UnityEngine;

public sealed class OZeroAccountLink : MonoBehaviour
{
    private void OnEnable()
        => OZeroSecurityManager.Instance.RegisterUserPolicyActionCallback(OnPolicyAction);

    private void OnDisable()
        => OZeroSecurityManager.Instance.UnregisterUserPolicyActionCallback(OnPolicyAction);

    // Call after your sign-in succeeds.
    public void OnSignedIn(string accountUuid)
    {
        if (!OZeroLicenseRuntime.SetExternalUserId(accountUuid))
            Debug.LogWarning("OZero: user id rejected (empty, too long, or control characters).");

        // Optional: keep the OZero device id with the account on your server.
        string deviceId = OZeroLicenseRuntime.CurrentDeviceId;
        MyGameServer.ReportDevice(accountUuid, deviceId);
    }

    // Call on sign-out.
    public void OnSignedOut() => OZeroLicenseRuntime.ClearExternalUserId();

    private void OnPolicyAction(OZeroPolicyActionEvent evt)
    {
        if (evt.Module != "user_policy")
            return;

        if (evt.ActionId == "user_blocked")
        {
            // Terminate rule: the SDK shows the termination notice and ends the session next.
            MyGame.SaveQuickly();
            return;
        }

        // Callback-only rule: the game decides what to do.
        Debug.LogWarning($"User block rule {evt.PolicyId}: {evt.Reason}");
        MyGame.RestrictAccount(evt.Reason);
    }
}

개인정보와 스토어 신고

• UUID에는 이메일 주소나 전화번호가 아닌 가명 계정 ID를 쓰세요.
• iOS: 애드온의 개인정보 매니페스트가 이미 User ID를 신고하므로 추가 항목은 필요 없습니다.
• Google Play: 사용자 UUID를 연결한다면 Data safety 양식에 User IDs를 신고하세요.

보안 설정 해시 허용 목록

빌드마다 보안 설정(OZeroSecurityConfig, 온라인 애드온 설정 포함)을 봉인하고 그 SHA-256 해시를 계산합니다. 배포하는 빌드의 해시를 승인하면 서버의 보안 레벨 확인은 그 빌드만 통과시킵니다. 따라서 설정을 낮춘 변조 빌드가 높은 보안 레벨을 선언해도 통과할 수 없습니다.

• 호환 모드(승인된 해시 0개): 선언한 보안 레벨만 비교하며, 모든 빌드가 해시 확인을 통과합니다.
• 적용 모드(승인된 해시 1개 이상): 해시가 승인되지 않은 빌드는 거부됩니다. Fail On Security Level Reject가 켜져 있으면 게임이 종료되고, 아니면 Standard로 강등됩니다.

Pro 전용입니다. Security Config > Pro - License & Online Services > Security Level Enforcement가 켜져 있어야(헤더의 Enable, enableSecurityLevelCheck) 동작합니다. 꺼져 있으면 빌드가 해시를 보내지 않아 허용 목록이 효과가 없으며, 이 섹션에는 해시 목록 대신 경고 하나만 표시됩니다.

빌드 해시 확인

• 빌드 로그에 [OZero] Security config digest for this <Target> build: <64 hex> 줄이 찍힙니다.
• Security Level Enforcement가 켜져 있으면 Security Config 맨 아래 Pro - License & Online Services 카드의 Security Level Enforcement 섹션 안 Security Config Hash (build allowlist)에 최근 빌드 5개(타깃, 시각(UTC), 해시, Copy 버튼)가 표시됩니다. Window > OZero Security > Online Services 창의 같은 섹션에도 같은 목록이 있습니다.
• 기록 파일 Library/OZeroSecurity/BuildConfigDigests.json에 최근 20개가 보관됩니다.
• 플레이어가 보내는 해시는 빌드 로그와 Pro 카드(또는 Online Services 창)에 표시된 다이제스트와 같습니다.
• 같은 설정을 다른 PC에서 빌드해도 해시는 같습니다.
• 에디터 Play Mode는 빌드 해시가 아니라 설정 에셋으로 계산한 해시를 보냅니다. 포털의 서버가 받은 해시 목록에 나타날 수 있지만 승인하지 마세요.

Customer Portal에서 해시 승인

정책 설정 > 보안 설정 해시를 엽니다(Pro).

• 위쪽에 정책 모드(적용 또는 호환)와 유효한 승인 해시 수가 표시됩니다.
• 승인된 해시: 해제로 뺍니다. 마지막 해시를 해제하면 라이선스가 호환 모드로 돌아갑니다.
• 서버가 받은 해시: Security Level Enforcement가 켜진 빌드가 보낸 해시입니다(기기 ID는 저장하지 않고, 관측 수는 최대 한 시간에 한 번 셉니다). 릴리스 빌드의 해시에서 승인을 누르세요.
• 해시 직접 등록: 빌드 로그나 Pro 카드의 해시, 라벨, 만료(없음, 30일, 90일, 1년)를 입력합니다.
• 첫 승인 때는 "승인되지 않은 빌드는 거부된다"는 확인 절차가 있습니다. 켜기 전에 현재 배포 중인 빌드를 모두 승인하세요.

승인과 해제는 운영 이력에 기록됩니다. CI에서 해시를 등록하려면 API 레퍼런스의 보안 설정 해시(CI)를 보세요.

Pro 라이선스 키 등록

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

1. 설정 에셋 생성

온라인 애드온은 import 뒤 에디터가 한가해질 때 라이선스 설정을 ProjectSettings/OZeroLicenseSettings.asset에 자동으로 만듭니다(옛 OZeroLicenseConfig 에셋이 Assets/ 아래 남아 있으면 만들지 않습니다). 라이선스는 Security Config 맨 아래 Pro - License & Online Services 카드에서 입력합니다. License에서 티어를 고르고 라이선스 키를 입력하며(Standard에서는 Native Variant 패키지를 쓸 때만), 서버 URL과 키는 Server Connection에 있습니다. Security Config나 Welcome 창의 Online Services를 누르면 같은 설정이 있는 Window > OZero Security > Online Services 창이 열리고, 설정이 없으면 만들어 줍니다. ProjectSettings/OZeroLicenseSettings.asset는 버전 관리에 커밋하세요.

2. Inspector 필드 채우기

3. Check Integrity With Server 확인

빌드하기 전에 Security Config > Build Integrity > Pro - Online > Check Integrity With Server가 원하는 값인지 확인하세요. Standard·Strict 프리셋은 켜고 Low 프리셋은 끄며, 새로 만든 Online 설정은 Standard 값(켬)으로 시작합니다. 켜 두면 서버 빌드 판정과 실행 중 재확인이 더해지고, Standard에서는 시작할 때 온라인이 필요합니다. 포털의 기기·Variant 차단은 이 값과 관계없이 적용됩니다. 기본 Built-In 확인 UI를 쓰면 TMP dialog 패키지가 필요하며 Auto Setup이 가져옵니다. 오프라인 실행이 필요하면 오프라인 동작을 참고하세요.

4. 빌드 & 검증

별도 코드를 추가할 필요는 없습니다. 앱이 시작되면 SDK가 빌드 때 암호화 리소스로 플레이어에 넣은 라이선스 설정을 자동으로 읽습니다. 첫 실행 후 Player 로그에서 [OZeroLicense] activated; tier=pro caps=5 같은 줄을 확인하세요. Pro로 설정했는데 Standard 모드로 실행된다는 로그가 보이면 먼저 ProjectSettings/OZeroLicenseSettings.asset가 있고 빌드 전에 저장됐는지, Check Setup에 Old OZeroLicenseConfig asset found가 없는지 확인하세요.

오프라인 동작

Standard는 서버 없이 실행됩니다. Pro는 저장된 활성화 정보를 이용해 오프라인으로 시작할 수 있지만, 라이선스 정책에서 실행할 때마다 온라인 확인을 요구하도록 설정한 경우에는 서버 연결이 필요합니다.

Standard — 인터넷 없이 바로 실행

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

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

선택형 Pro 서버 기능을 켠 경우 온라인 상태에서 기기와 라이선스를 확인합니다. 선택한 서버 기능은 제한된 시간 동안 일시적인 연결 끊김을 견딜 수 있습니다. 이 확인은 이미 취득한 Native Variant의 빌드나 로컬 보호를 제한하지 않습니다.

오프라인 실행이 필요한 게임: Standard·Strict 프리셋은 Check Integrity With Server를 켜므로 서버 검증을 위해 온라인 연결이 필요합니다. 오프라인으로 실행해야 하면 Low 프리셋을 적용하거나 Security Config > Build Integrity > Pro - Online > Check Integrity With Server를 끄세요. 이 경우 서버 빌드 판정과 실행 중 재확인이 빠집니다.

저장된 Pro 활성화 정보는 서버가 서명한 활성화 토큰이 만료될 때까지 유효합니다. 만료 시점은 OZero 서버가 토큰을 발급할 때 정하며(현재 활성화 성공 후 7일), SDK에서 늘릴 수 없습니다. 이 기간이 지나면 다시 활성화에 성공해야 Pro 서버 기능을 사용할 수 있습니다. 이미 적용한 Native Variant와 로컬 탐지 설정은 바뀌지 않습니다. 이 유효 기간은 아래의 로컬 시계 정책과 별도로 적용됩니다.

Pro — 기기 시계 사용 방식 선택

고객 포털 > 라이선스 > 로컬 시계에서 저장된 Pro 활성화 정보를 오프라인 시작에 사용할 수 있는지 설정합니다. 온라인 활성화에는 서버 시간이 사용되므로, 기기의 날짜나 시간이 실제와 다르다는 이유만으로 온라인 Pro 기능이 낮아지지 않습니다.

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

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

이 동작은 Security Config의 Pro - License & Online Services 카드에 있는 Offline & Device Policy 섹션의 Offline Pro Policy Mode(OZeroLicenseConfig.offlineProPolicyMode, Online Services 창에도 있음)로 설정합니다. 기기가 서버에 연결할 수 없을 때 로컬 Build Integrity가 마지막으로 받은 서명된 Pro 포털 차단 정책을 어떻게 다룰지 결정합니다.

요약하면 ApplyCachedBlockPolicies는 운영 기본값인 fail-open 모드, RequireFreshPolicy는 fail-closed 정책 모드, IgnoreCachedBlockPolicies는 테스트용 bypass입니다. 매 검증마다 온라인 서버 확인을 반드시 요구해야 한다면 이 옵션만으로 판단하지 말고 서버 Integrity 또는 Managed Verification 필수 옵션도 함께 구성하세요.

라이선스 오류 해결

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

프로젝트 설정

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

최소 빌드 타겟

릴리스 빌드 권장 설정

출시 빌드에는 다음 설정을 권장합니다.

• Scripting Backend를 IL2CPP로 설정하세요(Project Settings > Player > Other Settings).
• Managed Stripping Level은 Low로 두세요. Mono 백엔드라면 Disabled로 두세요.
• 설정을 바꾼 뒤에는 씬 전환, 저장/불러오기, 결제·광고 같은 외부 SDK를 실기기에서 테스트하세요.

클라이언트 보호의 한계

Mono 빌드는 일반 도구로 디컴파일하고 고칠 수 있어, 수정된 빌드가 클라이언트 검사를 건너뛸 수 있습니다. IL2CPP는 수정 비용을 크게 높이지만 완전한 방지는 아닙니다. 진짜 대책은 서버 검증, 그리고 게임 코드가 Secure Variables 같은 OZero API에 의존하게 하는 것입니다.

우회 피해가 큰 게임에는 다음 구성을 권장합니다.

• 핵심 게임 값(재화, 점수, 능력치)은 Secure Variables(OZeroSV)로 관리하세요. SDK를 제거하거나 무력화하면 게임 진행이 깨지므로 우회 비용이 커집니다.
• 서버 무결성 검증(OZeroManaged 또는 CustomerGameServer)을 켜고, 게임 서버에서 OZA 토큰이나 managed session을 확인하세요. 수정된 클라이언트는 유효한 서버 서명을 받을 수 없습니다.

macOS: Developer ID 서명과 공증

Unity가 만든 macOS 빌드는 ad-hoc 서명이라, Build Integrity가 켜져 있으면 실행 약 10초 뒤 종료됩니다. 배포하려면 Developer ID Application 인증서로 서명해야 합니다. 자동 서명을 켜 두면 빌드가 끝날 때 OZero가 서명합니다.

자동 서명 켜기 (권장)

1. Window > OZero Security > macOS Distribution Signing을 열고 Sign macOS builds를 켜세요. 빌드 대상이 macOS면 Check Setup의 Open signing settings로도 열 수 있습니다.
2. Certificate에서 Developer ID Application 인증서를 고르세요. 키체인에 하나뿐이면 Automatic으로 두면 됩니다.
3. 빌드 중에 공증까지 하려면 Notarize를 켜고, xcrun notarytool store-credentials로 한 번 만들어 둔 Notary keychain profile 이름을 입력하세요.
4. Save를 누르세요. 이후 macOS 빌드가 끝날 때마다 자동으로 서명되며, Console에 macOS distribution signing complete가 나오면 바로 배포할 수 있습니다.

bash "/path/to/YourProject/Assets/OZeroSecurity/Tools/macOS/OZeroMacSign.sh" \
  --app "/path/to/YourGame.app" \
  --project "/path/to/YourProject" \
  --notary-profile "YourNotaryProfile"

OZERO_MACOS_SIGNED_APP_PATH="/path/to/YourGame.app" \
  "/path/to/Unity.app/Contents/MacOS/Unity" -batchmode -nographics -quit \
  -projectPath "/path/to/YourProject" \
  -executeMethod OZeroSDK.Security.Editor.OZeroMacOSPostSignIntegrityRebaker.RebakeAfterNestedSigning \
  -logFile rebake.log

Windows / Linux: 코드 서명과 무결성 파일 재생성

Windows나 Linux 빌드에 직접 코드 서명을 하지 않는다면 아래 단계는 건너뛰세요. 빌드 뒤 실행 파일이나 네이티브 모듈에 서명했다면, 서명한 다음에 OZero 무결성 파일을 다시 생성해야 합니다. 그러지 않으면 시작 시 무결성 오류(0x0A)로 종료됩니다.

1. 평소처럼 빌드한 뒤 실행 파일과 직접 만든 DLL·.so에 서명하세요. OZero DLL은 이미 서명돼 있으니 다시 서명하지 않아도 됩니다. 출시 빌드에는 OS가 신뢰하는 인증서가 필요하며, 자체 서명 테스트 인증서로는 통과하지 않습니다.
2. 아래 명령으로 서명한 산출물 기준의 무결성 파일을 다시 생성하세요. 에디터에서는 Tools > OZero Security > Re-bake Integrity After Code Signing (Windows or Linux player)...을 써도 됩니다.
3. 그대로 패키징해 배포하세요. 무결성 파일은 <Game>_Data/StreamingAssets 아래에 있어 서명 대상이 아닙니다. 서버 검증을 쓴다면 재생성이 출력한 manifest 해시를 등록하세요.

set OZERO_SIGNED_PLAYER_PATH=C:\dist\YourGame.exe
"C:\Program Files\Unity\Hub\Editor\<version>\Editor\Unity.exe" -batchmode -nographics -quit ^
  -projectPath "C:\path\to\YourProject" ^
  -executeMethod OZeroSDK.Security.Editor.OZeroStandalonePostSignIntegrityRebaker.RebakeAfterSigning ^
  -logFile rebake.log

Android ProGuard / R8 설정

# 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/OZeroSecurity/Plugins/Android/arm64-v8a 아래에 유지하고, 32비트 빌드를 배포한다면 armeabi-v7a도 함께 유지하세요.
• Build Integrity > Check Platform Native와 Android SHA Keys를 사용하는 경우, Minify/R8 적용 후 최종 서명된 APK 또는 AAB로 반드시 테스트하세요. 디버그 키스토어 지문과 릴리스 키스토어 지문은 서로 다릅니다.

5 보안 설정 (OZeroSecurityConfig)

보안 설정은 패키지를 import하면 Standard 프리셋으로 만들어집니다. Edit > Project Settings > OZero Security에서 편집하며, Window > OZero Security > Config & Dashboard도 같은 페이지를 엽니다. 공유 값은 ProjectSettings/OZeroSecuritySettings.asset에 저장되고 비밀값이 없으므로 버전 관리에 커밋합니다. DeveloperSecret과 매니페스트 서명 개인키 경로는 사용자별 값으로 UserSettings/OZeroSecuritySecrets.json에 저장되며 버전 관리에 넣지 않습니다. 런타임과 에디터 스크립트에서는 OZeroSecurityConfig.Instance로 읽고, 스크립트에서 값을 바꾸려면 고객 빌드 스크립트를 참고하세요. 페이지는 Quick Preset, Project & Advanced(Common Settings, Editor Play Mode), Detection Response(Global Threat Response, Player Notice (Managed UI)), Protection Modules 순서입니다. 모든 섹션은 접힌 상태로 시작하므로 제목을 눌러 펼친 뒤 설정하세요. Security Termination Notice 정책은 Detection Response의 Player Notice (Managed UI)에 있습니다.

공통 설정

모든 보안 모듈에 공통으로 적용되는 최상위 설정입니다. 이 표의 기본값은 코드에 정의된 직렬화 기본값을 기준으로 합니다. Security Config에서는 Project & Advanced 그룹의 Common Settings에 있으며, Keys & Storage, Build Checks (Preflight), Logs & Diagnostics로 나뉩니다.

Player Notice (Managed UI) (모든 라이선스)

Security Termination Notice, 공통 다이얼로그 프리팹, 로컬라이징은 Standard와 Pro에서 모두 사용할 수 있습니다. Pro에는 Build Integrity와 Steam DRM용 Managed Verification 재시도·timeout·provider 설정이 추가됩니다. 선택형 package를 import하기 전에 Package Manager에서 Unity UI와 TextMeshPro를 설치하세요. 안내 UI는 이미 예약된 종료를 설명할 뿐 종료를 취소하거나 native deadline을 연장하지 않습니다.

Global Threat Response

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

연동 문제 자가진단 가이드

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

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

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

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

빌드 무결성 검증기 설정

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

플랫폼별 참고 (포털 차단): Android 빌드는 manifest hash를 만들지 않으므로 빌드 해시 차단은 적용되지 않고 버전 차단만 적용됩니다. WebGL은 서명된 차단 목록을 로컬에서 검사하지 않습니다. 버전 차단은 SDK 버전과 앱 버전을 같은 목록으로 비교하며 플랫폼을 구분하지 않으므로, 차단한 버전은 모든 플랫폼에 적용됩니다.

CustomerGameServer에서는 게임 서버가 서버 API 키로 POST /v1/validate를 호출해 토큰을 확인합니다. 전체 흐름과 예제는 API 레퍼런스의 서버 API 키로 게임 서버 연동하기를 보세요.

RSA 서명 키 생성 (Build Integrity Manifest)

Build Integrity는 빌드할 때 생성되는 manifest에 RSA 서명을 추가할 수 있습니다. 이 manifest에는 런타임에 검증할 assembly hash와 파일 무결성 정보가 들어 있습니다. 릴리스 빌드에서는 manifest 자체가 바뀌면 검증 기준을 믿을 수 없으므로, 배포 전에 Window > OZero Security > Config & Dashboard에서 Generate Key Pair를 실행해 manifest 서명 키 쌍을 생성하세요. SDK 1.2.0부터 통합 해시(oz_ahash)에는 모든 프리셋에서 플레이어 시작 파일이 항상 포함됩니다. Windows·macOS·Linux(Mono·IL2CPP)는 RuntimeInitializeOnLoads.json, ScriptingAssemblies.json, globalgamemanagers, globalgamemanagers.assets, Android는 네이티브 라이브러리와 global-metadata.dat에 더해 RuntimeInitializeOnLoads.json, ScriptingAssemblies.json입니다. 데스크톱에서 Compression Method가 LZ4/LZ4HC이면 globalgamemanagers, 씬, 에셋이 data.unity3d 한 파일로 묶이며, 이때는 개별 파일 대신 이 파일이 있으면 항상 해시됩니다. 파일이 커도 SHA-256 계산은 시작 시 GB당 1초 안팎입니다.

Manifest 서명이 필요한 이유

빌드 시점에 OZero는 개인 키로 manifest에 서명합니다. 플레이어 빌드에는 개인 키가 포함되지 않고, 보안 설정에 저장된 공개 키만 포함됩니다. 런타임에는 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용 키 쌍을 생성합니다. 공개 키는 보안 설정(Project Settings)에 저장되고, 개인 키는 기본적으로 다음 경로에 저장됩니다(이 경로 자체는 User Settings에 사용자별로 저장됩니다):
   [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을 사용해야 합니다.

기존 키 쌍 유효성 검사

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

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

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

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

듀얼 핑거프린트 키 회전

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

현재 키와 이전 키

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

안전한 키 회전 절차

1. 현재 fingerprint를 백업합니다. Assets/OZeroSecurity/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, 보안 설정의 공개 키, OZeroManifestTrustAnchor의 fingerprint, 생성된 manifest/signature 파일 중 하나가 서로 맞지 않을 때 발생합니다.

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

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

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

Project Settings > OZero Security > Build Integrity > Manifest Signing Public Key가 비어 있을 때 발생합니다. 해결: 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"

보안 설정의 공개 키와 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를 한 번 실행해 확인하는 것을 권장합니다.

Install Source (Android Only) 설정

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

Steam Anti-Piracy (PC Only) 설정

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

Steamworks SDK 폴더와 라이브러리 자동 복사

Project Settings > OZero Security > Steam Anti-Piracy (PC Only) > SDK Folder(또는 Check Setup의 Steam 설정 칸)에서 Steamworks SDK 폴더(sdk 폴더 또는 그 상위 폴더)를 고르세요. 빌드할 때 OZero가 대상 플랫폼에 맞는 Steam API 라이브러리를 빌드 산출물에 자동으로 복사하므로 직접 복사할 필요가 없습니다.

빌드를 시작하기 전에 OZero가 라이브러리의 파일 형식·아키텍처와 지원하는 Steamworks 버전(SteamApps v008–v009, SteamUtils v009–v010, SteamUser v022–v023)을 검사하며, 맞지 않으면 빌드가 멈춥니다. 복사는 무결성 manifest를 만들기 전에 일어나므로 Steam 라이브러리도 무결성 검사 대상에 들어갑니다. macOS 빌드에 서명할 때 libsteam_api.dylib의 Valve 서명은 그대로 유지됩니다(macOS 서명).

다른 PC와 CI: 고른 폴더는 그 PC의 Editor 설정에만 저장되고 프로젝트 파일에는 남지 않습니다. 다른 PC나 CI에서는 폴더를 다시 고르거나 환경 변수 OZERO_STEAMWORKS_SDK에 SDK 폴더 경로를 설정하세요. 둘 다 없으면 빌드가 안내 메시지와 함께 실패합니다.

데스크톱 전용: Steam Anti-Piracy는 Windows, macOS, Linux 플레이어에서만 동작합니다. 켠 채로 Android, iOS, WebGL을 빌드해도 빌드는 경고만 남기고 진행되며, 그 앱에서는 Steam 검사가 실행되지 않고 Steam 라이브러리도 포함되지 않습니다. 이때 Check Setup에는 Info 항목 Steam Anti-Piracy is skipped for this build target가 표시됩니다.

Steamworks.NET 등 래퍼와 함께 쓸 때: 래퍼 플러그인이 빌드 산출물에 넣은 steam_api 라이브러리가 선택한 SDK의 것과 다르면 OZero가 SDK의 라이브러리로 교체하고 빌드 로그에 경고를 남깁니다. 래퍼가 빌드된 것과 같은 Steamworks SDK 버전을 SDK Folder로 지정하세요.

Steam 보호 집행 수준

Steam 위반이 게임 종료로 이어지는 것은 Detection Action이 Callback 또는 Block이고 Response > Force Quit On Detection이 켜져 있을 때입니다. 이 집행 수준은 빌드할 때 boot 메타데이터에 봉인되고, 종료는 네이티브 코드가 직접 집행합니다. 빌드 출력의 봉인 값이 보안 설정과 다르면 빌드 preflight가 실패하니 다시 빌드하세요.

Observe·Off이거나 Force Quit On Detection이 꺼져 있거나, forceSteamAntiPiracyObserveOnly가 켜져 있거나, requireSteamApiInit이 꺼져 있거나, Low 프리셋이면 위반은 기록만 되고 게임은 종료되지 않습니다. 이런 구성도 허용되지만 Check Setup의 Steam enforcement 항목에 경고로 표시되고, 빌드할 때 콘솔에도 경고가 남습니다. 종료가 일어나는 구성이면 같은 항목에 "terminates on detection"으로 표시됩니다.

온라인 애드온에서 Check Steam DRM With Server로 서버가 Steam 소유를 판정하는 구성은 네이티브 종료 대신 서버 판정 흐름을 따르며, 로컬 Steam 위반은 관찰로 기록됩니다.

디바이스 바인딩 설정

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

운영에서 사용하는 방식

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

게임에서 바인딩 해제하기

플레이어가 정당하게 기기를 바꿨다면 게임에서 RequestReset으로 저장된 지문을 지울 수 있습니다. 플레이어 빌드에서는 OZeroDeviceBindingDetector.SetResetAuthorizer로 등록한 인가 콜백에 묻고, 콜백이 true를 돌려줄 때만 해제합니다. 해제한 뒤에는 같은 세션에서 현재 기기를 곧바로 다시 등록하므로 재시작할 필요가 없습니다.

using OZeroSDK.Security;

// Register once at startup.
OZeroDeviceBindingDetector.SetResetAuthorizer(request =>
{
    // Approve only after your own check succeeds, for example a recent
    // account re-authentication or a support code your server verified.
    return MyAccountService.HasVerifiedResetFor(request.Reason);
});

// Later, from your account recovery or support screen:
bool cleared = OZeroDeviceBindingDetector.Instance?.RequestReset("ticket-1234") ?? false;

플레이어 빌드에서 인가 콜백도 없고 유효한 서버 Reset Token도 없으면 해제를 거부하고 오류 로그를 남깁니다. 에디터에서는 항상 해제됩니다. RequestReset과 인가 콜백은 호출한 스레드에서 동기로 실행됩니다. ClearStoredFingerprint(token)도 계속 동작합니다. Pro 라이선스와 서버 설정(서버 URL, 라이선스 키)이 있으면 비어 있지 않은 토큰을 백그라운드에서 서버 Reset Token으로 검증하므로, 해제는 호출이 반환된 뒤에 일어납니다. 결과가 필요하면 메인 스레드에서 ClearStoredFingerprintAsync(token)을 await하세요(아래 흐름). 그 밖의 경우에는 인가 콜백이 판단하며 토큰은 request.AuthorizationToken으로 전달됩니다.

Standard 게임의 CS 처리 가이드

Standard에는 OZero 서버가 없어서 포털 Reset Token을 쓸 수 없습니다. 대신 게임의 CS 확인 절차를 인가 콜백(SetResetAuthorizer)에 직접 연결하세요. 아래 방법 중 하나를 고르되, 어떤 방법이든 위 경고처럼 확인이 통과한 뒤에만 콜백에서 true를 돌려주세요.

A. 게임 자체 서버(계정 시스템)가 있는 경우 — 권장

1. CS가 백오피스에서 플레이어 계정에 1회용 지원 코드를 발급합니다.
2. 플레이어가 게임 화면에 코드를 입력합니다.
3. 게임이 자체 서버에서 코드를 먼저 비동기로 검증합니다.
4. 통과하면 게임이 RequestReset을 호출하고, 콜백은 방금 검증이 통과했는지만 확인합니다.

플레이어가 다시 로그인(플랫폼 재인증)하면 해제를 허용하는 방식도 같은 구조입니다. 인가 콜백은 동기로 실행되므로 비동기 검증을 먼저 끝낸 뒤 RequestReset을 호출하세요.

bool _supportCodeVerified;

void Start()
{
    // The authorizer runs synchronously: it only reports whether the check just passed.
    OZeroDeviceBindingDetector.SetResetAuthorizer(_ => _supportCodeVerified);
}

async void OnSubmitSupportCode(string code)
{
    // Verify the one-time code issued by your support team on your own backend.
    _supportCodeVerified = await MyBackend.VerifyResetCodeAsync(accountId, code);
    try
    {
        bool cleared = OZeroDeviceBindingDetector.Instance.RequestReset("cs-support");
        ShowResetResult(cleared);
    }
    finally
    {
        _supportCodeVerified = false;
    }
}

B. 서버가 없는 오프라인 게임 — 서명 코드 방식

1. 게임이 요청 코드를 보여 줍니다. 예를 들어 1회용 난수와 게임 자체의 세이브·플레이어 ID를 짧게 인코딩한 값입니다.
2. CS가 개발사만 가진 개인키로 서명한 응답 코드를 돌려줍니다.
3. 게임은 내장된 공개키로 응답을 검증하고, 서명이 유효할 때만 콜백이 해제를 허용합니다. 같은 응답을 다시 쓰지 못하도록 사용한 난수는 버리세요.

// Pseudocode. Game: build a request code that the player sends to support.
nonce        = RandomBytes(8)          // keep until the reset is done, then discard
requestCode  = ShortEncode(nonce + yourSaveOrPlayerId)

// Support tool on your side. The private key never ships with the game.
responseCode = Sign(studioPrivateKey, requestCode)          // Ed25519 or ECDSA

// Game: verify with the public key built into the game, then reset.
OZeroDeviceBindingDetector.SetResetAuthorizer(_ => _signedCodeVerified)
_signedCodeVerified = Verify(embeddedPublicKey, requestCode, responseCode)
OZeroDeviceBindingDetector.Instance.RequestReset("cs-offline")
_signedCodeVerified = false
Discard(nonce)

C. 앱 데이터 삭제 또는 재설치

바인딩 기록은 앱 로컬 저장소(PlayerPrefs)에 있습니다. 플레이어가 앱 데이터를 지우거나 앱을 재설치하면 다음 실행 때 새 기기로 등록됩니다. 로컬 세이브도 사라질 수 있으니 서버·클라우드 세이브가 있는 게임에서만 CS 답변으로 쓰세요.

D. 문의 줄이기

hardwareChangeTolerance를 1 이상으로 두면(Standard 프리셋은 1, Strict는 0) OS 업데이트나 개인정보 설정 변경으로 식별값 하나가 바뀌어도 차단하지 않고 기기를 다시 등록합니다.

Pro: 포털 Reset Token과 ClearStoredFingerprintAsync(token)을 쓰세요. 아래 Reset Token 지원 흐름을 참고하세요.

Reset Token 지원 흐름 (Pro)

1. 기기 초기화가 필요한 이유와 플레이어 계정을 일반 고객지원 절차로 먼저 확인합니다.
2. Customer Portal → Device Binding에서 대상 기기를 선택하고 Reset Token을 발급합니다.
3. 토큰은 인증된 고객지원 채널로만 전달하세요. 공개 채팅, 스크린샷, 오래 남는 티켓에 남겨두지 마세요.
4. 게임이나 지원 UI는 메인 스레드에서 await OZeroDeviceBindingDetector.Instance.ClearStoredFingerprintAsync(token.Trim())로 토큰을 넘기고 돌려받은 bool을 확인하세요. ClearStoredFingerprint(token.Trim())도 동작하지만, 서버 검사가 백그라운드에서 돌기 때문에 해제는 호출이 반환된 뒤에 일어납니다.
5. SDK가 토큰을 받아들이면 같은 세션에서 현재 기기를 곧바로 다시 등록합니다. 재시작할 필요가 없습니다.

Speed & Time Hack 설정

Unity 시간, 네이티브 기준 시계, 백그라운드 타이머, 웹/Pro 서버 시간을 서로 비교해 게임 속도를 빠르게 또는 느리게 바꾸는 조작과 기기 시계 변경을 감지합니다. WebGL에서는 네이티브 시계 비교를 쓸 수 없습니다. 시작 로그에 이 내용이 표시되며, 브라우저 시계 변조(Date.now / performance.now)는 Injection & Hooking의 WebGL 런타임 검사가 대신 탐지합니다.

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로 확인합니다. 릴리스 빌드의 heartbeat 한도는 모든 플랫폼에서 약 10초입니다(시작 유예 이후). 한도가 지나면 Watchdog은 먼저 메인 스레드가 무엇을 하고 있는지 봅니다. 스레드가 막혀 CPU를 쓰지 않는 상태(긴 동기 로딩, 로그 flush, 디스크 I/O, 가상 머신의 일시 정지)는 stall로 보고 기록만 남기며, 게임이 계속 돌아가는데 heartbeat만 오지 않는 경우는 변조로 보고 설정된 대응 정책에 따라 종료합니다. 5분 넘게 멈춘 프로세스는 응답 없음으로 종료합니다.

대형 씬 로딩, 동기식 에셋 압축 해제, 셰이더 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 메모리, 인라인 후킹, 원격 스레드형 주입, 고위험 프로세스 핸들, WebGL 런타임 변조가 대상입니다. 정상 오버레이나 캡처 도구도 같은 방식으로 게임에 들어오므로, 탐지기는 모든 모듈을 파일 해시와 서명자로 식별하고 모듈별로 판정할 수 있게 합니다.

처음 보는 시스템 모듈이라고 해서 바로 게임을 종료하지는 않습니다. 우선 관측 대상으로 기록하며, 반복해서 발견되거나 파일에 서명이 없다는 이유만으로 차단하지 않습니다. 기존 허용 규칙은 유지되고, 해시로 명시적으로 차단한 모듈에는 차단 정책이 적용됩니다. 이 옵션은 Unity의 Injection 설정에서 조정할 수 있으며, Pro 포털에서는 원격으로 변경할 수 없습니다. 다른 플랫폼에는 영향을 주지 않습니다.

탐지기가 모듈을 식별하는 방식

탐지기는 몇 초마다 게임 프로세스에 로드된 모듈 전체를 훑어 시작 시점의 목록과 비교합니다. 새 모듈은 파일 해시로, Windows·macOS에서는 서명 인증서 지문으로도 식별합니다. 규칙은 모듈 자체만 보고 설치 폴더 이름은 보지 않으므로, 정상 프로그램이 설치 경로 때문에 오탐되는 일은 없습니다.

검사는 탐지 계열마다 탐지, 검사 후 정상, 아직 검사 시점 아님 세 가지 중 하나로 답합니다. 실제 표본만 누적치를 바꾸며, 실행되지 않은 검사는 이전 탐지를 지우지 않고, 아예 실행할 수 없었던 검사는 정상이 아니라 스캐너 상태 문제로 보고됩니다.

확정 탐지 뒤의 동작. Force Quit On Detection이 켜져 있으면(Standard·Strict 프리셋 기본값) 확정된 주입 모듈은 콜백 유예 시간이 지난 뒤 게임을 종료합니다. OZeroSecurityReceiver나 콜백에서 로그만 남겨도 마찬가지이며, Windows에서는 네이티브 모듈 감시가 직접 종료합니다. 인젝션을 게임 코드에서만 처리하려면 Force Quit On Detection을 끄고(Low 프리셋) Receiver에서 대응하세요.

Pro 빌드. Pro 빌드에 서명 없는 모듈이 주입되면 라이선스 서버가 다음 온라인 확인(약 4분 주기)을 거부합니다. 이 거부는 Build Integrity 실패라서 Force Quit On Detection 설정이나 콜백과 관계없이 항상 게임을 종료합니다. 정상 모듈이면 포털에서 허용하세요.

Pro: 포털에서 관측 모듈 허용/차단

enableServerWhitelist를 켜면 Pro 빌드는 포털의 프로젝트별 결정과 OZero의 전역 결정을 합친 서명 목록을 받습니다. 시작 시 수신하고, 설정한 주기로 다시 받으며, 승인·차단 목록이 만료되기 전에도 자동으로 갱신합니다.

• 목록은 라이선스에 바인딩되고 라이선스 서버 키(Ed25519)로 서명됩니다. SDK는 활성화에 이미 신뢰하는 같은 공개키로 검증합니다.
• 검증된 목록은 기기에 보관되어 오프라인 시작에도 적용됩니다. 검증에 실패한 목록은 받아들여지지 않으며, 탐지 자체가 꺼지는 일은 없습니다.
• 한 번도 접속하지 않은 기기는 빌드에 포함된 baseline 신뢰 목록만 씁니다. 이후 갱신 시 서버에 닿으면 목록을 받아 캐시합니다.
• OZero가 차단한 모듈을 우리 프로젝트가 허용했다면, 포털의 OZero 판정과 우리 프로젝트 판정이 다를 때 설정이 어느 쪽을 따를지 정합니다(기본값: OZero). 우리 프로젝트가 차단한 모듈은 언제나 차단됩니다.
• ABI 21 SDK는 Windows·macOS 모듈의 코드 서명 주체(예: Discord Inc.)도 함께 보고하므로 포털이 인증서 지문 옆에 회사 이름을 보여 줍니다. iOS·Android 모듈에는 읽을 수 있는 서명자가 없습니다.
• 탐지기가 보았지만 아직 조치하지 않은 모듈은 포털 관측된 모듈 목록에 출처 종료 전 후보로 올라옵니다. 플레이어가 영향을 받기 전에 허용이나 차단을 정할 수 있습니다. 기기에서 코드 서명 인증서 체인이 검증된 모듈은 신뢰 서명으로 표시되며, 이런 모듈은 identity 규칙이 자동으로 종료하지 않고 판정을 기다립니다.

스캐너 사용 불가 (abort code 0x15)

네이티브 스캐너 자체가 동작할 수 없으면(설정 적용 실패, 반복되는 네이티브 스캔 오류, managed/native 계약 불일치) SDK는 ModulationType.InjectionScannerUnavailable(값 10, abort code 0x15, message key injection_scanner_unavailable)을 보고하고 ForceQuitOnDetection이 꺼져 있어도 게임을 종료합니다. 공격 탐지가 아니라, 조용히 고장 난 스캐너가 게임을 무방비로 두는 것을 막기 위한 동작입니다. 플레이어에게는 OZ-SEC-15 같은 지원 코드를 보여 주고 로그에는 abort code를 남기세요.

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++ 힙에 저장되어 메모리 스캐너나 메모리 편집기로는 메모리를 스캔해도 찾을 수 없습니다. 타입 이름만 바꾸면 되고 나머지 코드는 그대로 동작합니다.

예시 코드

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 레퍼런스에서 모든 클래스, 메서드, 설정 옵션을 자세히 확인해 보세요.

문제 해결 레퍼런스

OZero 다이얼로그가 표시되었거나 앱이 보안 사유로 종료된 경우, 먼저 화면이나 로그에 표시된 코드를 확인하세요. 지원 코드를 기준으로 대략적인 원인을 찾고, 필요한 경우 아래 문제 해결 순서에 따라 로그와 설정을 점검하면 됩니다.

지원 코드

지원 코드는 OZero 다이얼로그와 로그에 표시되는 짧은 확인 코드입니다. 플레이어가 이 코드를 고객 지원팀에 전달하면, 개발팀이나 QA 담당자가 어느 영역을 먼저 확인해야 하는지 빠르게 파악할 수 있습니다. OZ-SEC-*는 보안 이벤트가 보고되었음을 의미하고, OZ-MV-*는 온라인 검증이나 관리형 검증 상태를 확인해야 함을 의미합니다.

종료 코드

종료 코드는 로그, 콜백, OZ-SEC-* 지원 코드에서 공통으로 사용하는 안정적인 분류입니다. 플레이어에게 세부 근거를 노출하지 않으면서, 개발팀이 어떤 보호 영역에서 반응했는지 확인할 수 있게 해 줍니다.

API 필드와 callback 예시는 OZeroAbortCode & Event Messages를 참고하세요.

문제 해결 절차