全部产品
弹性计算 会员服务 网络 安全 移动云 数加·大数据分析及展现 数加·大数据应用 管理与监控 云通信 阿里云办公 培训与认证 智能硬件
存储与CDN 数据库 域名与网站(万网) 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 更多
Web 应用防火墙

Android 接入文档

更新时间:2018-07-11 13:41:41

本文介绍了使用 Android App 接入 WAF SDK 的操作方法。

SDK-Android 文件说明

下载并解压 WAF SDK 包(点击获取SDK包),在 sdk-Android 文件夹下,提供了以下文件:

注意:aar 文件的版本号可能会有不同。

sdk-Android

各文件说明(xxx为版本号):

文件 功能
SecurityGuardSDK-xxx.aar 主框架SDK
AVMPSDK-xxx.aar 虚拟机引擎插件
SecurityBodySDK-xxx.aar 人机识别插件
yw_1222_0335.jpg 主框架配置文件
yw_1222_0335_mwua.jpg 虚拟机引擎配置文件

项目工程配置

参照以下步骤,来配置项目工程。

导入aar文件

  1. 在 Android Studio 中导入 SDK 中的 aar 文件。将 SDK 中所有的 aar 文件都复制到项目的 libs 目录下。如果没有 libs 目录,请手工创建一个。

  2. 打开该 Module 的 build.gradle 文件,在其中增加以下配置(图示 ③ 和 ④ )。

    • 将 libs 目录作为查找依赖的源。
    1. repositories{
    2. flatDir {
    3. dirs 'libs'
    4. }
    5. }
    • 增加编译依赖。注意:aar 文件版本号可能会有不同,以下载得到的文件为准。
    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. 向 drawable 文件夹中导入 jpg 文件。将 SDK 目录下的 yw_1222_0335_mwua.jpg 和 yw_1222_0335.jpg 图片文件放到 Android 应用工程的 drawable 目录下。

    注意:如果默认没有 drawable 目录,请手动创建一个。

    导入jpg文件

  4. 过滤 ABI(删除多余架构SO)。WAF SDK 目前仅支持 armeabi、armeabi-v7a、arm64-v8a 架构的 SO。因此,您需要对最终导出的 ABI 进行过滤。否则,会造成 App 崩溃。具体操作如下:

    1. 在 Android 工程 lib 目录下,删除除了 armeabi 文件夹之外的所有其他 CPU 架构的文件夹,包括 x86、x86_64、mips、mips64 等。最终,只保留 armeabi、armeabi-v7a、arm64-v8a 目录。
    2. 在工程的 build.gradle 配置文件中增加过滤规则,被 abiFilters 指定的架构即会被包含在 APK 里面。示例代码如下:

      说明: 本代码示例中指定了 armeabi 架构,您可以根据实际情况指定或兼容 armeabi-v7a、arm64-v8a 架构。

      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. // abiFilters "armeabi-v7a"
      10. // abiFilters "arm64-v8a"
      11. }
      12. }

      注意:只保留 armeabi 架构的 SO,不会影响 App 的兼容性,并且还能大大减小 App 的体积。

    下图显示了手机淘宝 App 的 ABI 情况。可以看出,手机淘宝 App 只有 armeabi 架构的目录。

    4

  5. 添加 App 权限。

    • 如果是 Android Studio 项目,并且使用 aar 方式集成,那么则不需要在项目中额外配置权限,因为在 aar 中已经声明了相关权限。

    • 如果是 Eclipse 项目,需要在 AndroidMenifest.xml 文件中添加下列权限配置:

      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. 添加 ProGuard 配置。如果您使用了 Proguard 进行混淆,则需要添加 ProGuard 配置。ProGuard 配置也根据接入方式的不同,分为 Eclipse 和 AndrodStudio 两种情况。

    • Android Studio

      如果在 build.gradle 中配置了 proguardFiles,并且开启了 minifyEnabled,则表明使用了 proguard-rules.pro 这个配置文件进行混淆。如下图所示。

      ProGuard

    • Eclipse

      如果在 project.properties 中指定了 proguard 配置,比如在 project.properties 中有如下的语句:proguard.config=proguard.cfg,则表明使用了 proguard 进行混淆。混淆配置在 proguard.cfg 文件中:

      proguard.cfg

    添加 keep 规则

    为了保证需要的一些类不被混淆,需要在 proguard 的配置文件中添加以下规则。

    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.**{*;}

代码编写

  1. 导入包。

    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. 初始化。

    • 接口定义:boolean initialize();
    • 接口描述:
      • 功能:初始化 SDK。
      • 参数:无。
      • 返回值:boolean 类型。初始化成功返回 true,失败返回 false。
    • 示例代码:
      1. IJAQAVMPSignComponent jaqVMPComp = SecurityGuardManager.getInstance(getApplicationContext()).getInterface(IJAQAVMPSignComponent.class);
      2. boolean result = jaqVMPComp.initialize();
  3. 签名请求数据。

    • 接口定义:byte[] avmpSign(int signType, byte[] input);
    • 接口描述:

      • 功能:使用 avmp 技术对 input 的数据进行签名处理,并且返回签名串。
      • 参数:见下表。

        参数名类型是否必须说明
        signTypeint签名使用的算法,目前是固定值,填写 3。
        inputbyte[]待签名的数据,一般是整个请求体(request body)。如果请求体为空(如POST请求的body为空,或是GET请求),那么此参数使用 null。
      • 返回值:byte[] 类型,返回签名串。

      • 示例代码。客户端往服务器端发送数据时,需要调用 avmpSign 接口对整个 body 数据进行签名处理,之后得到签名串,这个签名串就是 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. 将 wToken 放进协议头。在 HttpURLConnection 类的对象中增加 wToken 字段的内容。示例代码如下:

    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. 发送数据到服务器。将修改好协议头的数据发到 App 自有服务器,中间会由 WAF 截获,并解析 wToken 进行风险识别。

重点注意: 被签名的请求体应该跟客户端实际发送出来的请求体完全一样,完全一样的含义包括请求体中字符串的编码格式、空格、特殊字符以及参数的顺序等等,否则会造成验签失败。

错误码

上述 initialize 和 avmpSign 接口有可能会出现异常。如果生成签名串异常或失败,请搜索 Log 中 “SecException” 相关的信息。

常见错误信息及描述见下表。

错误代码 含义
1901 参数不正确,请检查输入的参数。
1902 图片文件有问题。一般是获取图片文件时的 apk 签名和当前程序的 apk 签名不一致。请使用当前程序的 apk 重新生成图片。iOS 可能是应为 BundleID 不匹配。
1903 图片文件格式有问题。
1904 请升级新版本图片。AVMP 签名功能仅支持 v5 图片。
1905 没有找到图片文件。请确保图片文件在 res\drawable 目录下,AVMP 相关的图片为:yw_1222_0335_mwua.jpg。
1906 图片中缺少 AVMP 签名对应的 byteCode。请检查使用的图片是否正确。
1907 初始化 AVMP 失败,请重试。
1910 非法的 avmpInstance 实例。可能原因如下:AVMPInstance 是否被 destroy 后,调用 InvokeAVMP。图片 byteCode 版本与 SDK 不匹配。
1911 加密图片的 byteCode 没有相应导出的函数。
1912 AVMP 调用失败。请联系我们。
1913 AVMPInstance 被 destroy 之后,调用 InvokeAVMP 出现该错误。
1915 AVMP 调用内存不足,请重试。
1999 未知错误,请重试。

常见问题

指定 shrinkResources 之后,密钥图片被优化掉了

在 Android Studio 中,如果指定了 shrinkResources 为 true,那么,在工程编译的时候会把没有在代码中引用的资源文件给优化掉。

faq1

上述操作会使 SDK 中提供的两个 jpg 文件不能正常工作。如下图所示,打包出来的 APK 中,yw_1222_0335.jpg 的配置文件大小为 0KB,表明这个图片被优化掉了。

faq2

解决方法

在工程的 res 目录下新建 raw 目录,在 raw 目录下创建 keep.xml 文件。在 keep.xml 中输入如下内容:

  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" />

faq3

添加完上述内容,重新编译工程 apk 即可。

集成效果确认

参照以下步骤确认您的 App 已正确集成了 WAF SDK。

  1. 将打包出来的 apk 文件重命名成 zip 文件,然后用解压工具将该文件解压。

    sdk1

  2. 解压之后,定位到工程的 lib 目录,确保文件夹下只有 armeabi 文件夹。如果还有其他架构的文件夹,请参考 项目工程配置 步骤 4,移除其他架构的文件夹。

    sdk2

  3. 定位到工程的 res/drawable 目录下,确保 yw_1222_0335.jpg 和 yw_1222_0335_mwua.jpg 文件在其中,并且文件大小不为 0。

    sdk3

  4. 通过打印日志,确保调用 avmpSign 接口之后能生成正确的签名信息。如果没有生成,则查看是否有错误码产生。

本文导读目录