全部产品
存储与CDN 数据库 安全 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 阿里云办公 培训与认证 物联网

接口文档

更新时间:2017-07-14 14:31:10

1 内容简介

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

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

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

其中:

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

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

安全接口:提供了安全签名、安全加密和安全存储三大类接口。其中,安全签名和安全加密需要使用指定密钥Key。这里的“指定密钥Key”是指,在获取yw_1222_0335.jpg文件时同时获得的“密钥”,如“4bf1c***81ca”。

在使用安全签名和安全加密时,需要输入key值的位置,只需要填入“4bf1c***81ca”。

1.1 安全签名

安全签名基于HMAC_SHA1算法和指定密钥Key对数据进行加签,在传输数据时,可以利用加签的结果对传输数据进行数据校验。

以下图为例,在进行转账时,无签名的正常流程为如图2。

无签名的数据传输

(图2 无签名的数据传输)

但如图3,攻击者可以在数据传输时对数据进行劫持,并进行伪造或修改。

攻击者进行劫持

(图3 攻击者进行劫持)

此时,如图4,利用签名对数据进行校验,劫持者的伪造信息就可以被识别。

增加签名的数据传输

(图4 增加签名的数据传输)

1.2 安全加密

安全加密基于AES128算法和指定密钥Key对输入数据进行加密,加密过程完全在Native层实现,速度更快,较Java方法更加安全。

普通Java加密和聚安全加密相关对比,请参看下表:

项目 普通加密 聚安全安全加密
速度
密钥 存于Java代码中易被破解 加密存储在加密存储在yw_1222_0335.jpg文件中,使用沙箱保护,不直接暴露在代码中
安全性 不校验APK签名,易被重打包 校验APK签名,攻击者重打包后无法直接使用

1.3 安全存储

安全签名用于校验数据不同,安全存储是对输入数据进行加密然后存储在本地sharepreference中,保护用户以及客户端私有数据安全。对于客户的私有数据,如登录密码、用户名等敏感信息,以及客户端访问网络端获取的敏感信息如果直接明文存储在sharepreference中,极容易被攻击者利用。使用安全存储,会在写入sharepreference前进行加密,提升数据的安全性,避免被攻击者利用。以下图为例,直接存储明文密码易被窃取。

明文存储的密码易被窃取

(图5 明文存储的密码易被窃取)

如图6,使用安全存储后,数据在存储前会进行加密,增强数据安全。

安全存储进行加密存储

(图6 安全存储进行加密存储)

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_ISNULL101参数不正确,请检查输入的参数.
SEC_ERROR_INIT_SO_CHECK_ERROR1025.x版本之前:libsecurityguard***.so文件和无线保镖的jar包不匹配。请检验是否存在libsecurityguard***.so文件被破坏或修改的情况。
SEC_ERROR_INIT_LOADSO_FAIL1035.x版本之前:libsecurityguard.so文件装载问题,通常不会发生。如果发生此问题,可以卸载APK,再重新安装来尝试。5.x版本及之后:插件对应的内部so加载失败,请解压对应插件检查内部的so版本是否匹配。
SEC_ERROR_INIT_NO_RSA_FILE_ERROR1045.x版本之前:APK中没有正常的RSA签名文件。请检验签名过程。
SEC_ERROR_INIT_PUBLICKKEY_FIND_ERROR1055.x版本之前:RSA文件不正常,无法正常解析出公钥。
SEC_ERROR_INIT_SO_NOT_EXIST1065.x版本之前:在APK中找不到对应aebi的libsecurityguard.so文件,请检查是否正常打包了无线保镖SDK提供的so文件。(不同版本的不通用,请不要拿其他版本的替换)
SEC_ERROR_INIT_DECODESO_FAIL1075.x版本之前:libsecurityguard*.so解码失败,请卸载后全新安装或检查磁盘空间。
SEC_ERROR_INIT_LOADSOINNER_FAILED1085.x版本之前:加载内部so失败。
SEC_ERROR_INIT_FDSOFUN_FAILED1095.x版本之前:内部so运行失败。
SEC_ERROR_INIT_PLUGIN_NOT_EXISTED110插件不存在,请检查打包配置中,so是否正确打入APK中。
SEC_ERROR_INIT_PLUGIN_LOAD_FAILED111加载插件失败,一般不会发生。请检查是否存在IO异常或内存分配不足。
SEC_ERROR_INIT_LOAD_INTERFACE_NOT_EXISTED112获取接口失败,请检查传入的接口名称是否正确。
SEC_ERROR_INIT_PLUGIN_REQUIREMENT_NOT_MEET113插件依赖不匹配,请检查插件版本,查看依赖关系是否兼容。
SEC_ERROR_INIT_EXTRACT_DIR_NOT_EXISTED114系统IO异常,插件加载目录打开失败。
SEC_ERROR_INIT_UNKNOWN_ERROR199未知错误,请重试。

2.4示例程序

  1. import com.alibaba.wireless.security.jaq.JAQException;
  2. import com.alibaba.wireless.security.jaq.SecurityInit;
  3. //初始化
  4. try {
  5. SecurityInit.Initialize(getApplicationContext());
  6. } catch (JAQException e) {
  7. Log.e(TAG, "errorCode =" + e.getErrorCode());
  8. }

3 异常

3.1 异常说明

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

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

3.2 异常接口

public int getErrorCode()

功能:

获取错误码。

参数:

无。

返回值:

当前调用的错误码。

异常:

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

4 安全签名(SecuritySignature类)

4.1 安全签名说明

安全签名用于对输入数据进行加签,进而在方便在server端进行数据校验。

4.2 安全签名接口

public SecuritySignature(Context context)

功能:

初始化SecuritySignature类实例。

参数:

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

返回值:

无。

异常:

无。

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

功能:

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

参数:

input:待加签数据。

key:存储于yw_1222_0335.jpg文件中的指定密钥key。

返回值:

加签结果。

异常:

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

4.3 错误码

错误码含义
SEC_ERROR_SIGNATRUE_INVALID_INPUT601参数不正确,请检查输入的参数
SEC_ERROR_SIGNATURE_NO_MEM602内存分配失败,请重试
SEC_ERROR_SIGNATURE_NO_SEEDSECRET606使用带seedkey的top签名时,没有找到seedkey对应的seedsecret
SEC_ERROR_SIGNATURE_DATA_FILE_MISMATCH607图片文件存在问题。一般是获取图片文件时的apk签名和当前程序的apk签名不一致。请使用当前程序的apk重新生成图片
SEC_ERROR_SIGNATURE_NO_DATA_FILE608没有找到图片文件,请确保图片文件在res\drawable目录下
SEC_ERROR_SIGNATURE_INCORRECT_DATA_FILE609图片文件格式有问题,请重新生成图片文件
SEC_ERROR_SIGNATURE_INCORRECT_DATA_FILE_DATA610SEC_ERROR_SIGNATURE_INCORRECT_DATA_FILE_DATA
SEC_ERROR_SIGNATURE_KEY_NOT_EXSITED611参数中的key在图片文件中找不到,请确认图片文件中有这个key
SEC_ERROR_SIGNATURE_ILLEGEL_KEY612输入的key非法,key不能为:’:’,’|’,’/‘,’.’,’1’,’2’,’3’,’4’,’5’,’6’,’7’,’8’
SEC_ERROR_SIGNATURE_ATLAS_KEY_NOT_EXSITED613atlas密钥不存在
SEC_ERROR_SIGNATURE_LOW_VERSION_DATA_FILE615请升级新版本的图片,当前图片的版本太低
SEC_ERROR_SIGNATRUE_UNKNOWN699未知错误,请重试

4.4 示例程序

  1. import com.alibaba.wireless.security.jaq.JAQException;
  2. import com.alibaba.wireless.security.jaq.SecuritySignature;
  3. //安全签名
  4. SecuritySignature securitySignature = new SecuritySignature(getApplicationContext());
  5. try {
  6. //"helloword":待签名字串
  7. //"ka1":签名用的密钥key
  8. String signStr = securitySignature.sign("helloword", "ka1");
  9. //将签名结果和原始数据一起发送到服务端,服务端根据原始数据重新计算签名,并与发送的签名进行比对,进而完成数据校验。
  10. sendtoServer("helloword", signStr);
  11. }
  12. catch (JAQException e) {
  13. Log.e(TAG, "errorCode =" + e.getErrorCode());
  14. }

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:存储于yw_1222_0335.jpg文件中的指定密钥key。

返回值:

加密结果。

异常:

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

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

功能:

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

参数:

input:待加密数据。

key:存储于yw_1222_0335.jpg文件中的指定密钥key。

返回值:

加密结果。

异常:

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

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

功能:

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

参数:

input:待解密数据。

key:存储于yw_1222_0335.jpg文件中的密钥key。

返回值:

解密结果。

异常:

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

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

功能:

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

参数:

input:待解密数据。

key:存储于yw_1222_0335.jpg文件中的指定密钥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目录下
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_DECRYPT_MISMATCH_KEY_DATA 311 待解密数据与密钥不匹配
SEC_ERROR_STA_LOW_VERSION_DATA_FILE 312 请升级新版本的图片,当前图片的版本太低
SEC_ERROR_STA_STORE_UNKNOWN_ERROR 399 未知错误,请重试

5.4 示例程序

  1. import com.alibaba.wireless.security.jaq.JAQException;
  2. import com.alibaba.wireless.security.jaq.SecurityCipher;
  3. //安全加解密
  4. SecurityCipher securityCipher = new SecurityCipher(getApplicationContext());
  5. try {
  6. //加密字串
  7. //"helloword":待加密字串
  8. //"ka1":加密用的密钥key
  9. String encryptString = securityCipher.encryptString("helloword", "ka1");
  10. //解密字串
  11. //encryptString:待解密字串
  12. //"ka1":解密用的密钥key
  13. String decryptString = securityCipher.decryptString(encryptString, "ka1");
  14. byte[] dataBytes = {1,2,3,4,5,6,7,8,9,0};
  15. //加密数组
  16. //dataBytes :待加密数组
  17. //"ka1":加密用的密钥key
  18. byte[] encryptBytes = securityCipher.encryptBinary(dataBytes, "ka1");
  19. //解密数组
  20. //encryptBytes:待解密数组
  21. //"ka1":解密用的密钥key
  22. byte[] decryptBytes = securityCipher.decryptBinary(encryptBytes, "ka1");
  23. }
  24. catch (JAQException e) {
  25. Log.e(TAG, "errorCode =" + e.getErrorCode());
  26. }

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。

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 示例程序

  1. import com.alibaba.wireless.security.jaq.JAQException;
  2. import com.alibaba.wireless.security.jaq.SecurityStorage;
  3. //安全存储
  4. SecurityStorage securityStorage = new SecurityStorage(getApplicationContext());
  5. try {
  6. //保存"helloword"
  7. securityStorage.putString("mykey", "helloword");
  8. //获取"helloword"
  9. securityStorage.getString("mykey");
  10. //删除"helloword"
  11. securityStorage.removeString("mykey");
  12. }
  13. catch (JAQException e) {
  14. Log.e(TAG, "errorCode =" + e.getErrorCode());
  15. }

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 1009 未知错误,请重试

7.4 示例程序

  1. import com.alibaba.wireless.security.jaq.JAQException;
  2. import com.alibaba.wireless.security.jaq.SecurityCipher;
  3. //安全加解密
  4. SecurityCipher securityCipher = new SecurityCipher(getApplicationContext());
  5. try {
  6. //白盒加密字符串
  7. String encryptString = securityCipher. atlasEncryptString ("helloword");
  8. //白盒加密本地无法解密,需要将加密信息发送到服务器端解密
  9. sendServer(encryptString);
  10. } catch (JAQException e) {
  11. Log.e(TAG, "errorCode =" + e.getErrorCode());
  12. }

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 1006 图片文件中找不到秘钥数据,请确认图片是否正确。
SEC_ERROR_ATLAS_ENC_NO_MEMORY 1008 内存不足,请重试。
SEC_ERROR_ATLAS_ENC_UNKNOWN_ERROR 1009 未知错误,请重试

8.4 示例程序

  1. import com.alibaba.wireless.security.jaq.JAQException;
  2. import com.alibaba.wireless.security.jaq.SecuritySignature;
  3. //安全签名
  4. SecuritySignature securitySignature = new SecuritySignature(getApplicationContext());
  5. try {
  6. //"helloword":待签名的字串
  7. //签名使用的指定密钥key,在聚安全官网上获取
  8. String signStr = securitySignature. atlasSign("helloword", "259fa5c9-xxxx-yyyy-zzzz-bd10917ff388");
  9. //将签名结果和原始数据一起发送到服务端,服务端根据原始数据重新计算签名,并与客户端发送过来的签名信息进行比对,进而完成请求数据完整性校验。
  10. sendtoServer("helloword", signStr);
  11. } catch (JAQException e) {
  12. Log.e(TAG, "errorCode =" + e.getErrorCode());
  13. }
本文导读目录