1.内容简介

本文档针对聚安全安全组件的接口使用进行详细说明，在使用接口前，请先参考聚安全安全组件的接入说明，接入聚安全安全组件。

聚安全安全组件的主要接口如下表：

组件	类	说明
初始化	SecurityInit	负责全局初始化
异常	JAQException	接口调用异常
安全接口	SecuritySignature	安全签名、白盒签名
	SecurityCipher	安全加密、白盒加密
	SecurityStorage	安全存储

其中：

初始化：负责整个聚安全安全组件的同步初始化。

异常：调用初始化或安全接口时，当接口调用失败时会抛出JAQException异常。JAQException包含错误码，可以用来甄别具体错误类型。

安全接口：提供了安全签名、安全加密、安全存储、模拟器检测四大类接口。其中，安全签名、安全加密需要使用指定的安全秘钥。这里说的“安全密钥”是指在聚安全官网上生成SDK时随机自动生成的“密钥”。如图1所示，该安全秘钥默认是隐藏的。

图1.指定密钥key默认隐藏

点击“查看安全密钥”按钮即可显示该密钥，如图2。

图2.秘钥信息

如果在使用安全签名和安全加密功能时需要输入密钥KEY作为参数，只需填入上述“259fa***ff388”即可。

注意：

（1）安全组件SDK的加解密操作都是在自带的安全沙箱中进行的，对外并不暴露密钥和加密算法。应用在调用加解密接口的时候传入上述“安全密钥”，“安全密钥”会去沙箱中索引真正的密钥进行加解密操作。因此，这个“安全密钥”并不是我们传统意义上加密算法使用的密钥，而是一个密钥的索引。同时，我们的秘钥信息和应用强绑定，黑客即使通过逆向手段拿到该密钥索引，也无法获取安全沙箱中执行加解密操作的真正密钥。

（2）白盒加密和白盒签名采用了更为安全和先进的白盒加密技术（通过大量的查表运算）对数据进行加密和签名操作，整个加密过程不会有秘钥的参与。因此，白盒技术不存在秘钥泄露的风险，安全性上大大超越传统的安全加密技术。

2.初始化（SecurityInit类）

2.1.初始化说明

初始化负责完成整个聚安全安全组件的全局初始化。初始化是线程安全的，初始化调用只需要进行一次，无需重复调用。

在使用安全接口时，如检测到聚安全安全组件未初始化，初始化会被默认执行。但是建议在使用安全接口时首先进行初始化，并判断初始化是否成功，方便查找原因。

2.2.初始化接口

public static int Initialize(Context context) throws JAQException

功能：

聚安全安全组件初始化。

参数：

context：任意Activity、Service等Coxtext类非空实例。

返回值：

初始化成功，返回0。

初始化失败，返回1。

异常：

初始化过程中出现异常时，会抛出 JAQException 异常。可以根据 JAQException 实例的 getErrorCode() 方法获取错误码。

2.3.错误码

错误码	值	含义
SEC_ERROR_INIT_CONTEXT_ISNULL	101	参数不正确，请检查输入的参数。
SEC_ERROR_INIT_SO_CHECK_ERROR	102	libsgmain.so文件和无线保镖的jar包不匹配。请检验是否存在libsgmain.so文件被破坏或修改的情况。
SEC_ERROR_INIT_LOADSO_FAIL	103	libsgmain.so文件装载问题，通常不会发生。如果发生此问题，可以卸载APK，再重新安装来尝试。
SEC_ERROR_INIT_NO_RSA_FILE_ERROR	104	APK中没有正常的RSA签名文件。请检验签名过程。
SEC_ERROR_INIT_PUBLICKKEY_FIND_ERROR	105	RSA文件不正常，无法正常解析出公钥。
SEC_ERROR_INIT_SO_NOT_EXIST	106	在APK中找不到对应 aebi 的 libsgmain.so 文件，请检查是否正常打包了无线保镖SDK提供的so文件。（不同版本的so和jar不能混用）
SEC_ERROR_INIT_UNKNOWN_ERROR	199	未知错误，请重试。

2.4.示例程序

import com.alibaba.wireless.security.jaq.JAQException;
import com.alibaba.wireless.security.jaq.SecurityInit;

   //初始化
	try {
		SecurityInit.Initialize(getApplicationContext());
	} catch (JAQException e) {
		Log.e(TAG, "errorCode =" + e.getErrorCode());
	}

3.异常（JAQException类）

3.1.异常说明

当初始化或安全接口调用内部出现异常时，会以 JAQException 的形式抛出异常。

JAQException 类提供了 getErrorCode() 方法获取错误码。

3.2.异常接口

public int getErrorCode()

功能：

获取错误码。

参数：

无。

返回值：

当前调用的错误码。

异常：

初始化过程中出现异常时，会抛出 JAQException 异常。可以根据 JAQException 实例的 getErrorCode() 方法获取错误码。

4.安全签名（SecuritySignature类）

4.1.安全签名说明

安全签名是对客户端请求的数据进行加签，进而在服务器端对数据进行校验的过程。可以有效防止请求被篡改、中间人劫持等恶意攻击场景。

4.2.安全签名接口

public SecuritySignature(Context context)

功能：

初始化SecuritySignature类实例。

参数：

context：任意Activity、Service等Coxtext类非空实例。

返回值：

无。

异常：

无。

public String sign(String input, String key) throws JAQException

功能：

使用密钥key对输入数据进行签名。

参数：

input：待加签数据。

key：在聚安全网站上获取指定密钥key。

返回值：

加签结果。

异常：

出现异常时，会抛出 JAQException 异常。可以根据 JAQException 实例的 getErrorCode() 方法获取错误码。

4.3.错误码

错误码	值	含义
SEC_ERROR_SIGNATRUE_INVALID_INPUT	601	参数不正确，请检查输入的参数
SEC_ERROR_SIGNATURE_NO_MEM	602	内存分配失败，请重试
SEC_ERROR_SIGNATURE_NO_SEEDSECRET	606	使用带seedkey的top签名时，没有找到seedkey对应的seedsecret
SEC_ERROR_SIGNATURE_DATA_FILE_MISMATCH	607	图片文件存在问题。一般是获取图片文件时的apk签名和当前程序的apk签名不一致。请使用当前程序的apk重新生成图片
SEC_ERROR_SIGNATURE_NO_DATA_FILE	608	没有找到图片文件，请确保图片文件在 res\drawable 目录下。如果是 Android Studio 工程中开启了 shrinkResources 优化，需要将安全组件的图片文件排除
SEC_ERROR_SIGNATURE_INCORRECT_DATA_FILE	609	图片文件格式有问题，请重新生成图片文件
SEC_ERROR_SIGNATURE_INCORRECT_DATA_FILE_DATA	610	图片文件内的内容不正确，请重新生成图片文件
SEC_ERROR_SIGNATURE_KEY_NOT_EXSITED	611	参数中的key在图片文件中找不到，请确认key和图片文件配套
SEC_ERROR_SIGNATURE_ILLEGEL_KEY	612	输入的key非法，key不能为：‘:’, ‘|’, ‘/’, ‘.’,‘1’,‘2’,‘3’,‘4’,‘5’,‘6’,‘7’,‘8’
SEC_ERROR_SIGNATRUE_UNKNOWN	613	未知错误

4.4.示例程序

import com.alibaba.wireless.security.jaq.JAQException;
import com.alibaba.wireless.security.jaq.SecuritySignature;

	//安全签名
	SecuritySignature securitySignature = new SecuritySignature(getApplicationContext());
	try {
        // "helloword"：待签名的字串
        // 签名使用的指定密钥key，在聚安全官网上获取
		String signStr = securitySignature.sign("helloword", "259fa5c9-xxxx-yyyy-zzzz-bd10917ff388");
       //将签名结果和原始数据一起发送到服务端，服务端根据原始数据重新计算签名，并与发送的签名进行比对，进而完成数据完整性校验。
       sendtoServer("helloword", signStr);
	} catch (JAQException e) {
		Log.e(TAG, "errorCode =" + e.getErrorCode());
	}

5.安全加密（SecurityCipher类）

5.1.安全加密说明

安全加密用于对输入的明文数据进行加密，然后返回密文。

5.2.安全加密接口

public SecurityCipher(Context context)

功能：

初始化 SecurityCipher 类实例。

参数：

context：任意Activity、Service等Coxtext类非空实例。

返回值：

无。

异常：

无。

public String encryptString(String input, String key) throws JAQException

功能：

使用指定密钥key对输入的字符串数据进行加密。

参数：

input：待加密字符串数据。

key：在聚安全官网上获取的指定密钥key。

返回值：

加密结果。

异常：

出现异常时，会抛出 JAQException 异常。可以根据 JAQException 实例的 getErrorCode() 方法获取错误码。

public byte[] encryptBinary(byte[] input, String key) throws JAQException

功能：

使用指定密钥key对输入的二进制数据进行加密。

参数：

input：待加密的二进制数据。

key：在聚安全官网上获取的指定密钥key。

返回值：

加密结果。

异常：

出现异常时，会抛出 JAQException 异常。可以根据 JAQException 实例的 getErrorCode() 方法获取错误码。

public String decryptString(String input, String key) throws JAQException

功能：

使用指定密钥key对输入的字符串数据进行解密。

参数：

input：待解密字符串数据。

key：在聚安全官网上获取的指定密钥key。

返回值：

解密结果。

异常：

出现异常时，会抛出 JAQException 异常。可以根据 JAQException 实例的 getErrorCode() 方法获取错误码。

public byte[] decryptBinary(byte[] input, String key) throws JAQException

功能：

使用指定密钥key对输入的二进制数据进行解密。

参数：

input：待解密二进制数据。

key：在聚安全官网上获取的指定密钥key。

返回值：

解密结果。

异常：

出现异常时，会抛出 JAQException 异常。可以根据 JAQException 实例的 getErrorCode() 方法获取错误码。

5.3.错误码

错误码	值	含义
SEC_ERROR_STA_INVALID_PARAM	301	参数不正确，请检查输入的参数
SEC_ERROR_STA_DATA_FILE_MISMATCH	302	图片文件有问题。一般是获取图片文件时的apk签名和当前程序的apk签名不一致。请使用当前程序的apk重新生成图片
SEC_ERROR_STA_NO_DATA_FILE	303	没有找到图片文件，请确保图片文件在res\drawable目录下。如果是Android Studio工程中开启了shrinkResources优化，需要将安全组件的图片文件排除
SEC_ERROR_STA_INCORRECT_DATA_FILE	304	图片文件格式有问题，请重新生成图片文件
SEC_ERROR_STA_INCORRECT_DATA_FILE_DATA	305	图片文件内的内容不正确，请重新生成图片文件
SEC_ERROR_STA_KEY_NOT_EXISTED	306	参数中的key在图片文件中找不到，请确认图片文件中有这个key
SEC_ERROR_STA_ILLEGEL_KEY	307	输入的key非法，key不能为：‘:’, ‘|’, ‘/’, ‘.’, ‘1’, ‘2’,‘3’,‘4’,‘5’,‘6’,‘7’,‘8’
SEC_ERROR_STA_NO_MEMORY	308	内存不足，请重试
SEC_ERROR_STA_NO_SUCH_INDEX	309	在图片文件中没有找到这个index
SEC_ERROR_STA_INVALID_ENCRYPTED_DATA	310	非法的加密数据
SEC_ERROR_STA_STORE_UNKNOWN_ERROR	399	未知错误，请重试

5.4.示例程序

import com.alibaba.wireless.security.jaq.JAQException;
import com.alibaba.wireless.security.jaq.SecurityCipher;

	//安全加解密
	SecurityCipher securityCipher = new SecurityCipher(getApplicationContext());

	try {
		//加密字符串
		String encryptString = securityCipher.encryptString("helloword", "259fa5c9-xxxx-yyyy-zzzz-bd10917ff388");
		
		//解密字符串
		String decryptString = securityCipher.decryptString(encryptString, "259fa5c9-xxxx-yyyy-zzzz-bd10917ff388");
		
		byte[] dataBytes = {1,2,3,4,5,6,7,8,9,0};
		
		//加密二进制
		byte[] encryptBytes = securityCipher.encryptBinary(dataBytes, "259fa5c9-xxxx-yyyy-zzzz-bd10917ff388");
		
		//解密二进制
		byte[] decryptBytes = securityCipher.decryptBinary(encryptBytes, "259fa5c9-xxxx-yyyy-zzzz-bd10917ff388");
		
	} catch (JAQException e) {
		Log.e(TAG, "errorCode =" + e.getErrorCode());
	}

6.安全存储（SecurityStorage类）

6.1.安全存储说明

安全存储对应用的敏感数据进行加密存储在本地。

6.2.安全存储接口

public SecurityStorage (Context context)

功能：

初始化SecurityStorage类实例。

参数：

context：任意Activity、Service等Coxtext类非空实例。

返回值：

无。

异常：

无。

public int putString(String key, String value) throws JAQException

功能：

保存数据。

参数：

key：索引value的key，自定义即可。

value：待存储的数据。

返回值：

存储成功返回1，否则返回0。

异常：

出现异常时，会抛出 JAQException 异常。可以根据 JAQException 实例的 getErrorCode() 方法获取错误码。

public void removeString(String key) throws JAQException

功能：

删除数据。

参数：

key：索引value的key。

返回值：

无返回值。

异常：

出现异常时，会抛出 JAQException 异常。可以根据 JAQException 实例的 getErrorCode() 方法获取错误码。

public String getString(String key) throws JAQException

功能：

获取数据。

参数：

key：索引value的key。

返回值：

返回值为原始保存的数据

异常：

出现异常时，会抛出 JAQException 异常。可以根据 JAQException 实例的 getErrorCode() 方法获取错误码。

6.3.错误码

错误码	值	含义
SEC_ERROR_DYN_STORE_INVALID_PARAM	501	参数不正确，请检查输入的参数
SEC_ERROR_DYN_STORE_NO_MEMORY	502	内存不足，请重试
SEC_ERROR_DYN_STORE_GET_SYS_PROPERTIES_FAILED	503	获取系统属性失败，请确认是否有软件拦截，获取系统参数
SEC_ERROR_DYN_STORE_GET_DATA_FILE_KEY_FAILED	504	获取图片文件的密钥失败，请确认图片文件的格式和内容是否正确
SEC_ERROR_DYN_STORE_GET_ENCRYPT_KEY_FAILED	505	获取动态加密密钥失败，请重试
SEC_ERROR_DYN_STORE_INVALID_ENCRYPTED_DATA	506	待解密数据不是可解密数据
SEC_ERROR_DYN_STORE_DECRYPT_MISMATCH_KEY_DATA	507	待解密数据与密钥不匹配，请重试
SEC_ERROR_DYN_STORE_DDPEX_KEY_VALUE_NOT_EXSIT	508	传入key对应的value不存在
SEC_ERROR_DYN_STORE_UNKNOWN_ERROR	599	未知错误，请重试

6.4.示例程序

import com.alibaba.wireless.security.jaq.JAQException;
import com.alibaba.wireless.security.jaq.SecurityStorage;

	//安全存储
	SecurityStorage securityStorage = new SecurityStorage(getApplicationContext());
	try {
		//保存"helloword"
		securityStorage.putString("mykey", "helloword");
		
		//获取"helloword"
		String str = securityStorage.getString("mykey");
		
		//删除"helloword"
		securityStorage.removeString("mykey");
		
	} catch (JAQException e) {
		Log.e(TAG, "errorCode =" + e.getErrorCode());
	}

7.白盒加密（SecurityCipher类）

7.1.白盒加密说明

白盒加密技术是使用白盒算法对输入的明文数据进行加密，然后返回密文。安全性上远远超越普通的安全加密。

7.2.白盒加密接口

public SecurityCipher(Context context)

功能：

初始化SecurityCipher类实例。

参数：

context：任意Activity、Service等Coxtext类非空实例。

返回值：

无。

异常：

无。

public String atlasEncryptString(String text) throws JAQException

功能：

采用白盒方式加密数据。

参数：

text：待加密的数据。

返回值：

加密结果。

异常：

出现异常时，会抛出 JAQException 异常。可以根据 JAQException 实例的 getErrorCode() 方法获取错误码。

7.3.错误码

错误码	值	含义
SEC_ERROR_ATLAS_ENC_INVALID_PARAM	1001	参数不正确，请检查输入的参数
SEC_ERROR_ATLAS_ENC_DATA_FILE_MISMATCH	1002	图片文件有问题。一般是获取图片文件时的apk签名和当前程序的apk签名不一致。请使用当前程序的apk重新生成图片
SEC_ERROR_ATLAS_ENC_NO_DATA_FILE	1003	没有找到图片文件，请确保图片文件在res\drawable目录下
SEC_ERROR_ATLAS_ENC_INCORRECT_DATA_FILE	1004	图片文件格式有问题，请重新生成图片文件
SEC_ERROR_ATLAS_ENC_NO_KEY	1006	图片文件中找不到秘钥数据，请确认图片是否正确
SEC_ERROR_ATLAS_ENC_NO_MEMORY	1008	内存不足，请重试
SEC_ERROR_ATLAS_ENC_UNKNOWN_ERROR	1099	未知错误，请重试

7.4.示例程序

import com.alibaba.wireless.security.jaq.JAQException;
import com.alibaba.wireless.security.jaq.SecurityCipher;

	//安全加解密
	SecurityCipher securityCipher = new SecurityCipher(getApplicationContext());

	try {
		//白盒加密字符串
		String encryptString = securityCipher. atlasEncryptString ("helloword");
        //白盒加密本地无法解密，需要将加密信息发送到服务器端解密
        sendServer(encryptString);
	} catch (JAQException e) {
		Log.e(TAG, "errorCode =" + e.getErrorCode());
	}

8.白盒签名（SecuritySignature类）

8.1.白盒签名说明

白盒签名使用白盒加密技术对输入的数据进行加签，进而在服务器端进行数据校验。可以有效防止请求被篡改、中间人劫持等恶意攻击场景。安全性上远远超越普通的安全签名。

8.2.白盒签名接口

public SecuritySignature(Context context)

功能：

初始化SecuritySignature类实例。

参数：

context：任意Activity、Service等Coxtext类非空实例。

返回值：

无。

异常：

无。

public String atlasSign(String input, String key) throws JAQException

功能：

使用白盒算法对输入数据进行签名。

参数：

input：待加签数据。

key：在聚安全网站上获取指定密钥key。

返回值：

加签结果。

异常：

出现异常时，会抛出 JAQException 异常。可以根据 JAQException 实例的 getErrorCode() 方法获取错误码。

8.3.错误码

错误码	值	含义
SEC_ERROR_SIGNATRUE_INVALID_INPUT	601	参数不正确，请检查输入的参数
SEC_ERROR_SIGNATURE_NO_MEM	602	内存分配失败，请重试
SEC_ERROR_SIGNATURE_NO_SEEDSECRET	606	使用带seedkey的top签名时，没有找到seedkey对应的seedsecret
SEC_ERROR_SIGNATURE_DATA_FILE_MISMATCH	607	图片文件存在问题。一般是获取图片文件时的apk签名和当前程序的apk签名不一致。请使用当前程序的apk重新生成图片
SEC_ERROR_SIGNATURE_NO_DATA_FILE	608	没有找到图片文件，请确保图片文件在res\drawable目录下。如果是Android Studio工程中开启了shrinkResources优化，需要将安全组件的图片文件排除。
SEC_ERROR_SIGNATURE_INCORRECT_DATA_FILE	609	图片文件格式有问题，请重新生成图片文件
SEC_ERROR_SIGNATURE_INCORRECT_DATA_FILE_DATA	610	图片文件内的内容不正确，请重新生成图片文件
SEC_ERROR_SIGNATURE_KEY_NOT_EXSITED	611	参数中的key在图片文件中找不到，请确认图片文件中有这个key
SEC_ERROR_SIGNATURE_ILLEGEL_KEY	612	输入的key非法，key不能为：‘:’, ‘|’, ‘/’, ‘.’, ‘1’, ‘2’,‘3’,‘4’,‘5’,‘6’,‘7’,‘8’
SEC_ERROR_SIGNATRUE_UNKNOWN	613	未知错误

8.4.示例程序

import com.alibaba.wireless.security.jaq.JAQException;
import com.alibaba.wireless.security.jaq.SecuritySignature;

	//安全签名
	SecuritySignature securitySignature = new SecuritySignature(getApplicationContext());
	try {
        //"helloword"：待签名的字串
        //签名使用的指定密钥key，在聚安全官网上获取
		String signStr = securitySignature. atlasSign("helloword", "259fa5c9-xxxx-yyyy-zzzz-bd10917ff388");
       //将签名结果和原始数据一起发送到服务端，服务端根据原始数据重新计算签名，并与客户端发送过来的签名信息进行比对，进而完成请求数据完整性校验。
       sendtoServer("helloword", signStr);
	} catch (JAQException e) {
		Log.e(TAG, "errorCode =" + e.getErrorCode());
	}

FAQ

关于此文档暂时还没有FAQ