感谢您的反馈！
阿里聚安全
安全组件-客户端接口说明（iOS）
更新时间：2017/07/14
访问次数：12171
1.内容简介
本文档针对聚安全安全组件的接口使用进行详细说明，在使用接口前，请先参考客户端环境配置文档，配置好接入环境。
阿里聚安全安全组件的主要接口如下表：
| 组件 | 类 | 说明 |
|---|---|---|
| 安全接口 | SecuritySignature | 安全签名、白盒签名 |
| SecurityCipher | 安全加密、白盒加密 | |
| SecurityStorage | 安全存储 |
安全接口：iOS版安全组件提供了安全签名、安全加密、安全存储三大类接口。其中，安全签名、安全加密需要使用指定的安全秘钥。这里说的“安全密钥”是指在聚安全官网上生成SDK时随机自动生成的“密钥”。如图1所示，该安全秘钥默认是隐藏的。
图1.指定密钥key默认隐藏
点击“查看安全密钥”按钮即可显示该密钥，如图2。
如果在使用安全签名和安全加密功能时需要输入密钥key作为参数，只需填入上述“259fa***ff388”即可。
注意：
（1） 安全组件SDK的加解密操作都是在自带的安全沙箱中进行的，对外并不暴露密钥和加密算法。上述的“安全密钥”其实是沙箱中真正做加解密操作的密钥的索引。同时，我们的秘钥信息和应用强绑定，黑客即使通过逆向手段拿到该密钥索引，也无法获取安全沙箱中的真正密钥。
（2） 白盒加密和白盒签名采用了更为安全和先进的白盒加密技术（通过大量的查表运算）对数据进行加密和签名操作，整个加密过程不会有秘钥的参与。因此，白盒技术不存在秘钥泄露的风险，安全性上大大超越传统的安全加密技术。
2.安全签名（SecuritySignature类）
2.1.安全签名说明
安全签名用于对输入数据进行加签，进而在方便在server端进行数据校验。
2.2.安全签名接口
+ (NSString*) sign: (NSString*) input key: (NSString*) key;
功能：
使用密钥key对输入数据进行签名。
参数：
input：待加签数据。
key：在聚安全网站上获取指定密钥key。
返回值：
加签结果。
异常：
接口不抛异常。当调用出错的时候，会在命令行中打印相应的错误日志,错误日志以SG ERROR开头，错误码的详细定义请见2.3。
2.3.错误码
| 错误码 | 值 | 含义 |
|---|---|---|
| SEC_ERROR_SIGNATRUE_INVALID_INPUT | 601 | 参数不正确，请检查输入的参数 |
| SEC_ERROR_SIGNATURE_NO_MEM | 602 | 内存分配失败，请重试 |
| SEC_ERROR_SIGNATURE_DATA_FILE_MISMATCH | 607 | 图片文件存在问题。一般情况是生成图片时的bundle id和应用的bundle id不匹配 |
| SEC_ERROR_SIGNATURE_NO_DATA_FILE | 608 | 没有找到图片文件，请确保图片文件在项目目录下。 |
| 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_LOW_VERSION_DATA_FILE | 615 | 请升级新版本v4的图片，当前图片的版本太低 |
| SEC_ERROR_SIGNATRUE_UNKNOWN | 699 | 位置错误，请重试 |
2.4.示例程序
#import <SecurityGuardSDK/JAQ/SecuritySignature.h>
@implementation SGTestJAQSecuritySignature
- (void) testJAQSecuritySignature
{
NSString* key = @"3b81f8ee-f2ef-4459-8c67-7bd5b75e8263";
NSString* valueToSign = @"valuetosign=test&method=md5";
NSString* result = [SecuritySignature sign: valueToSign key: key];
if (result.length) {
NSLog(@"The signature is : %@", result);
//发送到服务器端验签名
// ……
}
}
@end
3.安全加密（SecurityCipher类）
3.1.安全加密说明
安全加密用于对输入的明文数据进行加密，然后返回密文。
3.2.安全加密接口
+ (NSString*) encryptString: (NSString*) input key: (NSString*) key;
功能：
使用指定密钥key对输入的字符串数据进行加密。
参数：
input：待加密字符串数据。
key：在聚安全官网上获取的指定密钥key。
返回值：
加密结果。
异常：
接口不抛异常。当调用出错的时候，会在命令行中打印相应的错误日志,错误日志以SG ERROR开头，错误码的详细定义请见3.3。
+ (NSData*) encryptBinary: (NSData*) input key: (NSString*) key;
功能：
使用指定密钥key对输入的二进制数据进行加密。
参数：
input：待加密的二进制数据。
key：在聚安全官网上获取的指定密钥key。
返回值：
加密结果。
异常：
接口不抛异常。当调用出错的时候，会在命令行中打印相应的错误日志,错误日志以SG ERROR开头，错误码的详细定义请见3.3。
+ (NSString*) decryptString: (NSString*) input key: (NSString*) key;
功能：
使用指定密钥key对输入的字符串数据进行解密。
参数：
input：待解密字符串数据。
key：在聚安全官网上获取的指定密钥key。
返回值：
解密结果。
异常：
接口不抛异常。当调用出错的时候，会在命令行中打印相应的错误日志,错误日志以SG ERROR开头，错误码的详细定义请见3.3。
+ (NSData*) decryptBinary: (NSData*) input key: (NSString*) key;
功能：
使用指定密钥key对输入的二进制数据进行解密。
参数：
input：待解密的二进制数据。
key：在聚安全官网上获取的指定密钥key。
返回值：
解密结果。
异常：
接口不抛异常。当调用出错的时候，会在命令行中打印相应的错误日志,错误日志以SG ERROR开头，错误码的详细定义请见3.3。
3.3.错误码
| 错误码 | 值 | 含义 |
|---|---|---|
| SEC_ERROR_STA_INVALID_PARAM | 301 | 参数不正确，请检查输入的参数 |
| SEC_ERROR_STA_DATA_FILE_MISMATCH | 302 | 图片文件有问题。一般情况是生成图片时的bundle id和应用的bundle id不匹配 |
| SEC_ERROR_STA_NO_DATA_FILE | 303 | 没有找到图片文件，请确保图片文件在项目目录下 |
| 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_NO_MEMORY | 308 | 内存不足，请重试 |
| SEC_ERROR_STA_INVALID_ENCRYPTED_DATA | 310 | 非法的加密数据 |
| SEC_ERROR_STA_STORE_UNKNOWN_ERROR | 399 | 未知错误，请重试 |
3.4.示例程序
#import <SecurityGuardSDK/JAQ/SecurityCipher.h>
@implementation SGTestJAQSecurityCipher
- (void) testJAQSecurityCipher
{
NSString* key = @"3b81f8ee-f2ef-4459-8c67-7bd5b75e8263";
NSString* stringToEncrypt = @"thisastringtoencryptwithalibabajaqserverices";
//加密字符串
NSString* encryptedString = [SecurityCipher encryptString: stringToEncrypt key: key];
//解密字符串
NSString* plainString = [SecurityCipher decryptString: encryptedString key: key];
if ([plainString isEqualToString: stringToEncrypt]) {
NSLog(@"The string encrpytion is a success!");
}
char buf[] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
NSData* dataToEncrypt = [NSData dataWithBytes: buf length: 10];
//加密byte数组
NSData* encryptedData = [SecurityCipher encryptBinary: dataToEncrypt key: key];
//解密byte数组
NSData* plainData = [SecurityCipher decryptBinary: encryptedData key: key];
if ([plainData isEqualToData: dataToEncrypt]) {
NSLog(@"The Data encrpytion is a success!");
}
}
@end
4.安全存储（SecurityStorage类）
4.1.安全存储说明
安全存储对应用的敏感数据进行加密存储在本地。
4.2.安全存储接口
+ (NSInteger) putString: (NSString*) value key: (NSString*) key;
功能：
保存数据。
参数：
key：索引value的key，自定义即可。
key：value待存储的数据。
返回值：
存储成功返回1，否则返回0.
异常：
接口不抛异常。当调用出错的时候，会在命令行中打印相应的错误日志,错误日志以SG ERROR开头，错误码的详细定义请见4.3。
+ (void) removeString: (NSString*) key;
功能：
删除数据。
参数：
key：索引value的key。
返回值：
无返回值
异常：
接口不抛异常。当调用出错的时候，会在命令行中打印相应的错误日志,错误日志以SG ERROR开头，错误码的详细定义请见4.3。
+ (NSString*) getString: (NSString*) key;
功能：
获取数据。
参数：
key：索引value的key。
返回值：
返回值为原始保存的数据
异常：
接口不抛异常。当调用出错的时候，会在命令行中打印相应的错误日志,错误日志以SG ERROR开头，错误码的详细定义请见4.3。
4.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 | 未知错误，请重试 |
4.4.示例程序
#import <SecurityGuardSDK/JAQ/SecurityStorage.h>
@implementation SGTestJAQSecurityStorage
- (void)testJAQSecurityStorage
{
NSString* stringToStore = @"iamastringtostore";
NSString* myKey = @"myKey";
//存储string
[SecurityStorage putString: stringToStore key: myKey];
//获取存储的值
NSString* storedString = [SecurityStorage getString: myKey];
//清空存储的值
[SecurityStorage removeString: myKey];
if ([storedString isEqualToString: stringToStore]) {
NSLog(@"The String storage is a success.");
}
}
5.白盒签名（SecuritySignature类）
5.1.白盒签名说明
白盒签名使用白盒加密技术对输入的数据进行加签，进而在服务器端进行数据校验。可以有效防止请求被篡改、中间人劫持等恶意攻击场景。安全性上远远超越普通的安全签名。
5.2.白盒签名接口
+ (NSString*) atlasSign: (NSString*) input key: (NSString*) key;
功能：
使用白盒算法对输入数据进行签名。
参数：
input：待加签数据。
key：在聚安全网站上获取指定密钥key。
返回值：
加签结果。
异常：
接口不抛异常。当调用出错的时候，会在命令行中打印相应的错误日志,错误日志以SG ERROR开头，错误码的详细定义请见2.3。
5.3.示例程序
#import <SecurityGuardSDK/JAQ/SecuritySignature.h>
@implementation SGTestJAQSecuritySignature
- (void) testJAQSecuritySignature
{
NSString* key = @"3b81f8ee-f2ef-4459-8c67-7bd5b75e8263";
NSString* valueToSign = @"valuetosign=test&method=md5";
NSString* result = [SecuritySignature atlasSign: valueToSign key: key];
if (result.length) {
NSLog(@"The signature is : %@", result);
//发送到服务器端验签名
// ……
}
}
@end
6.白盒加密（SecurityCipher类）
6.1.白盒加密说明
白盒加密技术是使用白盒算法对输入的明文数据进行加密，然后返回密文。安全性上远远超越普通的安全加密。
6.2.白盒加密接口
+ (NSString*) atlasEncryptString: (NSString*) input;
功能：
采用白盒方式加密数据。
参数：
input：待加密字符串数据。
返回值：
加密结果。
异常：
接口不抛异常。当调用出错的时候，会在命令行中打印相应的错误日志,错误日志以SG ERROR开头，错误码的详细定义请见3.3。
6.3.示例程序
#import <SecurityGuardSDK/JAQ/SecurityCipher.h>
@implementation SGTestJAQSecurityCipher
- (void) testJAQSecurityCipher
{
NSString* stringToEncrypt = @"WhiteboxEncryptTest";
//加密字符串
NSString* encryptedString = [SecurityCipher atlasEncryptString: stringToEncrypt];
//白盒加密需要发送到服务器端解密
//……
}
@end