보안

이해하기

스토브 Security SDK는 게임 앱의 변조·해킹 시도를 탐지하고 주요 메모리 데이터를 보호하는 보안 서비스예요.
모바일(Android/iOS) 환경을 위한 스토브 Mobile Security SDK와 PC(Windows) 환경을 위한 스토브 PC Security SDK로 구성돼요.

SDK 종류

두 가지 SDK는 제공 환경과 탐지 방식이 다르므로, 게임 플랫폼에 맞는 SDK를 선택해야 해요.

주요 보안 기능

두 SDK가 공통으로 제공하는 핵심 보안 기능은 아래와 같아요.

추가 탐지 기능

• Mobile SDK 스토브 Mobile Security SDK는 모바일 환경에 특화된 추가 탐지 기능을 제공해요.

  기능	설명
  Native 파일 암호화	Android 환경의 Native 파일(.so 등) 암호화 지원. Unreal Engine, Unity 등의 게임 엔진 암호화 지원
  악의적인 환경 탐지	Rooting/Jailbreak, Security Folder(삼성 보안폴더), Dual App(Parallel Space) 등 악의적 실행 환경을 탐지
  Emulator 환경 탐지	Emulator 환경에서의 App 실행 여부를 탐지
  Macro(Auto Clicker) 탐지	게임에서 의도하지 않은 Touch 자동화를 탐지 (SDK 2.7.0 이상)
  VPN 환경 탐지	디바이스가 VPN에 연결되어 있는지 탐지
  USB/Wifi Debugging 설정 탐지	개발자 옵션의 USB/Wifi Debugging 연결 설정이 Enable 되어 있는지 탐지
  주요 데이터 암호화	앱에서 사용하는 Asset File을 암호화하고 사용할 때 실시간으로 복호화 (SDK 2.6.0 이상). 앱 실행 시 실시간으로 사용(생성)되는 File을 실시간으로 암/복호화
  패킷 탈취 탐지 (지원예정)	Proxy 설정 여부를 통한 패킷 탈취 환경을 탐지

• PC SDK 스토브 PC Security SDK는 PC 환경에 특화된 추가 탐지 기능을 제공해요.

  기능	설명
  DLL 무결성 감시	외부 프로그램 또는 공격적인 디버거/조작 도구에 의해 DLL이 강제로 Detach(Unload) 또는 훼손되는지 실시간으로 감시. 설정된 "타깃 DLL 목록" 기준으로 정상 로드 여부를 지속적으로 점검
  드라이버 무결성 감시	커널 모드에서 동작하는 당사 드라이버가 외부 프로세스나 툴에 의해 실행·중지·언로드되는 시도를 감지. 외부에서 드라이버를 강제 언로드하거나 서비스 상태를 조작할 경우 탐지
  매크로/자동화 탐지	이용자의 입력 데이터(마우스, 키보드, 터치 입력 포함)를 수집하여 서버로 전송해 분석. 최적화된 데이터 포맷을 사용하여 효율적인 전송을 수행

지원범위

SDK 사용 요청

스토브 Mobile Security SDK 및 PC Security SDK를 전달받기 위해서는
퍼블리싱기술팀(sgs_gsd_t@smilegate.com)에 문의하면 App에 맞는 설정 파일 제작 후 Sample 및 Plugin을 전달해 드려요.

연동 가이드

서비스 구성도

보안 SDK의 전체 서비스 구성도는 아래와 같아요.

• Game Client Security Module을 통해 getChecksum()을 호출해 무결성 데이터를 생성하고, Token과 함께 Game Server로 전달해요.
• Game Server 수신한 Checksum과 Token을 Security Server에 전달해 무결성을 검증해요.
• Security Server Token Server에서 Token을 검증하고, 검증 결과(Checksum Verification Result)를 Log Server에 기록해요.
• CDN Module Management를 통해 보안 SDK를 업데이트해요.
• Actor Abuser Management와 Checksum Management를 통해 어뷰저를 관리해요.

앱 변조 탐지 결과는 보안서버에서 검증 후 실시간 대시보드로 제공되어 게임 운영자가 수동적 이용자 제재를 할 수 있어요.

App 무결성 검증

클라이언트 보안 모듈에서 생성된 Checksum Data의 검증을 위한 Rest API Server예요.
Security Server 방화벽 정책에 따라 Live server는 ACL 정책 없이 자유롭게 데이터 통신이 가능하며,
Sandbox Server는 Game Server의 IP로 ACL 정책을 적용해 운영해요.

• 무결성 검증 API는 실시간으로 검증 결과를 알려주는 방식이 아니라, 서버에서 데이터만 전달받은 후 결과는 무조건 성공으로 리턴돼요. 변조 여부는 로그를 이용해 확인하는 방식이에요.
• 해당 API 호출이 실패(connect 등)하더라도 게임 진행에 영향을 주지 않기 위해서 비동기 방식으로 처리해야 해요.
• ChecksumData는 기본적으로 게임의 중요 프로토콜(게임입장, 로비이동 등)에 포함하여 프로토콜을 우회하지 못하도록 연동하는 것을 권장해요.
• 별도의 프로토콜을 이용해 Client로부터 ChecksumData를 전달한다면, 반드시 게임서버에서 일정시간 후에 ChecksumData가 정상적으로 전달되었는지 확인하여 로그를 기록해야 해요(보안 SDK 우회 이용자 확인).

• Request Body 주요 파라미터 구성
  • packageName(게임 패키지명)
  • gameVersion(게임 버전)
  • userInfo(이용자 정보)
  • checksumData(클라이언트에서 전달받은 checksum값)

보안변수

스토브 Security SDK V2 보안변수 모듈은 메모리에 올라간 게임의 주요 데이터를 보호하는 보안 변수를 제공해요.
보안 변수를 적용함으로써 게임 코드의 주요 메모리에 대한 악의적 검색과 조작을 무력화할 수 있어요.

지원되는 변수 타입은 일반적인 데이터형과 같은 의미를 가지며, GvtWrapper.h를 포함시키면 자동으로 정의돼요.
적용 순서는 SDK 모듈 추가 후 API를 연동하는 두 단계로 구성돼요.

보안 설정 상태 조회

스토브 서비스 이용자의 계정 보안 설정 상태 정보를 조회하는 API예요.
로그인 차단, OTP 설정, 지정 PC 사용 여부 등 이용자의 계정 보안 설정 상태를 확인할 수 있어요.
조회한 보안 설정 정보를 기준으로 인게임 내 보안 상태 아이콘 표기, 보안 등급에 따른 혜택 제공 및 기능 제어 로직을 구현할 수 있어요.

• 기본정보: GET /v1.0/security/setting
• Host: http://api.onstove.com/auth-secure (LIVE) / http://api.gate8.com/auth-secure (SANDBOX)

SDK 실행 확인

개발하기

Mobile Security SDK

사전 준비

Mobile Security SDK 연동 전, 아래 항목을 미리 확인하고 준비해 주세요.

개발 흐름

Mobile Security SDK의 클라이언트 ↔ 서버 동작 흐름은 아래와 같아요. 클라이언트가 무결성 데이터를 생성한 후 게임 서버를 거쳐 보안 서버로 전달되는 구조예요.

흐름 단계는 크게 네 가지로 나뉘어요.

1. 초기화 (SUI) : 스토브 로그인 후 발급받은 이용자 식별자를 SDK에 전달해 보안 SDK 이용자 정보를 설정해요. : Detection Log와 Error Log를 전송할 때 이 정보가 포함돼요.
2. Scan 시작 (Start) : 게임 버전(versionName)을 입력해 SDK 업데이트와 Scan 기능을 동작시켜요. : 호출 후 SDK는 백그라운드에서 변조 탐지를 시작해요.
3. 무결성 데이터 생성 (GCS) : Start 호출 약 2초 후 GCS를 호출하면 무결성 데이터(ChecksumData)가 반환돼요. : 이 데이터는 게임의 중요 프로토콜(게임 진입, 로비 입장 등)에 포함해 게임 서버로 전송해야 해요.
4. 서버 측 검증 : 게임 서버는 수신한 ChecksumData를 무결성 검증 API Server(/api/checksums/verify)로 전달해요. : 응답은 항상 success로 리턴되며, 실제 탐지 결과는 보안 서버의 Log를 통해 확인해요.

트러블슈팅

연동 과정에서 자주 마주치는 케이스와 권장 처리 방법이에요.

샘플 코드

각 플랫폼별 SDK 적용 흐름의 핵심 호출 부분이에요.

// 1. SDK 인스턴스 생성
private static RHNativeWrapper rhNativeWrapper = new RHNativeWrapper();

// 2. SDK 초기화 (Stove SDK 로그인 후 발급받은 사용자 식별자 전달)
void startSecuritySDK() {
    rhNativeWrapper.SUI("Stove SDK 사용자 식별자");

    // AndroidManifest.xml의 versionName 입력
    PackageInfo pi = getPackageManager().getPackageInfo(getPackageName(), 0);
    rhNativeWrapper.Start(this, getApplicationContext().getAssets(), pi.versionName, null);
}

// 3. 무결성 데이터 생성 (Start 후 약 2초 뒤 호출)
String getChecksumData() {
    return rhNativeWrapper.GCS();
}

// 4. App 생명주기 연동
@Override
protected void onPause() {
    super.onPause();
    rhNativeWrapper.Pause();
}

@Override
protected void onResume() {
    super.onResume();
    rhNativeWrapper.Resume();
}

// 5. 사용자 터치 데이터 (SDK 2.7.0+, Macro 탐지)
@Override
public boolean dispatchTouchEvent(MotionEvent event) {
    rhNativeWrapper.STE(event);
    return super.dispatchTouchEvent(event);
}

Packaging (Android)

사전 준비

Android 빌드 결과물에 보안 SDK를 적용하려면 RHAPKTool을 통한 Packaging 작업이 필요해요.

개발 흐름

Packaging은 packaging.ini 설정과 packaging.bat 실행 두 단계로 동작해요.

1. packaging.ini 설정 : [config], [package], [apksign], [filesize], [assetencrypt] 섹션별로 경로·옵션 설정. : 게임 엔진 타입(Native / Unity3D / Unreal / Cocos2d), keystore, 서명 옵션, 파일 사이즈 체크, asset 암호화 여부 등을 입력해요.
2. packaging.bat 실행 : rhapktool -package .\packaging.ini 명령으로 Repackaging 수행. : zipAlign → apksigner 순으로 서명까지 자동 처리돼요.
3. Packaging 적용 확인 : 결과 APK 내부에 assets/sdata 폴더가 생성되고 보안 SDK 파일들이 추가된 것을 확인해요.
4. Checksum 등록 (관리 페이지) : Packaging이 완료된 파일을 관리 페이지의 Security SDK 메뉴에서 Drag & Drop으로 업로드하고 Registration을 진행해요.

트러블슈팅

샘플 코드

[config]
;0 = apk, 1 = unity, 2 = unreal4, 3 = coco2
type=1

input=C:\Release\app-live-release.apk
manifest_file=AndroidManifest.xml
smali_jar=smali-2.5.2.jar
baksmali_jar=baksmali-2.5.2.jar
java_bin=C:\Program Files\Android\jdk\microsoft_dist_openjdk_1.8.0.25\bin\java.exe
backup=1

[package]
OriAPKPath=C:\Release\app-live-release-rh.apk
NewAPKPath=C:\Release\app-live-release-pack.apk
SecurityPath=C:\Release\securitymodule

;0[APK Mode], 1[AAB Mode]
PackagindMode=0
MinSdkVersion=19

[apksign]
Use=1
KeyStorePath=C:\keystore\keystore.jks
keyStorePass=hohoho
KeyAliasName=Testkey
KeyAliasPass=!a1s2d3f4g5
AdtToolPath=C:\Users\user\AppData\Local\Android\Sdk\build-tools\30.0.2

[filesize]
Use=1
filename001=.so
filename002=.dex
filename003=AndroidManifest.xml

[assetencrypt]
Use=0
filename001=test/text.txt
filename002=test/text.xml
filename003=test/test100.dat

PC Security SDK

PC Security SDK는 SDK 모듈 추가 → 클라이언트 연동 → Server 연동 3단계로 적용해요.

• SDK 모듈 추가 : 개발환경(Windows Native / Unreal Engine / Unity3D)에 맞춰 PC Security SDK 다운로드 및 적용
• 클라이언트 연동 : Game Client에 STOVE PC Security SDK에서 제공하는 API 연동 작업 진행. : PC Security SDK는 독립된 형태라 필요한 기능만 선택적으로 적용 가능
• Server 연동 : Client에서 생성된 App 무결성 데이터를 Security Server로 전달하기 위한 Server Side REST API 연동

사전 준비

PC Security SDK 연동 전, 아래 항목을 확인해 주세요.

• 폴더 구조 예시 DLL과 .SPSS 폴더는 게임 exe 기준 상대 경로 어디에 두어도 되지만, 반드시 같은 폴더 안에 함께 위치해야 해요. 일반적인 폴더 구조 예시는 아래와 같아요.
  text

  GameProject/
  ├── build/
  │   ├── Game.exe
  │   └── data/                       ← 폴더명 자유
  │       ├── RHCoreSDK.dll
  │       └── .SPSS/                  ← DLL과 동일 폴더 필수
  │           ├── xxxx
  │           └── xxxx
  ├── pc_security_sdk/
  │   ├── RHCoreSDK.dll
  │   └── .SPSS/
  │       ├── xxxx
  │       └── xxxx
  ├── source/
  └── header/
      └── RHCoreSDKWrapper.h
  

• 환경별 SDK 모듈 추가 절차 각 개발 환경에 맞춰 SDK 모듈을 추가하는 절차는 아래와 같아요. API 연동 호출 순서(Initialize → SUI → Start → GCS → Shutdown)는 모든 환경에서 동일해요.

  환경	절차
  Windows Native	1. RHCoreSDKWrapper.h를 프로젝트 소스 트리에 추가하고 #include로 사용 2. RHCoreSDK.dll + .SPSS 폴더를 게임 exe 기준 상대 경로(예: data/)에 배치 3. RHCoreSDKWrapper.h의 RHCORESDKDLLPATH 매크로를 실제 경로(예: .\\data\\RHCoreSDK.dll)에 맞춰 수정
  Unreal Engine	1. 전달된 보안 SDK의 StoveSecuritySDKPlugin 폴더를 프로젝트의 Plugins 폴더로 복사 2. Unreal Editor 종료 후 재시작 → "Missing Modules" 다이얼로그에서 "예" 선택해 자동 리빌드 3. Visual Studio 프로젝트 새로고침(파일 → Visual Studio 프로젝트 새로고침) 4. 솔루션 탐색기에서 Plugins/StoveSecuritySDKPlugin 포함 여부 확인
  Unity3D	1. Unity 메뉴: Assets → Import Package → Custom Package... 선택 2. 전달된 StovePCSecuritySDK.unitypackage 파일 선택 후 모든 파일 import 3. Import 후 폴더 확인: Assets/Editor, Assets/Plugins/Windows/x86_64/RHCoreSDK.dll, Assets/Scripts, Assets/Stove/SDK/Security

개발 흐름

PC Security SDK는 Visual Studio·Unreal·Unity 환경 모두 동일한 호출 흐름을 가져요.

각 호출 단계 의미는 아래와 같아요.

1. Initialize : API 사용을 위한 초기화 작업. 보안 SDK DLL의 경로를 입력받아 로드해요. : Initialize와 Shutdown은 각각 1회만 호출해요.
2. SUI : 이용자 식별자를 SDK에 전달해 Detection Log와 Error Log에 이용자 정보를 포함시켜요. : 이용자 로그인 ID, 이메일과 같이 이용자를 직접 특정할 수 있는 정보는 입력하지 않아요.
3. Start : 게임 버전과 패키지명을 입력해 SDK를 초기화하고 Scan을 시작해요. : 게임 로딩 단계 초반에 호출하는 것을 권장해요.
4. GCS (Generate Checksum) : App의 무결성 데이터를 생성해 반환해요. : Start 호출 후 약 2초 뒤 호출하고, 최초 1회만 호출해요. : 게임 종료 후 다시 시작 화면으로 돌아가는 경우 재호출하지 않아도 돼요.
5. Shutdown : API 사용을 마무리하고 정리 작업을 수행해요.

트러블슈팅

샘플 코드

#include "RHCoreSDKWrapper.h"

// 게임 시작 시
if (!RHCoreSDK::Initialize()) {
    MessageBox(hWnd, L"RHCoreSDK.dll 로드 실패", L"Error", MB_OK | MB_ICONERROR);
    // SDK 로드 실패 처리
}

std::string user_info    = "tester";
std::string game_version = "5.0.0";
std::string game_package_name = "com.stove.mobilegamesecurity";

// 사용자 정보 설정
RHCoreSDK::SUI(user_info.c_str());

// 보안 SDK 시작
RHCoreSDK::Start(game_version.c_str(), game_package_name.c_str());

// 무결성 데이터 생성 후 서버 전송 (Start 후 약 2초 뒤, 게임 진입/로비 이동 시점)
const char* checksum = RHCoreSDK::GCS();
// → checksum을 게임 프로토콜에 포함하여 게임 서버로 전송

// 게임 종료 시
RHCoreSDK::Shutdown();

보안변수(Ghost Variable) V2

사전 준비

보안변수 V2 모듈은 메모리 영역의 주요 데이터를 보호하는 별도 모듈로, 보안 SDK와 함께 사용할 수 있어요.

• SDK 모듈 추가 (환경별) 플랫폼별 library 파일을 프로젝트에 포함하고, wrapper 파일을 적용 소스에 추가해요.

  환경	절차
  Android Native	ABI별 libGvt.so를 jniLibs(또는 동일 역할의) 디렉터리에 배치, wrapper 파일을 적용 소스에 추가
  iOS	Gvt.framework를 프로젝트에 추가하고 wrapper 파일을 import
  Windows Native	Gvt.dll을 게임 exe 기준 상대 경로에 배치, wrapper 파일을 프로젝트에 추가
  Unity	1. library를 Assets\Plugins 폴더에 (없다면 생성) 복사 2. GvtWrapper.cs를 소스에 추가 3. 보안변수 OFF 옵션 사용 시: [File] → [Build Settings] → [Player Settings] → [Other Settings] → [Scripting Define Symbols]에 NO_USING_GHOST_VAR_TYPE 입력

Windows IL2CPP 정적 연동 (선택)

STOVE PC Security SDK는 기본적으로 Gvt.dll을 사용하는 동적 연동 방식을 제공해요.
Windows IL2CPP 환경에서는 Gvt.lib를 GameAssembly.dll에 정적으로 링크하여 Gvt.dll 없이 배포할 수 있어요.

지원 환경

• Unity Windows x64
• IL2CPP
• Architecture = x86_64

사전 준비

1. Unity Hub → Windows Build Support (IL2CPP) 설치
2. Player Settings → Windows → Scripting Backend = IL2CPP
3. Architecture = x86_64 설정
4. Build Settings에 Scene 등록

프로젝트 구성

Assets/Stove/Plugins/Windows/
├── Gvt.lib
└── GvtBridge.cpp

Assets/Editor/
└── GvtIl2CppLinker.cs

Assets/Stove/SDK/Security/
└── GvtWrapper.cs

연동 절차

1. Gvt.lib를 프로젝트에 추가해요.
2. GvtBridge.cpp를 추가하여 GVT 심볼이 링크되도록 설정해요.
3. GvtIl2CppLinker.cs를 추가하여 IL2CPP 빌드 시 정적 라이브러리가 링크되도록 설정해요.
4. Plugin Importer를 설정해요.
5. GvtWrapper.cs를 수정하여 DllImport("__Internal")를 사용하도록 변경해요.
6. Callback 등록 시 Delegate가 GC 대상이 되지 않도록 관리해요.
7. Windows IL2CPP Build 결과물에서 동작을 검증해요.

Plugin Importer 설정

GvtWrapper.cs 수정

Windows IL2CPP 환경에서는 Native 함수를 __Internal을 통해 호출하도록 수정해야 해요.

#if UNITY_STANDALONE_WIN && !UNITY_EDITOR
[DllImport("__Internal", CallingConvention = CallingConvention.Cdecl)]
public static extern IntPtr GVTGetFL(ref int size);
#endif

또한 LoadLib() 내부에서 Windows IL2CPP Build 시 GVTGetEFL()을 사용하도록 수정해야 합니다.

빌드 및 검증

1. File → Build Profiles → Windows (IL2CPP) → Build
2. Build 로그에서 Gvt.lib 링크 여부 확인
3. 생성된 exe 실행
4. GVT 정상 로드 여부 확인
5. Callback 정상 동작 여부 확인

제한사항

• Editor Play Mode에서는 Native GVT가 동작하지 않아요.
• Windows IL2CPP Build 결과물에서만 동작해요.
• Gvt.dll 없이 배포가 가능해요.

참고

개발 흐름

보안변수 V2의 적용은 두 단계로 구성돼요.

1. SDK 모듈 추가 플랫폼별 library 파일과 wrapper 파일을 프로젝트에 포함해요.
2. API 연동 (Option Interface) Option Interface 함수를 통해 SDK 동작 옵션을 설정한 후, 코드 내에서 일반 데이터 타입처럼 보안 변수를 사용해요.

• Option Interface 4종

  함수	역할
  NO_USING_GHOST_VAR_TYPE	보안변수 모듈의 변수보호 기능을 OFF하는 매크로. #define NO_USING_GHOST_VAR_TYPE으로 적용. Unity는 Scripting Define Symbols에 설정
  SetSwapLinkNum	변수 저장소 개수 설정 함수. 3～100 사이 값 설정 가능, 미설정 시 기본값으로 설정
  SetMemRolling	변수 저장소 메모리 재할당 함수. 미설정 시 기본값으로 설정
  SetModEventCallbackObj	변수 값 변조 탐지 시 게임 코드의 Callback 호출 함수. 미설정 시 변조 탐지가 발생해도 아무 이벤트가 발생하지 않음

• 명시적 캐스팅이 필요한 경우 보안 변수 객체를 사용할 때 아래 세 가지 케이스에서는 명시적 캐스팅이 필요해요.

  ① 문자열 출력 포맷과 같이 사용할 때

  cpp

  printf("gUInt = %d\n", (int)gUInt);
  

  ② 상수값 뒤 연산자 사용 시

  cpp

  CGwInt gnInt;
  gnInt = 100;
  int nTemp = 5 + (int)gnInt;
  

  ③ 타입이 다른 보안 변수 객체 간 변환

  cpp

  CGwInt gnInt;
  gnInt = 100;
  
  CGwShort gnShort;
  gnShort = (short)gnInt;
  

  {.is-info}

트러블슈팅

샘플 코드

#include "GvtWrapper.h"

class CGhostVarModHandler : public IGvtModEventHandler
{
public:
    CGhostVarModHandler() {};
    virtual ~CGhostVarModHandler() {};

public:
    void ModEventCallback(G_DOUBLE a_dOrg, G_DOUBLE a_dMod)
    {
        printf("[*modified-callback*] org = %f, mod = %f \n", a_dOrg, a_dMod);
    }
};

void GvtInit()
{
    if (!CGvtWrapper::_LoadLib())
    {
        printf("fail to load lib");
        return;
    }

    static CGhostVarModHandler GhostVarModHandler;
    CGvtWrapper::_SetModEventCallbackObj(&GhostVarModHandler);
    CGvtWrapper::_SetSwapLinkNum(50);
}

자주 묻는 질문