# XMod 接入文档

[TOC]

## XMod 简介
腾讯 XMod 项目基于 Android Root 后的高权限，通过对 Linux kernel 动态打补丁，实现对内核漏洞的修补，让用户免受提权型病毒或者恶意程序的攻击，保护用户数据的安全。

XMod 中的内核补丁基于云端运营，通过云端推荐最适配的补丁模块下发到客户端，由客户端加载到当前内核中，以实现动态的漏洞修补，用户无须重启手机即可享受高质量的安全保障。

漏洞修补是 XMod 的核心能力，可以以无界面、纯服务的形态为用户提供内核级别的安全防护。另外，也可以接入 XMod 的 Client SDK，当内核检测到有风险软件提权的时候，会以回调的方式通知到 Client SDK，产品上层就可以做一些用户感知的特性，例如 UI 变化提醒用户某些软件有风险等。

## XMod 总体框架
: *图1：XMod 总体架构图*

### 模块说明
+ Root shell
XMod 加载内核补丁以及与内核补丁通信等都需要 Root 权限，因此需要接入放提供一个 Root shell 方便 XMod 在 Root 权限下执行一些操作。**无论是 SDK 还是内置 APK 的形式接入 XMod，都需要接入方提供一个可用于执行 Shell 命令的 Root shell。**

+ XMod Client
**只有以SDK形式接入的时候，才会有该模块。** 该模块集成与上层的 APK 中，提供的接口可用于控制 XMod 功能的开关、接收 XMod 检测到风险软件时的回调信息等。

+ XMod 主进程
XMod 主进程是一个 app_process 的 Java 进程。该进程是 XMod 的主体部分，负责补丁的管理，并作为上层的 Client 与底层内核补丁通信的桥梁。

+ XMod 内核补丁
该模块是 XMod 的核心，实现了内核级别的风险软件检测以及拦截的功能。

+ 补丁精准下发云平台
根据 Android 手机的终端特性，给手机下发适配性最好、能力最强的补丁。

### 流程说明
1. SDK 或者内置 APK（视接入方式而定）利用接入方提供的 Root shell 拉起 XMod 的主进程。
2. XMod 主进程向 XMod 云端请求合适的内核补丁。
3. XMod 云端向 XMod 主进程精准下发适配的内核补丁。
4. XMod 主进程把云端下发的内核补丁加载到当前手机的内核中。
5. 但 XMod 补丁检测到有进程在执行分发操作（如 Root 提权）时会对相应操作进行拦截并通知 XMod 主进程。
6. XMod 主进程将第 5 步接收到的内核消息发送给 XMod 的 Client 端。

## XMod 参数

### XMod 文件体积
| 文件 | 文件类型 | 文件大小（单位：KB） |
| - | - | - |
XMod Client | JAR | 369
XMod 主进程 | ELF | 427
XMod 补丁 | ELF | 25 ~ 28
*附注：以上数据来自截至 2016-12-27 的最新版本 XMod。*

### XMod 流量消耗
| 场景 | 流量（单位：KB） |
| - | - |
请求补丁 | 5.5
下载补丁 | 28.59
补丁加载/执行结果上报 | 2.07
合计 | 36.16
*附注：*
*- 以上数据来自截至 2016-12-27 的最新版本 XMod，且为多个机型测试结果的均值。*
*- 请求补丁时会上传设备的基础参数，作为云端精准下发补丁的依据*。
*- 补丁加载/执行结果的上报，目的是作为质量闭环的基础数据。*

### XMod 性能数据

#### CPU 性能影响
| 场景 | CPU 时间（单位：jiffies） |
| - | - |
启动 XMod 主进程后 | 41
加载补丁后 | 51
检测到提权后 | 66
待机 15 小时后 | 96
*附注：以上数据来自截至 2016-12-27 的最新版本 XMod，且为多个机型测试结果的均值。*

#### 内存性能影响
| 场景 | 内存 PSS 均值（单位：KB） |
| - | - |
初始内存 | 14.840
补丁请求 | 15.954
补丁下载与加载 | 17.308
检测到提权 | 18.892
*附注：以上数据来自截至 2016-12-27 的最新版本 XMod，且为多个机型测试结果的均值。*

## SDK 形式接入指南

### 接入准备
1. 提供接入方 APK 的包名与签名 MD5 给 XMod 方，由其生成证书文件(以“.cert”为后缀命名)，把证书文件改名为“xmodclient.cert” 。
2. 将 xmodclient.cert 拷贝到客户端工程的 assets 目录下。
3. 将 xmodclient-1.0.jar 拷贝到客户端工程的 libs 目录下。
4. AndroidManifest.xml 权限配置。**（非常重要，请添加以下完整的配置）**

<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.MOUNT_UNMOUNT_FILESYSTEMS"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

*附：签名MD5获取方法*
*keytool -v -list -alias {别名} -keystore {签名文件，一般后缀为.keystore} -storepass {密钥库密码} -keypass {密钥密码}*

### 实现 AbsXModClient 的抽象方法
XModClient 1.0 提供了 AbsXModlient 抽象类。客户端首先需要继承 AbsXModClient 并实现其中的抽象方法：

private class MyXModClient extends AbsXModClient {
    public MyXMod(Context context) {
        super(context);
    }
    
    public abstract long onRootExploitAccepted(
        int pid, String packageName, String procPath) {
        // Your implementation.
    }
    // ...
}

AbsXModClient 的抽象方法包含以下三个，用于响应来自 XModService 的事件：

/**
 * XMod 主进程退出时被调用
 */
public abstract void onXModServiceDisconnected();

/**
 * XMod 检测到有进程执行 Root 提权操作并放行时
 * @param pid 提权的pid
 * @param packageName 提权的进程的 APK 包名
 * @param procPath 提权的进程的路径
 */
public abstract void onRootExploitAccepted(
    int pid, String packageName, String procPath);

/**
 * XMod 检测到有进程执行 Root 提权操作并拦截时
 * @param pid 提权的pid
 * @param packageName 提权的进程的 APK 包名
 * @param procPath 提权的进程的路径
 */
public abstract void onRootExploitDenied(
    int pid, String packageName, String procPath);

### 实现 XMod 的 IRootShell 接口
`IRootShell` 接口定义如下：

public interface IRootShell {
    String runCommandAsRoot(String command);
}

接入方需要实现该接口的 `runCommandAsRoot(String command)` 方法，接收一行 shell 命令，然后以 root 权限同步执行该命令并把命令执行的标准输出作为函数返回。实现的 `IRootShell` 在启动 XMod 的时候传入。

### 调用 AbsXModClient 的接口
AbsXModClient 提供以下方法，客户端可以直接调用。在调用其它方法之前，确保已成功启动 XMod 并已初始化连接（`startXMod()` 与 `init()` 均返回 `true`），否则会抛出 XModException 的异常。
| 方法 | 说明 |
| - | - |
boolean startXMod(IRootShell shell) | 启动 XMod 主进程。成功返回 `true`，失败返回 `false`。**该方法是所有 XMod 功能的基础，建议开机后尽早调用。**
boolean init() | 建立 XMod Client 与 XMod 主进程之间的连接，成功返回 `true`，失败返回 `false`。
String getXModVersion() | 返回 XMod 主进程的版本号字符串，例如 *1.2.3*。
int isPatchAvailable() | 查询当前手机是否有可用的 XMod 补丁，有则返回 `1`，没有返回 `0`，未确定（正在联网判断）则返回 `2`。
boolean enableRootExploitMonitor() | 开启 XMod 监听 Root 提权行为，开启成功返回 `true`，失败返回 `false`。
boolean disableRootExploitMonitor() | 关闭 XMod 监听 Root 提权行为，关闭成功返回 `true`，失败返回 `false`。
boolean isRootExploitMonitorEnabled() | 判断 XMod 是否开启了监听 Root 提权行为，开启返回 `true`，否则返回 `false`。
boolean close() | 断开 XMod Client 与 XMod 主进程之间的连接，不继续接收主进程的回调，也无法调用主进程的控制方法。成功返回 `true`，失败返回 `false`。

### Demo
我们提供了SDK Demo，方便接入方快速地、直观地了解如何使用XMod的相关服务。Demo 请见附件。