Web Application Firewall:Integrasikan SDK untuk Android

1. Tambahkan file header

import com.alibaba.fastjson.*;
import com.aliyun.tigertally.*;

2. Siapkan penandatanganan data

1. Tetapkan ID kustom untuk setiap pengguna akhir. Hal ini memungkinkan Anda mengonfigurasi kebijakan mitigasi WAF secara lebih fleksibel.

   /**
   * Menetapkan akun pengguna.
   *
   * @param account Akun pengguna.
   * @return Kode kesalahan.
   */
   public static int setAccount(String account)

   • Parameter:

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

   • Nilai kembali: int. Mengembalikan 0 jika berhasil, atau -1 jika gagal.

   • Kode contoh:

     // Untuk tamu, Anda dapat melewatkan setAccount dan langsung menginisialisasi SDK. Setelah pengguna login, panggil setAccount dan inisialisasi ulang.
     String account = "user001";
     TigerTallyAPI.setAccount(account);

2. Inisialisasi SDK dan lakukan pengumpulan data awal.

   Pengumpulan data awal mengumpulkan informasi perangkat satu kali. Anda dapat memanggil fungsi init lagi untuk melakukan pengumpulan baru sesuai kebutuhan bisnis Anda. Tersedia tiga mode pengumpulan: pengumpulan lengkap, pengumpulan privasi kustom, dan pengumpulan non-privasi. Mode non-privasi tidak mengumpulkan data dari bidang yang terkait privasi pengguna akhir, termasuk: imei, imsi, simSerial, wifiMac, wifiList, bluetoothMac, dan androidId.

   Catatan

   Pilih mode pengumpulan yang sesuai dengan persyaratan kepatuhan Anda dan pastikan integritas data. Data lengkap meningkatkan identifikasi risiko.

   // Callback inisialisasi
   public interface TTInitListener {
       // Parameter code menunjukkan kode status pemanggilan antarmuka.
       void onInitFinish(int code);
   }
   
   /**
    * Menginisialisasi SDK dengan callback.
    *
    * @param context Konteks aplikasi.
    * @param appkey Appkey SDK.
    * @param collectType Mode pengumpulan data.
    * @param otherOptions Parameter opsional.
    * @param listener Callback inisialisasi.
    * @return Kode kesalahan.
    */
   public static int init(Context context, String appkey, int collectType,
                          Map<String, String> otherOptions, TTInitListener listener);

   • Parameter:

     • context: Context. Konteks aplikasi Anda.

     • appkey: String. Appkey SDK Anda.

     • collectType: int. Mode pengumpulan. Nilai valid:

       Parameter	Deskripsi	Contoh
       TT_DEFAULT	Mengumpulkan semua data.	TigerTallyAPI.TT_DEFAULT
       TT_NO_BASIC_DATA	Tidak mengumpulkan data perangkat dasar. Mencakup: nama perangkat (Build.DEVICE), versi Android (Build.VERSION#RELEASE), dan resolusi layar.	TigerTallyAPI.X | TigerTallyAPI.Y (Menunjukkan bahwa X maupun Y tidak dikumpulkan. X dan Y merepresentasikan nama bidang item tertentu.)
       TT_NO_IDENTIFY_DATA	Tidak mengumpulkan data pengenal perangkat. Mencakup: IMEI, IMSI, SimSerial, BuildSerial (SN), dan alamat MAC.
       TT_NO_UNIQUE_DATA	Tidak mengumpulkan data pengenal unik. Mencakup: OAID, Google Advertising ID, dan Android ID.
       TT_NO_EXTRA_DATA	Tidak mengumpulkan data perangkat tambahan. Mencakup: daftar aplikasi berbahaya/abu-abu, IP LAN, IP DNS, informasi Wi-Fi yang terhubung (SSID, BSSID), daftar Wi-Fi terdekat, informasi lokasi, dan informasi sensor.
       TT_NOT_GRANTED	Tidak mengumpulkan data privasi apa pun yang disebutkan sebelumnya.	TigerTallyAPI.TT_NOT_GRANTED

     • otherOptions: Map<String, String>. Parameter opsional untuk pengumpulan data. Bisa bernilai null. Parameter yang tersedia:

       Parameter	Deskripsi	Contoh
       IPv6	Menentukan apakah akan menggunakan nama domain IPv6 untuk melaporkan informasi perangkat. 0 (default): Gunakan nama domain IPv4. 1: Gunakan nama domain IPv6.	1
       Intl	Menentukan apakah akan melaporkan informasi perangkat ke wilayah luar Tiongkok daratan. 0 (default): Laporkan ke Tiongkok daratan. 1: Laporkan ke wilayah luar Tiongkok daratan.	1
       CustomUrl	Nama domain server pelaporan data.	https://cloudauth-device.us-west-1.aliyuncs.com
       CustomHost	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: TTInitListener. Callback inisialisasi SDK. Gunakan callback ini untuk memeriksa status inisialisasi. Bisa bernilai null.

       TTCode	Kode	Deskripsi
       TT_SUCCESS	0	SDK berhasil diinisialisasi.
       TT_NOT_INIT	-1	SDK belum diinisialisasi.
       TT_NOT_PERMISSION	-2	SDK belum diberikan izin Android yang diperlukan.
       TT_UNKNOWN_ERROR	-3	Kesalahan sistem tidak dikenal.
       TT_NETWORK_ERROR	-4	Kesalahan jaringan.
       TT_NETWORK_ERROR_EMPTY	-5	Kesalahan jaringan: respons 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	Gateway mengembalikan respons kegagalan.
       TT_APPKEY_EMPTY	-9	Appkey kosong.
       TT_PARAMS_ERROR	-10	Parameter tidak valid.
       TT_FGKEY_ERROR	-11	Kesalahan perhitungan kunci.
       TT_APPKEY_ERROR	-12	Ketidakcocokan antara versi SDK dan appkey.

   • Nilai kembali: int. Mengembalikan 0 jika berhasil, atau -1 jika gagal.

   • Kode contoh:

     // Appkey adalah kunci otentikasi yang ditetapkan di platform Alibaba Cloud.
     final String appkey="******";
     // Parameter opsional untuk mengonfigurasi IPv6 dan pelaporan internasional.
     Map<String, String> options = new HashMap<>();
     options.put("IPv6", "0");   // Gunakan IPv4.
     options.put("Intl", "0");   // Laporkan ke Tiongkok daratan.
     //options.put("Intl", "1"); // Laporkan ke wilayah luar Tiongkok daratan.
     
     // Laporkan ke AS (Silicon Valley).
     //options.put("CustomUrl", "https://cloudauth-device.us-west-1.aliyuncs.com"); 
     //options.put("CustomHost", "cloudauth-device.us-west-1.aliyuncs.com"); 
     
     // Pengumpulan data awal mengumpulkan informasi perangkat satu kali. Anda dapat memanggil fungsi init lagi untuk melakukan pengumpulan baru sesuai kebutuhan bisnis Anda.
     // Pengumpulan lengkap.
     int ret = TigerTallyAPI.init(this.getApplicationContext(), appkey, TigerTallyAPI.TT_DEFAULT, options, null);
     
     // Tentukan data privasi yang akan dikumpulkan. Anda dapat menggabungkan flag berbeda dengan operator "|".
     int privacyFlag = TigerTallyAPI.TT_NO_BASIC_DATA | TigerTallyAPI.TT_NO_UNIQUE_DATA;
     int ret = TigerTallyAPI.init(this.getApplicationContext(), appkey, privacyFlag, options, null);
     
     // Jangan kumpulkan bidang privasi.
     int ret = TigerTallyAPI.init(this.getApplicationContext(), appkey, TigerTallyAPI.TT_NOT_GRANTED, options, null);
     Log.d("AliSDK", "ret:" + ret);

3. Hash data.

   Metode penandatanganan kustom ini menghitung hash dari data masukan dan mengembalikan string whash sebagai data tanda tangan kustom. Untuk permintaan POST, PUT, dan PATCH, berikan badan permintaan. Untuk permintaan GET dan DELETE, berikan URL lengkap. String whash harus ditambahkan ke bidang ali_sign_whash dalam Header permintaan HTTP.

   // Jenis permintaan:
   public enum RequestType { GET, POST, PUT, PATCH, DELETE }
   
   /**
    *  Hash data untuk tanda tangan kustom.
    *
    * @param type Jenis permintaan.
    * @param input Data yang akan di-hash.
    * @return String whash.
    */
   public static String vmpHash(RequestType type, byte[] input);

   • Parameter:

   • type: RequestType. Jenis permintaan. Nilai valid:

     • GET: Permintaan GET.

     • POST: Permintaan POST.

     • PUT: Permintaan PUT.

     • PATCH: Permintaan PATCH.

     • DELETE: Permintaan DELETE.

   • input: byte[]. Data yang akan di-hash.

   • Nilai kembali: String. Mengembalikan string whash.

   • Kode contoh:

     // Permintaan GET
     String url = "https://tigertally.aliyun.com/apptest";
     String whash = TigerTallyAPI.vmpHash(TigerTallyAPI.RequestType.GET, url.getBytes());
     Log.d("AliSDK", "whash:" + whash);
     
     // Permintaan POST
     String body = "hello world";
     String whash = TigerTallyAPI.vmpHash(TigerTallyAPI.RequestType.POST, body.getBytes());
     Log.d("AliSDK", "whash:" + whash);

     Catatan

     Metode ini tidak diperlukan untuk penandatanganan default. Untuk penandatanganan kustom, panggil metode ini untuk meng-hash data sebelum menandatangani.

4. Menandatangani data.

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

   /**
    * Menandatangani data.
    *
    * @param type Jenis tanda tangan.
    * @param input Data yang akan ditandatangani.
    * @return String wtoken.
    */
   public static String vmpSign(int type, byte[] input);

   • Parameter:

     • type: int. Jenis penandatanganan data. Nilainya harus 1.

     • input: byte[]. Data yang akan ditandatangani. Biasanya berupa seluruh badan permintaan atau string whash dari penandatanganan kustom.

   • Nilai kembali: String. Mengembalikan string wtoken.

   • Kode contoh:

     // Gunakan kode ini jika penandatanganan default dikonfigurasi di Konsol (penandatanganan kustom tidak dipilih).
     String body = "i am the request body, encrypted or not!";
     String wtoken = TigerTallyAPI.vmpSign(1, body.getBytes("UTF-8"));
     Log.d("AliSDK", "wToken:" + wtoken);
     
     // Gunakan kode ini jika penandatanganan kustom dikonfigurasi di Konsol.
     // Permintaan GET
     String url = "https://tigertally.aliyun.com/apptest";
     String whash = TigerTallyAPI.vmpHash(TigerTallyAPI.RequestType.GET, url.getBytes());
     String wtoken = TigerTallyAPI.vmpSign(1, whash.getBytes());
     Log.d("AliSDK", "whash:" + whash + ", wtoken:" + wtoken);
     
     // Permintaan POST
     String body = "hello world";
     String whash = TigerTallyAPI.vmpHash(TigerTallyAPI.RequestType.POST, body.getBytes());
     String wtoken = TigerTallyAPI.vmpSign(1, whash.getBytes());
     Log.d("AliSDK", "whash:" + whash + ", wtoken:" + wtoken);

     Catatan

     • Saat Anda memanggil vmpHash untuk penandatanganan kustom, parameter input metode vmpSign adalah string whash yang dihasilkan. Saat mengonfigurasi kebijakan anti-bot aplikasi, nilai Custom Signature Field harus diatur ke ali_sign_whash.

     • Saat Anda memanggil vmpHash untuk menghasilkan string whash untuk permintaan GET, pastikan URL input identik dengan URL akhir yang digunakan dalam permintaan jaringan. Perhatikan khusus encoding URL, karena beberapa framework secara otomatis meng-encode karakter Tionghoa atau parameter.

     • Parameter input metode vmpHash tidak mendukung array byte kosong atau string kosong. Jika input berupa URL, URL tersebut harus berisi path atau parameter.

     • Saat Anda memanggil vmpSign, jika badan permintaan kosong (misalnya, pada permintaan GET atau permintaan POST dengan badan kosong), berikan objek null atau nilai byte dari string kosong, seperti "".getBytes("UTF-8").

     • Jika nilai whash atau wtoken adalah salah satu string berikut, SDK telah mengembalikan kesalahan:

       • you must call init first: SDK belum diinisialisasi. Panggil init() terlebih dahulu.

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

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

3. Lakukan verifikasi sekunder

1. Evaluasi hasil.

   Periksa bidang cookie dan badan dalam respons untuk menentukan apakah verifikasi sekunder diperlukan. Sebelum memanggil metode ini, gabungkan beberapa entri Set-Cookie menjadi satu string cookie.

   /**
    * Menentukan apakah perlu melakukan verifikasi sekunder.
    *
    * @param cookie String cookie.
    * @param body String badan.
    * @return 0 untuk lolos, atau 1 untuk verifikasi sekunder diperlukan.
    */
   public static int cptCheck(String cookie, String body)

   • Parameter:

     • cookie: String. Semua cookie dari respons HTTP.

     • body: String. Seluruh body dari tanggapan HTTP.

   • Nilai kembali: int. Mengembalikan 0 jika permintaan lolos, atau 1 jika verifikasi sekunder diperlukan.

   • Kode contoh:

     String cookie = "key1=value1;kye2=value2;";
     String body = "....";
     int recheck = TigerTallyAPI.cptCheck(cookie, body);
     Log.d("AliSDK", "recheck:" + recheck);

2. Buat slider.

   Jika cptCheck mengembalikan 1, buat objek slider. Objek TTCaptcha menyediakan metode show() dan dismiss() untuk menampilkan dan menyembunyikan jendela slider. TTOption membungkus parameter yang dapat dikonfigurasi untuk slider, dan TTListener menyediakan callback untuk status sukses dan gagal. Untuk menggunakan jendela slider kustom, berikan URL halaman kustom. File HTML lokal maupun halaman remote didukung.

   /**
    * Membuat objek slider.
    *
    * @param activity Aktivitas tempat slider ditampilkan.
    * @param option Parameter slider.
    * @param listener Callback untuk slider.
    * @return Objek verifikasi slider.
    */
   public static TTCaptcha cptCreate(Activity activity, TTOption option, TTListener listener);
   
   
   /**
    * Objek slider.
    */
   public class TTCaptcha {
       /**
        * Menampilkan slider.
        */
       public void show();
   
       /**
        * Menyembunyikan slider.
        */
       public void dismiss();
   
       /**
        * Mendapatkan traceId slider untuk statistik data.
        */
       public String getTraceId();
   }
   
   /**
    * Parameter slider.
    */
   public static class TTOption {
       // Menentukan apakah slider dapat ditutup dengan mengklik area kosong.
       public boolean cancelable;
   
       // Halaman kustom. File HTML lokal dan URL remote didukung.
       public String customUri;
   
       // Bahasa.
       public String language;
   }
   
   /**
    * Callback untuk event slider.
    */
   public interface TTListener {
       /**
        * Dipanggil saat verifikasi berhasil.
        *
        * @param captcha Objek slider.
        * @param data Token. Default-nya adalah certifyId.
        */
       void success(TTCaptcha captcha, String data);
   
       /**
        * Dipanggil saat verifikasi gagal.
        *
        * @param captcha Objek slider.
        * @param code Kode kesalahan.
        */
       void failed(TTCaptcha captcha, String code);
   }

   • Parameter:

     • activity: Activity. Aktivitas halaman saat ini.

     • option: TTOption. Parameter konfigurasi slider.

     • listener: TTListener. Callback status slider.

   • Nilai kembali: TTCaptcha. Objek slider.

   • Kode contoh:

   TTCaptcha.TTOption option = new TTCaptcha.TTOption();
   // option.customUri  = "file:///android_asset/ali-tt-captcha-demo.html";
   option.language   = "cn";
   option.cancelable = false;
   
   TTCaptcha captcha = TigerTallyAPI.cptCreate(this, option, new TTCaptcha.TTListener() {
       @Override
       public void success(TTCaptcha captcha, String data) {
           Log.d(TAG, "captcha check success:" + data);
       }
       @Override
       public void failed(TTCaptcha captcha, String code) {
           Log.d(TAG, "captcha check failed:" + code);
       }
   });
   captcha.show();

   Catatan

   Kegagalan verifikasi menunjukkan bahwa anomali terdeteksi setelah pengguna menyelesaikan tantangan slider.

   Daftar berikut menjelaskan kode kesalahan:

   • 1001: Verifikasi gagal.

   • 1002: Pengecualian sistem.

   • 1003: Parameter tidak valid.

   • 1005: Verifikasi dibatalkan.

   • 8001: Gagal menampilkan slider.

   • 8002: Data verifikasi slider abnormal.

   • 8003: Pengecualian internal verifikasi slider.

   • 8004: Kesalahan jaringan.