주요 API 설명

AppGuard SDK iOS API Reference

---

문서 개요

이 문서는 nProtect AppGuard iOS SDK의 API 사용 방법을 설명합니다.

제공하는 API 목록

---

API 이름	설명
void APPGUARD_INIT(APPGUARDAPPCALLBACK)	AppGuard 구동을 시작하는 함수입니다.
void APPGUARD_SET_USER_ID(const char* userId)	정책 위반 탐지 시 로그 서버에 기록되는 사용자의 ID를 설정하는 함수입니다.
void APPGUARD_SET_CERTIFICATION_ID(const char* clientId, int retryTimeout)	서버 인증에 사용되는 사용자 식별 키와 서버 인증 재시도 시간을 설정하는 함수입니다.
void APPGUARD_SET_RESERVED1(int value, int option)	AppGuard의 추가 전용 기능을 수행하는 함수입니다.
void APPGUARD_SET_RESERVED2(const char* url)	서버 인증(Server-Side Authentication) 서버의 주소를 설정하는 함수입니다.
void APPGUARD_START_CUSTOMMACROMODE	Custom Macro 규칙을 적용하여 탐지를 시작하는 함수입니다.
void APPGUARD_STOP_CUSTOMMACROMODE	Default Macro 규칙을 적용하여 탐지를 시작하는 함수입니다.

APPGUARD_INIT

void APPGUARD_INIT(PAPPGUARDAPPCALLBACK)

APPGUARD_INIT 함수는 AppGuard를 초기화하는 함수로, 앱이 실행될 때 가장 먼저 호출하는 것을 권장합니다.

매개변수	설명
PAPPGUARDAPPCALLBACK	AppGuard SDK로부터 결과를 전달받는 콜백 함수

이 함수는 다음 예시와 같이 AppDelegate.m 또는 AppDelegate.mm 파일의 application:didFinishLaunchingWithOptions: 함수 내부에서 호출하는 것이 좋습니다.

AppDelegate.m 또는 AppDelegate.mm

#import <AppGuardCore/AppGuard.h>
#import <AppGuardCore/AppGuardDefine.h>

// AppGuard SDK로부터 결과를 전달받을 콜백 함수 정의
static void APPGUARDAPPCALLBACK(int type, int code, const char* desc)
{
   // ...
}

// 앱이 시작되는 시점
- (Bool)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   APPGUARD_INIT(APPGUARDAPPCALLBACK);
}

팁

APPGUARDAPPCALLBACK 함수가 정상적으로 등록되면, AppGuard SDK가 수행한 탐지 내역을 콜백 함수를 통해 확인할 수 있습니다.

APPGUARDAPPCALLBACK

typedef void (*PAPPGUARDAPPCALLBACK)(int type, int code, const char *pData);

APPGUARDAPPCALLBACK 함수는 고객사에서 반드시 구현해야 하는 콜백 함수로, AppGuard 보안 서비스의 동작 과정 및 보안 위반에 대한 이벤트를 수신합니다. 이 함수는 APPGUARD_INIT 함수의 파라미터로 전달되어야 합니다.

매개변수	설명
int type	보안 서비스의 종류 (Event, Report, Kill)
int code	보안 서비스의 정책 종류
const char* desc	보안 위반 행위에 대한 상세 정보

주의

APPGUARDAPPCALLBACK 함수는 반드시 구현하고, APPGUARD_INIT 호출 시 파라미터로 전달해야 합니다.

아래 예제와 같이 적용하면 APPGUARDAPPCALLBACK 함수에서 AppGuard SDK로부터 전달받은 결과를 처리할 수 있습니다.

static void APPGUARDAPPCALLBACK(int type, int code, const char* desc) {
   if (type == APPGUARD_TYPE_EVENT) {
      if (code == APPGUARD_EVENT_INITIALIZED) {
         // 엔진 초기화가 완료되었습니다.
      } else if (code == APPGUARD_EVENT_STOP) {
         // 엔진이 중지되었습니다.
      }
   } else if (type == APPGUARD_TYPE_DETECT) {
      if (code == DETECT_IOS_INVALID_EXECUTION_FILE) {
         /**
          * 원본 실행 파일의 변조가 탐지되었습니다.
          * desc : 탐지된 정보
          */
      } else if (code == DETECT_IOS_DEVELOPMENT_BUILD) {
         /**
          * AppStore에서 배포되지 않은 실행 상태가 탐지되었습니다.
          * desc : 탐지된 정보
          */
      }
   } else if (type == APPGUARD_TYPE_ERROR) {
      if (code == APPGUARD_ERROR_APPGUARD_INIT) {
         /**
          * 엔진 초기화에 실패하였습니다.
          */
      }
   } else if (type == APPGUARD_TYPE_S2AUTH_CALLBACK) {
      if (code == APPGUARD_TYPE_CSAUTH_SUCCESS) {
         /**
          * 서버 인증 작업이 성공하였습니다.
          * desc 파라미터로 전달되는 서버 인증용 아이디를 사용하여 게임서버에서 재검증 작업을
          * 수행하시기 바랍니다.
          *
          * desc : 서버 인증용 아이디 (UniqueClientID)
          */
      } else if (code == APPGUARD_TYPE_CSAUTH_RETRY) {
         /**
          * 서버 인증 작업을 진행 중입니다.
          * 무시하셔도 됩니다.
          */
      } else if (code == APPGUARD_TYPE_CSAUTH_FALSE) {
         /**
          * 서버 인증 작업이 실패하였습니다.
          * desc 파라미터로 전달되는 서버 인증용 아이디를 사용하여 게임서버에서 재검증 작업을
          * 수행하시기 바랍니다.
          * 서버 인증 작업이 실패한 사유가 클라이언트의 네트워크 문제일 수 있으므로
          * 게임서버를 통한 재검증 작업을 꼭 진행하시기 바랍니다.
          */
      }
   } else if (type == APPGUARD_TYPE_KILL) {
      /**
       * 탐지 내용이 정책에 의해 kill 옵션으로 설정되어 있는 경우 통지하고, 강제 종료를 요청합니다.
       * 해당 메시지가 감지되면 앱을 강제 종료해야 합니다.
       * 종료 방식은 메시지 창을 통한 통보 후 앱을 종료하는 것을 권장합니다.
       */
   }
}

APPGUARD_SET_USER_ID

void APPGUARD_SET_USER_ID(const char* userId)

APPGUARD_SET_USER_ID 함수는 AppGuard 정책 위반 탐지 시 로그 서버에 기록할 사용자의 ID를 설정할 수 있습니다.

매개변수	설명
const char*	로그 서버에 기록할 사용자의 ID

아래 예시와 같이 APPGUARD_SET_USER_ID 함수의 매개변수로 기록할 사용자 ID를 문자열로 설정할 수 있습니다.

#import <AppGuardCore/AppGuard.h>

APPGUARD_SET_USER_ID("user_id");

APPGUARD_SET_CERTIFICATION_ID

void APPGUARD_SET_CERTIFICATION_ID(const char* clientId, int retryTimeout)

APPGUARD_SET_CERTIFICATION_ID 함수는 서버 인증에 사용되는 사용자 식별 키와 서버 인증 재시도 시간을 설정할 수 있습니다.

매개변수	설명
clientId	UniqueClientID 키 포맷을 준수하는 게임 서버에서 생성한 사용자 식별 값
retryTimeout	서버 인증 재시도 허용시간(초)

클라이언트에서 인증 시도한 UniqueClientID는 세션 구분을 위해 서버에서 인증 확인 요청 시 동일한 ID를 사용해야 합니다. UniqueClientID는 반드시 Formatted-Unique-Client-ID 규칙을 준수해야 합니다.
Formatted-Unique-Client-ID의 형식은 UniqueID:TimeStamp:LicenseKey 입니다.

항목	타입	설명
UniqueID	char(40)	사용자 별 SHA1 또는 40자로 구성된 클라이언트 유일 식별 값
TimeStamp	char(13)	UTC 기반의 13자리로 구성된 세션 생성 시간
LicenseKey	string	해당 애플리케이션에 발부된 AppGuard License Key

아래 예시와 같이 APPGUARD_SET_CERTIFICATION_ID 함수의 매개변수로 Formatted-Unique-Client-ID 포맷에 맞게 서버 인증에 사용되는 사용자 식별 값과 서버 인증 재시도 허용시간 값을 설정할 수 있습니다.

#import <AppGuardCore/AppGuard.h>

// UniqueClientID를 인자로 전달
APPGUARD_SET_CERTIFICATION_ID("UniqueID:TimeStamp:LicenseKey", 180

);

정보

만약 UniqueClientID 값을 null로 입력할 경우 AppGuard 내부에서 랜덤한 UniqueClientID를 생성합니다. 생성된 UniqueClientID는 APPGUARD_INIT 호출 시 등록한 APPGUARDAPPCALLBACK 함수를 통해 전달받을 수 있습니다.

서버 인증 재시도 retryTimeout 시간 값의 설정 범위는 0 ~ 180초이며,
0으로 설정 시 재시도를 하지 않습니다.
180으로 설정 시 3분 동안 약 15번의 인증 재시도를 수행합니다.

APPGUARD_SET_RESERVED1

void APPGUARD_SET_RESERVED1(int value, int option)

APPGUARD_SET_RESERVED1 함수는 AppGuard의 추가 기능 수행을 설정하는 함수입니다. 아래 표와 같이 3가지 기능이 있으며, 설정 값에 따라 제공되는 기능이 달라집니다.

항목	값	설명
FUNCTION_MACRO_RESTART	0x10000000	매크로 탐지를 초기화하여 재시작합니다. 이미 매크로 탐지로 진단된 경우라도, 재진단 시 탐지 이벤트를 발생합니다.
FUNCTION_PROXY_DETECTION	0x20000000	현재 디바이스에서 Proxy Host 서버를 사용 중인지 탐지하는 기능을 제공합니다. 해당 기능은 호출할 때마다 1회 검사를 수행합니다. (다중 호출 가능)
FUNCTION_AUTH_REGION	0x30000000	서버 인증에 사용할 인증서버의 국가를 설정할 수 있습니다. 현재 지원되는 국가는 한국과 중국 두 국가이며, 이 메소드의 옵션 값으로 국가를 설정할 수 있습니다. option = 0 : 한국 인증 서버 option = 2 : 중국 인증 서버

아래 예시와 같이 APPGUARD_SET_RESERVED1 함수 내의 매개변수 값에 따라 매크로 탐지를 초기화하고 재시작하거나, Proxy Host 탐지 기능을 제공받거나, 서버 인증할 국가를 설정할 수 있습니다.

#import <AppGuardCore/AppGuard.h>

APPGUARD_SET_RESERVED1(FUNCTION_MACRO_RESTART);
...
APPGUARD_SET_RESERVED1(FUNCTION_AUTH_REGION, 0);

APPGUARD_SET_RESERVED2

void APPGUARD_SET_RESERVED2(const char* url)

APPGUARD_SET_RESERVED2 함수는 서버 인증(Server-Side Authentication)을 수행하기 위한 서버 인증의 주소를 설정합니다.

매개변수	설명
url	인증을 시도할 서버 인증(Server-Side Authentication) 서버의 주소

아래 예시와 같이 APPGUARD_SET_RESERVED2 함수의 매개변수로 서버 인증 주소를 URL 포맷에 맞게 추가하여 설정할 수 있습니다.

#import <AppGuardCore/AppGuard.h>

APPGUARD_SET_RESERVED2("https://c4-auth.appguard.co.kr");

주의

서버 인증을 수행하는 APPGUARD_SET_CERTIFICATION_ID 메소드를 호출하기 전에만 이 메소드로 서버의 주소를 변경할 수 있습니다.

APPGUARD_START_CUSTOMMACROMODE

void APPGUARD_START_CUSTOMMACROMODE()

APPGUARD_START_CUSTOMMACROMODE 함수는 Custom Macro 규칙이 적용된 매크로 탐지 기능을 수행합니다.

아래 예시와 같이 APPGUARD_START_CUSTOMMACROMODE 함수를 적용하면 Custom Macro 규칙에 따라 매크로 정책 탐지가 진행됩니다.

#import <AppGuardCore/AppGuard.h>

APPGUARD_START_CUSTOMMACROMODE();

APPGUARD_STOP_CUSTOMMACROMODE

void APPGUARD_STOP_CUSTOMMACROMODE()

APPGUARD_STOP_CUSTOMMACROMODE 함수는 매크로 탐지 기능이 Custom 규칙이 아닌 Default Macro 규칙에 따라 탐지를 시작합니다.

아래 예시와 같이 APPGUARD_STOP_CUSTOMMACROMODE 함수를 적용하면 Default Macro 규칙에 따라 매크로 정책 탐지가 진행됩니다.

#import <AppGuardCore/AppGuard.h>

APPGUARD_STOP_CUSTOMMACROMODE();

경고

CustomMacroMode에 대해 더 자세한 내용이 필요하시면, appguard@inca.co.kr 또는 담당자에게 문의 바랍니다.