注意：以下文档只适用于TOP接口，请谨慎使用！
注意：以下文档只适用于TOP接口，请谨慎使用！
ISV大致确认自己的接入方案和加密方案后，进入开发阶段。需要首先下载最新的TOP SDK。以下是代码开发介绍，分成3个部分：首先介绍SDK中的api, 第二部分是代码开发的规范，最后列举了再各个场景下的一些代码Demo（JAVA）。
下面的代码示例是JAVA版本，PHP版本的请直接查看一下 SDK包中的 PHPsdk/top/security/SecurityTest.php .
C#版本与JAVA类似，可以模仿JAVA的代码进行测试。
请注意，为了性能和稳定性，代码规范请务必要注意遵守！
|
|
作用 |
参数 |
| SecurityClient (constructor) |
初始化 |
|
| securityClient.encrypt |
自动用最新版本密钥将数据加密 |
可批量传入数据，批量返回 |
| securityClient.encryptPrevious |
自动用上一版本密钥将数据加密(在密钥变更迁移中可能用到) |
可批量传入数据，批量返回 |
| securityClient.decrypt |
自动判断密文版本，用对应版本密钥解密数据 |
可批量传入数据，批量返回 |
| securityClient.isPartEncryptData |
判断list元素是否存在密文数据。只要有一个是密文，则返回true
|
可批量传入数据，返回true or false。建议使用这个方法判断批量数据。 |
| securityClient.isEncryptData |
判断字符串是否是密文方法,支持批量判断。如果list中有明文返回false。 |
可批量传入数据，返回true or false |
| securityClient.search |
生成给定字符串的模糊查询 |
|
| SecurityClient.generateCustomerSession |
自建账号生成sessionkey方法 |
使用前需要调用taobao.top.secret.register API接口注册用户，在使用方法获取自建账号的sessionkey |
初始化：
SecurityClient SecurityClient = new SecurityClient(new DefaultTaobaoClient(serverUrl, appkey, appSecret), randomNumber)
注:
1）randomNumber 为安全码，不是随机数，需要在数据加密菜单，店铺加密模块中 点击生成。
已经生成的应用可以在流量证书上方查看到。
2）defaultTaobaoClient 使用的serverUrl必须是https协议
正式环境 https://eco.taobao.com/router/rest
沙箱环境 https://gw.api.tbsandbox.com/router/rest
加密：
securityClient.encrypt(“13888883333”, type, sessionKey)
密文判断:
SecurityClient.isEncryptData(“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#%
(此例为手机号码，其余例子见下面分场景详述)
1）全部用主账号的sessionkey，子账号可能没有权限
2）调用之前前置判断sessionkey
3）授权返回sessionkey带了过期时间
4）判断sessionkey的过期时间+90天是否已经超过，如果过期超过90天，不需要调用加、解密（在重新授权之前永远不可能成功，浪费资源），假设客户端存在误判，实际调用加、解密可能抛异常。可以采用以下方案：
try {
// 加、解密操作
} catch (SecretException e) {
if(ErrorUtil.isInvalidSession(e)) {
// 标记该sessionkey无效，重新授权之前不要再调用
}
}
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(“3333”, type, sessionKey);
// 去数据库做模糊查询
List<DO> objects = SELECT * FROM table WHERE nick LIKE “%”+ #search# + “%”
// 筛选
List<DO> result = new List<DO>();
for(DO object : objects) {
if (SecurityClient.decrypt(object.nick).contains(partial)){
result.add(object);
}
}
场景2：phone 模糊查询前3位示例代码：
(会用到前缀索引)
//需要模糊查询的片段
String partial = "138";
// 去数据库做模糊查询
List<DO> objects = SELECT * FROM table WHERE nick LIKE “$”+partial + “%”
场景3：phone 模糊查询后4位示例代码：
(会用到前缀索引)
//需要模糊查询的片段
String partial = "5383";
//得到模糊查询密文
String search = securityClient. search(“3333”, type, sessionKey);
// 去数据库做模糊查询
List<DO> objects = SELECT * FROM table WHERE nick LIKE partial+“%”
