注意:以下文档只适用于TOP接口,请谨慎使用!

文档中心 > 基础技术

应用代码开发方案

更新时间:2017/08/16 访问次数:21934

 1 场景需求

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

下面的代码示例是JAVA版本,PHP版本的请直接查看一下 SDK包中的 PHPsdk/top/security/SecurityTest.php .

C#版本与JAVA类似,可以模仿JAVA的代码进行测试。

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

 

方案介绍

2.1  API介绍

 

作用

参数

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#%

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

 

 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(“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);
  }
}

 

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

(会用到前缀索引)

 //需要模糊查询的片段

String partial = "138";

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

 

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

(会用到前缀索引) 

//需要模糊查询的片段

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

 

 

FAQ

关于此文档暂时还没有FAQ
返回
顶部