1 场景需求

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

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

2  方案介绍

2.1  API介绍

初始化：

 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<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(partial);
// 去数据库做模糊查询
List<DO> objects =  SELECT * FROM table WHERE nick LIKE partial+“%”

FAQ

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