メインコンテンツまでスキップ
バージョン: Next

主要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_CUSTOMMACROMODECustom Macroルールとして適用され、検出を開始する関数です。
void APPGUARD_STOP_CUSTOMMACROMODEDefault Macroルールとして適用され、検出を開始する関数です。

APPGUARD_INIT​

void APPGUARD_INIT(PAPPGUARDAPPCALLBACK)

APPGUARD_INIT関数はAppGuardを初期化する関数です。従ってAppは実行する際に一番最初に呼び出すことをお勧めします。

媒介変数説明
PAPPGUARDAPPCALLBACKAppGuard 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パラメータで転送されるサーバ認証用のIDを使用して、ゲームサーバーで再検証作業を
          * 実行してください。
          *
          * desc : サーバ認証用のID (UniqueClientID)
          */
      } else if( code == APPGUARD_TYPE_CSAUTH_RETRY ) {
         /**
          * サーバ認証作業が進行中です。
          * 無視しても大丈夫です
          */
      } else if( code == APPGUARD_TYPE_CSAUTH_FALSE ) {
         /**
          * サーバ認証作業に失敗されました。
          * descパラメータで転送されるサーバ認証用のIDを使用して、ゲームサーバーで再検証作業を
          * 実行してください。
          *サーバー認証作業が失敗さらた理由がクライアントのネットワーク問題による可能性がありますので、
          * ゲームサーバーを通じた再検証作業を必ず進めてください。
          */
      }
   } 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 関数は、サーバー認証に使用されるユーザー識別キーとサーバー認証の再試行時間を設定できます。

媒介変数説明
clientIdUniqueClientID キーフォーマットを遵守するゲーム サーバーで生成されたユーザー識別値
retryTimeoutサーバー認証再試行の許容時間(秒)

クライアントから認証試したUniqueClientIDはセッション区分のためサーバーから認証確認の要請時同一のIDを使用する必要があります。 UniqueClientIdは必ず Formatted-Unique-Client-ID ルールを純水主要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_CUSTOMMACROMODECustom Macroルールとして適用され、検出を開始する関数です。
void APPGUARD_STOP_CUSTOMMACROMODEDefault Macroルールとして適用され、検出を開始する関数です。

APPGUARD_INIT​

void APPGUARD_INIT(PAPPGUARDAPPCALLBACK)

APPGUARD_INIT関数はAppGuardを初期化する関数です。従ってAppは実行する際に一番最初に呼び出すことをお勧めします。

媒介変数説明
PAPPGUARDAPPCALLBACKAppGuard 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パラメータで転送されるサーバ認証用のIDを使用して、ゲームサーバーで再検証作業を
          * 実行してください。
          *
          * desc : サーバ認証用のID (UniqueClientID)
          */
      } else if( code == APPGUARD_TYPE_CSAUTH_RETRY ) {
         /**
          * サーバ認証作業が進行中です。
          * 無視しても大丈夫です
          */
      } else if( code == APPGUARD_TYPE_CSAUTH_FALSE ) {
         /**
          * サーバ認証作業に失敗されました。
          * descパラメータで転送されるサーバ認証用のIDを使用して、ゲームサーバーで再検証作業を
          * 実行してください。
          *サーバー認証作業が失敗さらた理由がクライアントのネットワーク問題による可能性がありますので、
          * ゲームサーバーを通じた再検証作業を必ず進めてください。
          */
      }
   } 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 関数は、サーバー認証に使用されるユーザー識別キーとサーバー認証の再試行時間を設定できます。

媒介変数説明
clientIdUniqueClientID キーフォーマットを遵守するゲーム サーバーで生成されたユーザー識別値
retryTimeoutサーバー認証再試行の許容時間(秒)

クライアントから認証試したUniqueClientIDはセッション区分のためサーバーから認証確認の要請時同一のIDを使用する必要があります。 UniqueClientIdは必ず Formatted-Unique-Client-ID ルールを順守する必要があります。
Formatted-Unique-Client-ID の形式は UniqueID:TimeStamp:LicenseKey です。

項目タイプ説明
UniqueIDchar(40)ユーザー別 SHA1又は 40字で構成されたクライアント唯一の識別値
TimeStampchar(13)UTC基板の 13桁で構成されたセッションが生成された時間
LicenseKeystring該当 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_RESTART0x10000000マクロ検知を初期化して再起動します。 既にマクロ検知で診断されている場合でも、再診断時に検知イベントが発生します。
FUNCTION_PROXY_DETECTION0x20000000現在のデバイスでProxy Hostサーバーを使用しているかを検知する機能を提供します。 この機能は呼び出しごとに1回検査を行います。(多重呼び出し可能)
FUNCTION_AUTH_REGION0x30000000サーバー認証に使用する認証サーバーの国を設定できます。 現在サポートされている国家は、韓国と中国の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();

警告

CustomMacroMode についてもっと詳しい内容が必要の場合、appguard@inca.co.kr 又は担当者にお問い合わせください。