淘宝开放平台开发文档 / 应用代码开发方案

应用代码开发方案

 1 场景需求

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

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

 

方案介绍

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

LB1OXJaPXXXXXbvXFXXXXXXXXXX.png

输出结果:

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

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

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

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

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

 

3) 批量加、解密

LB1o4ALOVXXXXbKaFXXXXXXXXXX.png

 

LB1NX8hPXXXXXcjXpXXXXXXXXXX.png

输出结果

手机号码明文: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);
  }
}

 

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

(会用到前缀索引)

 //需要模糊查询的片段

String partial = "138";

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

 

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

(会用到前缀索引) 

//需要模糊查询的片段

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

 

 

FAQ

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