Web Application Firewall:Integrasi SDK aplikasi iOS

1. Tambahkan file header

• Untuk versi IDFA, tambahkan pernyataan impor berikut:

  #import <AliTigerTally_IDFA/AliTigerTally.h>

• Untuk versi non-IDFA, tambahkan pernyataan impor berikut:

  #import <AliTigerTally_NOIDFA/AliTigerTally.h> 

2. Konfigurasi penandatanganan data

1. Tetapkan identifier pengguna akhir kustom untuk bisnis Anda. Hal ini memungkinkan Anda mengonfigurasi kebijakan perlindungan WAF dengan fleksibilitas lebih tinggi.

   /**
   * Menetapkan akun pengguna.
   *
   * @param account   Informasi akun.
   */
   - (void)setAccount:(NSString *)account;

   • Parameter:

     • account: Tipe: NSString. String yang mengidentifikasi pengguna. Kami merekomendasikan penggunaan format yang telah didesensitisasi.

   • Nilai kembalian: Tidak ada.

   • Contoh:

     // Untuk pengguna tamu, Anda dapat melewati setAccount dan langsung melakukan inisialisasi. Setelah pengguna masuk, panggil setAccount dan lakukan inisialisasi ulang.
     [[AliTigerTally sharedInstance] setAccount:@"testAccount"];

2. Inisialisasi SDK untuk melakukan pengumpulan data.

   Setiap inisialisasi mengumpulkan informasi perangkat satu kali. Anda dapat memanggil fungsi init lagi untuk melakukan inisialisasi ulang pengumpulan data untuk skenario bisnis yang berbeda.

   Inisialisasi mendukung tiga mode pengumpulan data: lengkap, privasi kustom, dan non-privasi. Mode non-privasi mengecualikan bidang yang terkait privasi pengguna akhir, seperti IDFA dan IDFV.

   Catatan

   Untuk memenuhi persyaratan internal Anda, pilih mode pengumpulan data yang sesuai guna memastikan integritas data. Data yang lebih lengkap meningkatkan deteksi ancaman.

   // Callback inisialisasi. Mengembalikan kode status pemanggilan antarmuka.
   typedef void (^TTInitListener)(int);
   
   /**
    * Menginisialisasi SDK.
    *
    * @param appkey        Kunci.
    * @param options       Parameter opsional.
    * @param onInitFinish  Callback saat inisialisasi selesai.
    * @return Menunjukkan apakah inisialisasi berhasil.
    */
   - (int)init:(NSString *)appkey collectType:(TTCollectType)type options:(NSMutableDictionary *_Nullable)options listener:(TTInitListener _Nullable)onInitFinish;

   • Parameter:

     • appkey: Tipe: NSString. Authentication key SDK Anda.

     • collectType: Tipe: TTCollectType. Mode pengumpulan data. Nilai yang valid:

       Bidang	Deskripsi	Contoh
       TT_DEFAULT	Mengumpulkan semua data.	TT_DEFAULT
       TT_NO_BASIC_DATA	Tidak mengumpulkan data perangkat dasar. Termasuk nama perangkat, versi OS, dan resolusi layar.	TT_NO_X | TT_NO_Y (di mana X dan Y merepresentasikan jenis bidang data yang dikecualikan)
       TT_NO_UNIQUE_DATA	Tidak mengumpulkan data identifier unik. Termasuk IDFV dan IDFA.
       TT_NO_EXTRA_DATA	Tidak mengumpulkan data perangkat yang diperluas. Termasuk informasi Wi-Fi yang terhubung (SSID, BSSID) dan daftar jaringan Wi-Fi terdekat.
       TT_NOT_GRANTED	Tidak mengumpulkan data privasi yang disebutkan sebelumnya.	TT_NOT_GRANTED

     • options: Tipe: NSMutableDictionary. Parameter opsional untuk pengumpulan data. Nilai default adalah nil. Parameter berikut tersedia:

       Bidang	Deskripsi	Contoh
       IPv6	Menentukan apakah akan menggunakan nama domain IPv6 untuk melaporkan informasi perangkat. 0 (default): Menggunakan nama domain IPv4. 1: Menggunakan nama domain IPv6.	1
       Intl	Menentukan apakah akan menggunakan nama domain di luar Tiongkok daratan untuk melaporkan informasi perangkat. 0 (default): Melaporkan ke Tiongkok daratan. 1: Melaporkan ke wilayah di luar Tiongkok daratan.	1
       CustomUrl	Menetapkan nama domain server pelaporan data.	https://cloudauth-device.us-west-1.aliyuncs.com
       CustomHost	Menetapkan host server pelaporan data.	cloudauth-device.us-west-1.aliyuncs.com

       Catatan

       Untuk sebagian besar situs internasional, cukup atur parameter Intl. Untuk melaporkan data ke situs tertentu, atur parameter CustomUrl dan CustomHost. Situs yang tersedia meliputi:

       • Jika Intl diatur ke 0, data dilaporkan ke situs default di Tiongkok (Shanghai): https://cloudauth-device.cn-shanghai.aliyuncs.com

       • Jika Intl diatur ke 1:

         • Situs default adalah Singapura: https://cloudauth-device.ap-southeast-1.aliyuncs.com

         • Indonesia (Jakarta): https://cloudauth-device.ap-southeast-5.aliyuncs.com

         • AS (Silicon Valley): https://cloudauth-device.us-west-1.aliyuncs.com

         • Jerman (Frankfurt): https://cloudauth-device.eu-central-1.aliyuncs.com

         • Tiongkok (Hong Kong): https://cloudauth-device.cn-hongkong.aliyuncs.com

     • listener: Tipe: TTInitListener. Antarmuka callback inisialisasi SDK. Anda dapat menggunakan callback ini untuk menentukan status inisialisasi. Nilai default adalah nil.

       TTCode	Kode	Deskripsi
       TT_SUCCESS	0	Inisialisasi berhasil.
       TT_NOT_INIT	-1	SDK belum diinisialisasi.
       TT_NOT_PERMISSION	-2	Izin iOS yang diperlukan belum diberikan.
       TT_UNKNOWN_ERROR	-3	Terjadi kesalahan sistem yang tidak diketahui.
       TT_NETWORK_ERROR	-4	Terjadi kesalahan jaringan.
       TT_NETWORK_ERROR_EMPTY	-5	Terjadi kesalahan jaringan. Konten yang dikembalikan adalah string kosong.
       TT_NETWORK_ERROR_INVALID	-6	Format respons jaringan tidak valid.
       TT_PARSE_SRV_CFG_ERROR	-7	Gagal mengurai konfigurasi server.
       TT_NETWORK_RET_CODE_ERROR	-8	Gerbang mengembalikan respons kegagalan.
       TT_APPKEY_EMPTY	-9	appkey kosong.
       TT_PARAMS_ERROR	-10	Terjadi kesalahan parameter lainnya.
       TT_FGKEY_ERROR	-11	Terjadi kesalahan perhitungan kunci.
       TT_APPKEY_ERROR	-12	Versi SDK tidak cocok dengan versi appkey.

   • Nilai kembalian: Tipe: int. kode kesalahan. 0 menunjukkan keberhasilan, dan angka negatif menunjukkan kegagalan.

   • Contoh:

     // appkey adalah kunci autentikasi yang diberikan kepada Anda di konsol Alibaba Cloud.
     NSString *appKey = @"xxxxxxxxxxxxxxxxxxxxx";
     // Parameter opsional. Anda dapat mengonfigurasi IPv6 dan pelaporan dari luar Tiongkok daratan.
     NSMutableDictionary *options = [[NSMutableDictionary alloc] init];
     [options setValue:@"0" forKey:@"IPv6"];     // Gunakan IPv4.
     [options setValue:@"0" forKey:@"Intl"];     // Laporkan data dari dalam Tiongkok daratan.
     // [options setValue:@"1" forKey:@"Intl"];  // Laporkan data dari luar Tiongkok daratan.
     // Laporkan data ke wilayah AS (Barat).
     // [options setValue:@"https://cloudauth-device.us-west-1.aliyuncs.com" forKey:@"CustomUrl"];
     // [options setValue:@"cloudauth-device.us-west-1.aliyuncs.com" forKey:@"CustomHost"];
     
     // Pemanggilan inisialisasi mengumpulkan informasi perangkat satu kali. Anda dapat memanggil fungsi init lagi untuk mengumpulkan informasi untuk skenario bisnis yang berbeda.
     // Pengumpulan data lengkap.
     if (0 == [[AliTigerTally sharedInstance] init:appkey collectType:TT_DEFAULT options:options listener:nil]) {
         NSLog(@"Inisialisasi berhasil");
     } else {
         NSLog(@"Inisialisasi gagal");
     }
     
     // Untuk mengumpulkan jenis data pribadi tertentu, gunakan operator "|" untuk menentukan beberapa jenis.
     TTCollectType collectPrivacy = TT_NO_BASIC_DATA | TT_NO_EXTRA_DATA;
     int ret = [[AliTigerTally sharedInstance] init:appkey collectType:collectPrivacy options:options listener:nil];
     
     // Jangan kumpulkan data pribadi.
     int ret = [[AliTigerTally sharedInstance] init:appkey collectType:TT_NOT_GRANTED options:options listener:nil];

3. Hashing data.

   Antarmuka penandatanganan kustom ini melakukan hashing terhadap data input untuk menghasilkan string whash, yang berfungsi sebagai signature kustom. Untuk permintaan POST, PUT, dan PATCH, gunakan badan permintaan sebagai input. Untuk permintaan GET dan DELETE, gunakan URL lengkap. Anda juga harus menambahkan string whash yang dihasilkan ke bidang ali_sign_whash dalam Header permintaan HTTP.

   // Jenis permintaan:
   typedef NS_ENUM(NSInteger, TTRequestType) {
       TT_GET=0, TT_POST, TT_PUT, TT_PATCH, TT_DELETE
   };
   
   /**
    * Melakukan hashing terhadap data signature kustom.
    * @param type  Jenis data.
    * @param input Data yang akan ditandatangani.
    * @return String whash.
    */
   - (NSString *)vmpHash:(TTRequestType)type input:(NSData *)input;

   • Parameter:

     • type: Tipe: TTTypeRequest. Jenis data. Nilai yang valid:

       • GET: Data permintaan GET.

       • POST: Data permintaan POST.

       • PUT: Data permintaan PUT.

       • PATCH: Data permintaan PATCH.

       • DELETE: Data permintaan DELETE.

     • input: Tipe: NSData. Data yang akan ditandatangani. Masukkan badan atau URL berdasarkan type.

   • Nilai kembalian: Tipe: NSString. String whash.

   • Contoh:

     // Permintaan GET
     NSString *url = @"https://tigertally.aliyun.com/apptest";
     NSString *whash = [[AliTigerTally sharedInstance] vmpHash:TT_GET input:[url dataUsingEncoding:NSUTF8StringEncoding]];
     NSLog(@"whash: %@", whash);
     
     // Permintaan POST
     NSString *body = @"hello world";
     NSString *whash = [[AliTigerTally sharedInstance] vmpHash:TT_POST input:[body dataUsingEncoding:NSUTF8StringEncoding]];
     NSLog(@"whash: %@", whash);

   Catatan

   Pemanggilan antarmuka ini hanya diperlukan jika Anda telah mengaktifkan opsi penandatanganan kustom di konsol WAF. Jika Anda menggunakan konfigurasi signature default, Anda dapat melewati langkah ini.

4. Penandatanganan data.

   Metode ini menggunakan teknologi VMP untuk menandatangani data input dan mengembalikan sebuah string wtoken untuk otentikasi permintaan.

   /**
    * Menandatangani data.
    * @param input Data yang akan ditandatangani.
    * @return string wtoken.
    */
   - (NSString *)vmpSign:(NSData *)input;

   • Parameter:

     • input: Tipe: NSData. Data yang akan ditandatangani. Biasanya berupa seluruh request body atau whash dari custom signing.

   • Nilai kembalian: Tipe: NSString. String wtoken.

   • Contoh:

     // Signature default yang dikonfigurasi di Konsol (custom signing tidak dipilih).
     NSString *body = @"hello world";
     NSString *wtoken = [[AliTigerTally sharedInstance] vmpSign:[body dataUsingEncoding:NSUTF8StringEncoding]];
     NSLog(@"wtoken: %@", wtoken);
     
     // Custom signing yang dikonfigurasi di Konsol.
     // Custom signing untuk permintaan POST.
     NSString *whash = [[AliTigerTally sharedInstance] vmpHash:TT_POST input:[body dataUsingEncoding:NSUTF8StringEncoding]];
     NSString *wtoken = [[AliTigerTally sharedInstance] vmpSign:[whash dataUsingEncoding:NSUTF8StringEncoding]];
     NSLog(@"whash: %@, wtoken: %@", whash, wtoken);
     
     // Custom signing untuk permintaan GET.
     NSString *url = @"https://tigertally.aliyun.com/apptest";
     NSString *whash = [[AliTigerTally sharedInstance] vmpHash:TT_GET input:[url dataUsingEncoding:NSUTF8StringEncoding]];
     NSString *wtoken = [[AliTigerTally sharedInstance] vmpSign:[whash dataUsingEncoding:NSUTF8StringEncoding]];
     NSLog(@"whash: %@, wtoken: %@", whash, wtoken);

     Catatan

     • Saat menggunakan custom signing, input untuk antarmuka vmpSign harus berupa string whash yang dihasilkan oleh vmpHash. Saat Anda mengonfigurasi kebijakan berbasis skenario untuk App Protection, Anda harus mengatur Custom Signing Field menjadi ali_sign_whash.

     • Saat memanggil vmpHash untuk menghasilkan whash untuk permintaan GET, pastikan URL input identik dengan URL permintaan jaringan akhir. Perhatikan dengan cermat pengkodean URL, karena beberapa framework secara otomatis melakukan encode terhadap karakter atau parameter tertentu.

     • Input untuk antarmuka vmpHash tidak boleh berupa array byte atau string kosong. Jika input berupa URL, URL tersebut harus mencakup path atau parameter.

     • Saat memanggil vmpSign, jika request body kosong (misalnya pada permintaan GET atau permintaan POST tanpa body), berikan nil atau representasi NSData dari string kosong, seperti [@"" dataUsingEncoding:NSUTF8StringEncoding].

     • Jika whash atau wtoken mengembalikan salah satu string berikut, hal ini menunjukkan adanya kesalahan:

       • you must call init first: Fungsi init belum dipanggil.

       • you must input correct data: Data input tidak valid.

       • you must input correct type: Tipe input tidak valid.

3. Verifikasi sekunder

1. Periksa hasil.

   Untuk menentukan apakah diperlukan verifikasi sekunder, periksa cookie dan badan dari tanggapan. Jika header berisi beberapa bidang Set-Cookie, gabungkan menjadi satu string cookie sebelum memanggil antarmuka ini.

   /**
    * Memeriksa apakah perlu melakukan verifikasi sekunder.
    *
    * @param cookie  Cookie tanggapan.
    * @param body    Badan tanggapan.
    * @return 0: Lolos, 1: Diperlukan verifikasi sekunder.
    */
   - (int)cptCheck:(NSString *)cookie body:(NSData *)body;

   • Parameter:

     • cookie: Tipe: NSString. Semua cookie dalam tanggapan permintaan.

     • body: Tipe: NSData. Merupakan seluruh body dari tanggapan permintaan.

   • Nilai kembalian: Tipe: int. Hasil keputusan. 0 menunjukkan permintaan lolos, dan 1 menunjukkan bahwa verifikasi sekunder diperlukan.

   • • Contoh:

     NSString *cookie = @"key1=value1;key2=value2;";
     NSData *body = xxx;
     int recheck = [[AliTigerTally sharedInstance] cptCheck:cookie body:body];
     NSLog(@"recheck: %d", recheck);

2. Buat slider.

   Jika hasil dari cptCheck menunjukkan perlunya verifikasi, buat objek slider. Objek TTCaptcha menyediakan metode show dan dismiss untuk mengontrol jendela slider. Gunakan TTOption untuk mengonfigurasi parameternya dan TTDelegate untuk menangani callback statusnya. Untuk menyesuaikan jendela slider, Anda harus menyediakan URL ke halaman kustom, yang dapat berupa file HTML lokal atau halaman remote.

   /**
    * Menampilkan slider untuk verifikasi.
    *
    * @param view      Komponen induk.
    * @param option    Parameter.
    * @param detegate  Protokol callback.
    */
   - (TTCaptcha *)cptCreate:(UIView *)view option:(TTOption *)option delegate:(id<TTDelegate>)detegate;
   
   
   @protocol TTDelegate <NSObject>
   @required
   // Verifikasi slider berhasil.
   - (void)success:(TTCaptcha *)captcha data:(NSString *)data;
   
   // Verifikasi slider gagal.
   - (void)failed:(TTCaptcha *)captcha code:(NSString *)code;
   @end
   
   
   @interface TTOption : NSObject
   // Ketuk untuk membatalkan.
   @property (nonatomic, assign) BOOL cancelable;
   
   // Halaman kustom.
   @property (nonatomic, strong) NSString *customUri;
   
   // Bahasa.
   @property (nonatomic, strong) NSString *language;
   @end
   
   
   @interface TTCaptcha : NSObject
   
   - (instancetype)init:(UIView *)view option:(TTOption *)option delegate:(id<TTDelegate>)delegate;
   
   // Mendapatkan traceId slider untuk analitik data.
   - (NSString *)getTraceId;
   
   // Menampilkan slider.
   - (void)show;
   
   // Menutup slider.
   - (void)dismiss;
   
   @end

   • Parameter:

     • view: Tipe: View. Tampilan halaman saat ini.

     • option: Tipe: TTOption. Parameter konfigurasi slider.

     • delegate: Tipe: TTDelegate. Callback status slider.

   • Nilai kembalian: Tipe: TTCaptcha. Objek slider.

   • Contoh:

     #pragma mark - TTDelegate
     - (void)failed:(TTCaptcha *)captcha code:(nonnull NSString *)code {
         NSLog(@"captcha gagal: %@", code);
     }
     
     - (void)success:(TTCaptcha *)captcha data:(nonnull NSString *)data {
         NSLog(@"captcha berhasil: %@", data);
     }
     
     TTOption *option = [[TTOption alloc] init];
     // option.customUri = @"ali-tt-captcha-demo-ios";
     option.language   = @"cn";
     option.cancelable = true;
     
     TTCaptcha *captcha = [[AliTigerTally sharedInstance] cptCreate:[self view] option:option delegate:self];
     [captcha show];

     Catatan

     Kesalahan "Verifikasi gagal" menunjukkan bahwa terdeteksi adanya anomali selama atau setelah interaksi pengguna dengan slider.

     Tabel berikut menjelaskan kode kesalahan.

     • 1001: Tantangan verifikasi gagal.

     • 1002: Terjadi anomali sistem.

     • 1003: Parameter yang ditentukan tidak valid.

     • 1005: Verifikasi dibatalkan.

     • 8001: Gagal menampilkan slider.

     • 8002: Terjadi anomali pada data verifikasi slider.

     • 8003: Terjadi anomali internal selama verifikasi slider.

     • 8004: Terjadi kesalahan jaringan.