1场景需求

ISV大致确认自己的接入方案和加密方案后，进入开发阶段。需要首先下载最新的TOP SDK。以下是代码开发介绍，分成3个部分：首先介绍SDK中的api, 第二部分是代码开发的规范，最后列举了再各个场景下的一些代码Demo。

请注意，为了性能和稳定性，代码规范请务必要注意遵守！

2方案介绍

2.1 API介绍

	作用	参数
SecurityClient (constructor)	初始化
securityClient.encrypt	自动用最新版本密钥将数据加密	可批量传入数据，批量返回
securityClient.encryptPrevious	自动用上一版本密钥将数据加密(在密钥变更迁移中可能用到)	可批量传入数据，批量返回
securityClient.decrypt	自动判断密文版本，用对应版本密钥解密数据	可批量传入数据，批量返回
securityClient.isEncrypt
securityClient.search	生成给定字符串的模糊查询

初始化：

SecurityClient SecurityClient = new SecurityClient(new DefaultTaobaoClient(serverUrl, appkey, appSecret), randomNumber)

注1: defaultTaobaoClient 使用的serverUrl必须是https协议

加密：

securityClient.encrypt(“13888883333”, type, sessionKey)

密文判断:

SecurityClient.isEncrypt(“13888883333”, type)

上一版本密钥加密：

securityClient.encryptPrevious(“13888883333”, type, sessionKey)

解密：

securityClient.decrypt(“~CKoqAl2hWzh54uBFv9Suug==~1~”, type, sessionKey)

模糊搜索子句：

String searchIndex = securityClient. search(“3333”, type, sessionKey)

SELECT * FROM table_orders WHERE phone LIKE #searchIndex#%

(此例为手机号码，其余例子见下面分场景详述)

2.2加密调用规范：

1）全部用主账号的sessionkey，子账号可能没有权限

2）调用之前前置判断sessionkey

3）授权返回sessionkey带了过期时间

4）判断sessionkey的过期时间+90天是否已经超过，如果过期超过90天，不需要调用加、解密（在重新授权之前永远不可能成功，浪费资源），假设客户端存在误判，实际调用加、解密可能抛异常。可以采用以下方案：

try {

// 加、解密操作

} catch (SecretException e) {

if(ErrorUtil.isInvalidSession(e)) {

// 标记该sessionkey无效，重新授权之前不要再调用

}

}

2.3代码场景示例：

1)初始化:

SecurityClient securityClient

= new SecurityClient (new DefaultTaobaoClient(serverUrl, appkey, appSecret), Random Number);

defaultTaobaoClient serverUrl必须是https协议,目前是https://eco.taobao.com/router/rest(沙箱环境 ：https://gw.api.tbsandbox.com/router/rest)

2)加解密：

receiver_mobile 加密字段类型(type)是phone。其他加密字段类型(type)是根据字段查询方式：普通加密方式的字段类型(type)为simple模糊查询的字段类型(type)为 search.

加、解密入参必须带上sessionkey

输出结果：

手机号码明文：13834566786 ->密文：$138$SuR++h6AtlSj8Z59W2W9EQ==$103$

手机号码密文：$138$SuR++h6AtlSj8Z59W2W9EQ==$103$ ->明文：13834566786

=========================TOP=======================

nick明文：taobaoTEST ->密文：~CKoqAl2hWzh54uBFv9Suug==~103~

nick密文：~CKoqAl2hWzh54uBFv9Suug==~103~ ->明文：taobaoTEST

3)批量加、解密

输出结果：

手机号码明文：15923847823 ->密文：$159$AtyBFui4xvl92WV7GKwfBw==$103$

手机号码明文：13834566786 ->密文：$138$SuR++h6AtlSj8Z59W2W9EQ==$103$

手机号码密文：$138$SuR++h6AtlSj8Z59W2W9EQ==$103$ ->明文：13834566786

手机号码密文：$159$AtyBFui4xvl92WV7GKwfBw==$103$ ->明文：15923847823

==========================TOP========================

nick明文：taobaoTEST2 ->密文：~nID/f9qCBqgm7MXZSXBpfA==~103~

nick明文：taobaoTEST1 ->密文：~kgRCprD8gH2KuZ3dPoVuqg==~103~

nick密文：~nID/f9qCBqgm7MXZSXBpfA==~103~ ->明文：taobaoTEST2

nick密文：~kgRCprD8gH2KuZ3dPoVuqg==~103~ ->明文：taobaoTEST1

4)普通加密场景:

场景1:在SQL语句中不出现在where从句中。直接取数据解密展示或打印：

String cipher = ReadFromDataBase(); // SELECT cipher FROM table...

String phone = securityClient.decrypt(cipher, “phone”, sessionKey);

场景2:需要把加密字段作为SQL的搜索条件放入where 从句(key = “value”)中：

String cipher = securityClient.encrypt(p, “phone”, sessionKey);

SELECT * FROM table WHERE phone = #cipher#

在明文切换到密文的过程中，可能会出现明文和密文混合存在的短暂状态。这是需要做好兼容准备:

SELECT * FROM table WHERE phone in ( #cipher#, #p#)

5)支持模糊查询的加密场景(非手机号码字段)：

场景1：非手机号码字段模糊查询示例代码：

//需要模糊查询的片段

String partial = "cdefg";

//得到模糊查询密文
String search = securityClient.search(partial);

// 去数据库做模糊查询
List objects = SELECT * FROM table WHERE nick LIKE “%”+ #search# + “%”

// 筛选
List result = new List();

for(DO object : objects) {
if (SecurityClient.decrypt(object.nick).contains(partial)){
result.add(object);
}
}

场景2：phone 模糊查询前3位示例代码：

(会用到前缀索引)

//需要模糊查询的片段

String partial = "138";

// 去数据库做模糊查询
List objects = SELECT * FROM table WHERE nick LIKE “$”+partial + “%”

场景3：phone 模糊查询后4位示例代码：

(会用到前缀索引)

//需要模糊查询的片段

String partial = "5383";
//得到模糊查询密文
String search = securityClient.search(partial);
// 去数据库做模糊查询
List objects = SELECT * FROM table WHERE nick LIKE partial+“%”

FAQ

• 关于此文档暂时还没有FAQ