주요 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로 부터 결과를 전달 받는 콜백 함수

APPGUARD_INIT 함수는 아래 예시와 같이 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 didFinishLaunchingWithOption:(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_START ) {
         //. 엔진이 시작 되었습니다.
      } 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_SUCESS ) {
         /**
          * 서버 인증 작업이 성공하였습니다.
          * 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 option으로 설정되어 있는 경우 통지하고, 강제 종료를 요청합니다.
       * 해당 메세지 통지가 감지 되면 APP을 강제 종료 해야 합니다.
       * 종료 방식은 메세지창을 통한 통보 후 앱을 종료 하는 것을 권장합니다.
       */
   }
}

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	해당 Application에 발부된 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	서버인증에 사용할 인증서버의 국가를 설정할 수 있습니다. 현재 지원되는 국가는 한국과 중국 2개의 국가 설정만 지원하며, 해당 메소드의 Option 값 으로 지원되는 국가를 설정할 수 있습니다. 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 함수의 매개변수로 인증할 서버인증(Server-Side Authentication)의 주소를 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()

Macro 탐지 정책 기능이

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

아래 예제와 같이 APPGUARD_START_CUSTOMMACROMODE 함수를 적용 시 Custom Macro 규칙으로 Macro 정책 탐지가 진행됩니다.

#import <AppGuardCore/AppGuard.h>

APPGUARD_START_CUSTOMMACROMODE();

APPGUARD_STOP_CUSTOMMACROMODE

void APPGUARD_STOP_CUSTOMMACROMODE()

APPGUARD_STOP_CUSTOMMACROMODE 함수는 Macro 탐지 기능이 Custom 규칙이 아닌 Default Macro 규칙으로 적용되어 탐지를 시작합니다.

아래 예제와 같이 APPGUARD_STOP_CUSTOMMACROMODE 함수를 적용 시 Default Macro 규칙으로 Macro 정책 탐지가 진행됩니다.

#import <AppGuardCore/AppGuard.h>

APPGUARD_STOP_CUSTOMMACROMODE();

warning

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