edit-icon download-icon

Android integration manual

Last Updated: Jun 27, 2018

This document describes the procedure to connect to WAF SDK by using an Android App.

Download the SDK package

Download and unzip the WAF SDK package. Click to download SDK.

The following files are included in the sdk-Android folder:

Note: The aar file version numbers may be different.

sdk-Android

The description of these files is as follows (xxx is the version number):

File Description
SecurityGuardSDK-xxx.aar Main framework SDK
AVMPSDK-xxx.aar Virtual machine plugin
SecurityBodySDK-xxx.aar Man/machine identification plugin
yw_1222_0335.jpg Mainframe configuration file
yw_1222_0335_mwua.jpg Virtual machine engine configuration file

Procedure

Follow these steps to configure the project:

Import the aar files

  1. Import the aar files of the SDK to Android Studio. Copy all aar files from the SDK to the project’s libs directory. If the libs directory does not exist, create one.

  2. Open this Module’s build.gradle file, and add the following configuration to it (as shown in ③ and ④).

    • Use the libs directory as the source for searching dependencies.
    1. repositories{
    2. flatDir {
    3. dirs 'libs'
    4. }
    5. }
    • Add compilation dependencies.

      Note: The aar file version numbers here may be different with those of the files downloaded by you.

    1. dependencies {
    2. compile fileTree(include: ['*.jar'], dir: 'libs')
    3. compile ('com.android.support:appcompat-v7:23.0.0')
    4. compile (name:'AVMPSDK-external-release-xxx', ext:'aar')
    5. compile (name:'SecurityBodySDK-external-release-xxx', ext:'aar')
    6. compile (name:'SecurityGuardSDK-external-release-xxx', ext:'aar')
    7. }
  3. Import the jpg file into the drawable folder. Move the yw_1222_0335_mwua.jpg and yw_1222_0335.jpg files from the SDK directory to the Android application project’s drawable directory.

    Note: If the drawable directory does not exist by default, create one.

    Import jpg files

  4. Filter out ABI to remove redundant SO architectures. Currently, WAF SDK only provides SO in the armeabi architecture. Therefore, you must filter the exported ABIs. Otherwise, it may cause an App crash. The procedure is as follows:

    1. Go to the Android project’s lib directory, and delete all CPU architecture folders apart from the armeabi folder, which include armeabi-v7a, x86, x86_64, arm64-v8a, mips, and mips64. Make sure you keep only the armeabi folder.
    2. Add a filter rule in the project’s build.gradle configuration file. Architectures specified by abiFilters are included in the APK. Only the armeabi architecture is specified. The sample code is as follows:

      1. defaultConfig {
      2. applicationId "com.xx.yy"
      3. minSdkVersion xx
      4. targetSdkVersion xx
      5. versionCode xx
      6. versionName "x.x.x"
      7. ndk {
      8. abiFilters "armeabi"
      9. }
      10. }

      Note: Keeping only the SO in the armeabi architecture can remarkably reduce the App size without affecting the App’s compatibility.

  5. Add App permission.

    • For an Android Studio project that uses the aar method integration, additional permission configuration is not necessary, because the relevant permissions are already specified in the aar files.

    • For an Eclipse project, you must add the following permission configuration to the AndroidMenifest.xml file:

      1. <uses-permission android:name="android.permission.INTERNET" />
      2. <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
      3. <uses-permission android:name="android.permission.READ_PHONE_STATE" />
      4. <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
      5. <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
      6. <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
      7. <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
      8. <uses-permission android:name="android.permission.WRITE_SETTINGS" />
  6. Add ProGuard configuration. If you have used Proguard for obfuscation, then you must add the ProGuard configuration. Based on different access methods, the ProGuard configuration is divided into two types, which are Eclipse and AndrodStudio respectively.

    • Android Studio

      If proguardFiles is configured in build.gradle and minifyEnabled is enabled, it means that the proguard-rules.pro configuration file is used for obfuscation, as shown in the following figure:

      ProGuard

    • Eclipse

      If the proguard configuration is specified in project.properties (for example, the project.properties contains the following statement proguard.config=proguard.cfg), it means that proguard is used for obfuscation. Obfuscation configuration in the proguard.cfg file is shown in the following figure:

      proguard.cfg

    Add keep rules

    To make sure that certain classes are not obfuscated, you must add the following rules in the proguard configuration file.

    1. -keep class com.taobao.securityjni.**{*;}
    2. -keep class com.taobao.wireless.security.**{*;}
    3. -keep class com.ut.secbody.**{*;}
    4. -keep class com.taobao.dp.**{*;}
    5. -keep class com.alibaba.wireless.security.**{*;}

Coding process

1. Import SDK

The sample code is as follows.

  1. import com.alibaba.wireless.security.jaq.JAQException;
  2. import com.alibaba.wireless.security.jaq.avmp.IJAQAVMPSignComponent;
  3. import com.alibaba.wireless.security.open.SecurityGuardManager;
  4. import com.alibaba.wireless.security.open.avmp.IAVMPGenericComponent;

2. Initialize SDK

Interface definition: boolean initialize();

Interface description:

  • Function: Initialize SDK.
  • Parameter: N/A.
  • Return value: Boolean type. True if the initialization is successful, and False if the initialization fails.

Sample code:

  1. IJAQAVMPSignComponent jaqVMPComp = SecurityGuardManager.getInstance(getApplicationContext()).getInterface(IJAQAVMPSignComponent.class);
  2. boolean result = jaqVMPComp.initialize();

3. Sign the request data

Interface definition: byte[] avmpSign(int signType, byte[] input);

Interface description:

  • Function: Use the avmp technology to sign the input data, and return the signature string.

  • Parameters:

    Parameter Name Type Required Description
    signType int Yes Algorithm used by the signature. Currently, it is a fixed value. Enter 3.
    input byte[] No Data to be signed, which is generally the entire request body. If the request body is empty, then enter null for this parameter.
    • Return value: byte[] type. The signature string is returned.

Sample code:

When the client sends data to the server, it must call the avmpSign interface to sign the entire body data and obtain the signature string (the wToken).

  1. int VMP_SIGN_WITH_GENERAL_WUA2 = 3;
  2. String request_body = "i am the request body, encrypted or not!";
  3. byte[] result = jaqVMPComp.avmpSign(VMP_SIGN_WITH_GENERAL_WUA2, request_body.getBytes("UTF-8"));
  4. String wToken = new String(result, "UTF-8");
  5. Log.d("wToken", wToken);

4. Put the wToken in the protocol header

Add the wToken field’s content to the HttpURLConnection class object. The sample code is as follows:

  1. String request_body = "i am the request body, encrypted or not!";
  2. URL url = new URL("http://www.xxx.com");
  3. HttpURLConnection conn = (HttpURLConnection) url.openConnection();
  4. conn.setRequestMethod("POST");
  5. // set wToken info to header
  6. conn.setRequestProperty("wToken", wToken);
  7. OutputStream os = conn.getOutputStream();
  8. // set request body info
  9. byte[] requestBody = request_body.getBytes("UTF-8");
  10. os.write(requestBody);
  11. os.flush();
  12. os.close();

5. Send data to the server

Send the data with the modified protocol header to the App’s self-owned server. WAF captures the data and parses the wToken for risk identification.

Error codes

The preceding initialize() and avmpSign() interfaces may encounter exceptions. If you encounter an exception or error when generating the signature string, search “SecException” for related information in the log.

Common errors are listed as follows:

Error Code Meaning
1901 Incorrect parameter. Enter the correct parameter.
1902 Image file error. It generally indicates that the apk signature used to retrieve the image file is inconsistent with the current application’s apk signature. Use the current application’s apk to generate the image file. In iOS, it may be caused by inconsistent BundleIDs.
1903 Incorrect image format.
1904 Upgrade to new version images. AVMP signature function only supports v5 images.
1905 Unable to find the image file. Make sure that the image file is in the res\drawable directory. The AVMP image is yw_1222_0335_mwua.jpg.
1906 byteCode corresponding to the AVMP signature is missing in the image. Check if the image used is correct.
1907 Failed to initialize AVMP. Try again later.
1910 Invalid avmpInstance instance. Probable causes are: InvokeAVMP is called after AVMPInstance is destroyed. The image’s byteCode version does not match with that of the SDK.
1911 The encrypted image’s byteCode does not have the corresponding export function.
1912 AVMP calling fails. Submit a ticket for further assistance.
1913 This error occurs when calling InvokeAVMP after AVMPInstance is destroyed.
1915 AVMP calling out of memory. Try again later.
1999 Unknown error. Try again later.

Troubleshooting

Symptoms

Secret key image is optimized away due to specifying shrinkResources.

In Android Studio, if you specify shrinkResources to be True, then resource files that are not referenced in the code are optimized away during project compilation.

faq1

As a result, the two jpg files provided in the SDK cannot work normally.

Resolution

Create a raw folder under the project’s res directory, and then create a keep.xml file in the raw folder. Enter the following content to the keep.xml file:

  1. <?xml version="1.0" encoding="utf-8"?>
  2. <resources xmlns:tools="http://schemas.android.com/tools"
  3. tools:keep="@drawable/yw_1222_0335.jpg,@drawable/yw_1222_0335_mwua.jpg" />

After that, re-compile the project apk.

Test and validation

Follow these steps to check if your App is correctly integrated with WAF SDK:

  1. Change the suffix of the compressed apk file to zip, and decompress this zip file.

  2. Locate the project’s lib directory, and make sure that it contains only the armeabi folder. If you find folders for other architectures, delete them.

  3. Locate the project’s res/drawable directory, and make sure that the yw_1222_0335.jpg and yw_1222_0335_mwua.jpg files are there, and the file sizes are not 0.

  4. Print the log, and make sure that the correct signature information is generated after the avmpSign interface is called. If the signature information cannot be generated, check the log for error codes.

Thank you! We've received your feedback.