Version: Next

Main API Description

AppGuard SDK iOS API Reference

Document Outline

This document is a programming guide that explains how to use the API in the nProtect AppGuard iOS SDK.

API list

API	Description
void APPGUARD_INIT(APPGUARDAPPCALLBACK)	A function that starts AppGuard operation.
void APPGUARD_SET_USER_ID(const char* userId)	A function that sets the User ID recorded on the log server when detecting a policy violation.
void APPGUARD_SET_CERTIFICATION_ID(const char* clientId, int retryTimeout)	A function that sets the user identification key used for Server-Side Authentication and the Server-Side Authentication retry time.
void APPGUARD_SET_RESERVED1(int value, int option)	A function that performs an AppGuard add-only function.
void APPGUARD_SET_RESERVED2(const char* url)	A function that sets the address of the Server-Side Authentication server.
void APPGUARD_START_CUSTOMMACROMODE	A function that is applied as a Custom Macro rule to initiate detection.
void APPGUARD_STOP_CUSTOMMACROMODE	A function that is applied as a Default Macro rule to initiate detection.

APPGUARD_INIT

void APPGUARD_INIT(PAPPGUARDAPPCALLBACK)

APPGUARD_INIT API is recommended to be called at first in the entering point of the App, since the function initializes AppGuard.

Parameter	Description
`PAPPGUARDAPPCALLBACK`	Callback function that receives results from AppGuard SDK

APPGUARD_INIT API is recommended to be called inside the application:didFinishLaunchingWithOptions: function in the AppDelegate.m or AppDelegate.mm file, as shown in the example below.

AppDelegate.m or AppDelegate.mm
#import <AppGuardCore/AppGuard.h>
#import <AppGuardCore/AppGuardDefine.h>

//.  Define the callback function to receive results from the AppGuard SDK as follows
static void APPGUARDAPPCALLBACK(int type, int code, const char* desc)
{
   . . .
}

// App starting point
- (Bool)application:(UIApplication *)application didFinishLaunchingWithOption:(NSDictionary *) launchOptions {
   APPGUARD_INIT(APPGUARDAPPCALLBACK);
}

tip

If the APPGUARDAPPCALLBACK callback function is successfully registered, the detection history performed by the AppGuard SDK can be seen through the registered callback function.

APPGUARDAPPCALLBACK

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

APPGUARDAPPCALLBACK function must be implemented by the customer company. It is a callback function that receives events about the operation process and security violations of the AppGuard security service, and must be sent as a parameter to the APPGUARD_INIT function.

Parameter	Description
`int type`	type of security service - `Event`, `Report`, `Kill`
`int code`	policy type of security service
`const char* desc`	Detailed information about security violation

caution

APPGUARDAPPCALLBACK function must be implemented by the customer company, and be sent as a parameter when APPGUARD_INIT is called.

When applying the APPGUARDAPPCALLBACK function as follows, results can be received from AppGuard SDK through corresponding parameters.

static void APPGUARDAPPCALLBACK(int type, int code, const char* desc) {
   if( type == APPGUARD_TYPE_EVENT ) {
      if( code == APPGUARD_EVENT_INITIALIZED ) {
         //. The engine initialization has been completed.
      } else if( code == APPGUARD_EVENT_START ) {
         //. The engine has been started.
      } else if( code == APPGUARD_EVENT_STOP ) {
         //. The engine has been stopped.
      }
   } else if( type == APPGUARD_TYPE_DETECT ) {
      if( code == DETECT_IOS_INVALID_EXECUTION_FILE ) {
         /**
          * Original execution file modification has been detected.
          * desc : Detected Information
          */
      }
      . . . 
      else if( code == DETECT_IOS_DEVELOPMENT_BUILD )  {
         /**
          * The build execution has been detected that is not deployed to the AppStore.
          * desc : Detected Information
          */
      }
   } else if( type == APPGUARD_TYPE_ERROR ) {
      if( code == APPGUARD_ERROR_APPGUARD_INIT ) {
         /**
          * Engine initialization has been failed.
          */
      }
   } else if( type == APPGUARD_TYPE_S2AUTH_CALLBACK ) {
      if( code == APPGUARD_TYPE_CSAUTH_SUCESS ) {
         /**
          * Server-side authentication process has been succeeded.
          * Proceed re-verification process in the game server 
          * using the ID for server-side authentication delivered from desc parameter.
          *
          * desc : ID for server-side authentication (UniqueClientID)
          */
      } else if( code == APPGUARD_TYPE_CSAUTH_RETRY ) {
         /**
          * Server-side authentication process is under progress.
          * It can be ignored
          */
      } else if( code == APPGUARD_TYPE_CSAUTH_FALSE ) {
         /**
          * Server-side authentication process has been failed. 
          * Proceed re-verification process in the game server
          * using the ID for server-side authentication delivered from desc parameter.
          * Re-verification through the game server is needed
          * since the server-side authentication operation may fail due to a network problem of the client.
          */
      }
   } else if( type == APPGUARD_TYPE_KILL ) {
      /**
       * If the kill option is set for the detection by policy, notify the information and request to terminate the App forcibly.
       * If this message is noticed, the App has to be terminated.
       * It is recommended to terminate the App after notification through the message pop-up.
       */
   }
}

APPGUARD_SET_USER_ID

void APPGUARD_SET_USER_ID(const char* userId)

APPGUARD_SET_USER_ID function can set the User ID to record to the log server in case of policy violation.

Parameter	Description
`const char*`	User ID to record to the log server

User ID to be recorded as a parameter of the APPGUARD_SET_USER_ID function can be registered as a string, as follows.

#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 function sets the user identification key used for Server-Side Authentication and the Server-Side Authentication retry time.

Parameter	Description
`clientId`	UniqueClientID User identification values generated by game servers that comply with key formats
`retryTimeout`	The maximum time value (in seconds) to allow server-side authentication retry

To distinguish between sessions, UniqueClientID that the client attempts to authenticate must use the same ID as the ID when the server requests authentication. UniqueClientId must comply Formatted-Unique-Client-ID rule.
The format of Formatted-Unique-Client-ID is UniqueID:TimeStamp:LicenseKey.

Parameter	Type	Description
`UniqueID`	char(40)	Unique identifier value of client which is composed with SHA1 or up to 40 characters
`TimeStamp`	char(13)	Time when a UTC-based 13-digit session was created
`LicenseKey`	string	AppGuard License Key issued for the Application

User identification value and retry time value for server-side authentication can be set in Formatted-Unique-Client-ID format as APPGUARD_SET_CERTIFICATION_ID function's parameters.

#import <AppGuardCore/AppGuard.h>

// Send UniqueClientID as a factor
APPGUARD_SET_CERTIFICATION_ID("UniqueID:TimeStamp:LicenseKey", 180);

info

If 'null' is entered as a UniqueClientID value, a random UniqueClientID is automatically generated by AppGuard The generated UniqueClientID can be received through the APPGUARDAPPCALLBACK function registered when calling APPGUARD_INIT.

Timeout setting range for server-side authentication retry is 0~180 seconds, and there is no retry if set to 0. If set the range value for the
time value to 180, authentication retries are typically performed about 15 times within 3 minutes.

APPGUARD_SET_RESERVED1

void APPGUARD_SET_RESERVED1(int value, int option)

APPGUARD_SET_RESERVED1 function can currently set additional function of AppGuard. There are three functions as shown in the table below, and the function provision varies depending on the setting value.

Parameter	Value	Description
`FUNCTION_MACRO_RESTART`	0x10000000	Initialize macro detection and restart. Even if it is already detected as macro detection, a detection event is generated upon re-detection.
`FUNCTION_PROXY_DETECTION`	0x20000000	Check whether the device use Proxy Host. This feature inspects 1 time per each it is called(multiple call available).
`FUNCTION_AUTH_REGION`	0x30000000	The country for server-side authentication can be set. Korea and China are currently supported, and the country can be set with option value of each method. `option = 0` : Korea Server-Side Authentication `option = 2` : China Server-Side Authentication

Depending on the parameter values in the APPGUARD_SET_RESERVED1 function, One of the options can be selected; Initialize macro detection and restart, check whether the device use Proxy Host, or set the country to authenticate the server, as follows.

#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)하기 위한 서버인증의 주소를 설정합니다.

Parameter	Description
`url`	The address of the Server-Side Authentication server to attempt to authenticate

When applying as follows, the address of the Server-Side Authentication can be set in URL format as a parameter of APPGUARD_SET_RESERVED2 function.

#import <AppGuardCore/AppGuard.h>

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

caution

The server address can only be changed before calling the APPGUARD_SET_CERTIFICATION_ID method that performs server-side authentication.

APPGUARD_START_CUSTOMMACROMODE

void APPGUARD_START_CUSTOMMACROMODE()

Macro detection policy function is,

The APPGUARD_START_CUSTOMMACROMODE function performs macro detection with the Custom Macro rule.

When applying APPGUARD_START_CUSTOMMACROMODE function as follows, Macro policy detection is performed with the Custom Macro rule.

#import <AppGuardCore/AppGuard.h>

APPGUARD_START_CUSTOMMACROMODE();

APPGUARD_STOP_CUSTOMMACROMODE

void APPGUARD_STOP_CUSTOMMACROMODE()

APPGUARD_STOP_CUSTOMMACROMODE function starts detection by applying the Macro detection function as a Default Macro rule, not a Custom rule.

When applying APPGUARD_STOP_CUSTOMMACROMODE function as follows, Macro policy detection is performed with the Default Macro rule.

#import <AppGuardCore/AppGuard.h>

APPGUARD_STOP_CUSTOMMACROMODE();

warning

If you need more information about CustomMacroMode, please contact appguard@inca.co.kr or the technical supporter in charge.

AppGuard SDK iOS API Reference​

Document Outline​

API list​

APPGUARD_INIT​

APPGUARDAPPCALLBACK​

APPGUARD_SET_USER_ID​

APPGUARD_SET_CERTIFICATION_ID​

APPGUARD_SET_RESERVED1​

APPGUARD_SET_RESERVED2​

APPGUARD_START_CUSTOMMACROMODE​

APPGUARD_STOP_CUSTOMMACROMODE​