通用规则

1. 说明

1.1 用词说明

报文：指HTTP请求或响应的数据内容
参数内容：指报文中，bizData属性值
MD5密钥：由平台给出的参与加签、验签的特殊字符串
AES秘钥：由平台提供的AES加密种子字符串

1.2 代码说明

JSON.serialize：JSON序列化
AES.encrypt：AES加密
URLEncoder.encode：URL（UTF-8）编码

2. 数据安全

2.1 基于 AES 对称加密

AES具有应用范围广、隐蔽性好、破解难度高、吞吐量大等优点，为了保证消息的安全性、一致性，本系统使用AES（AES-128-ECB，AES/ECB/PKCS5Padding）对报文进行加密传输，Java版工具类如下：

2.2 数据签名

在发送请求前为避免数据被恶意篡改，渠道方需要使用MD5对参数内容生成数据签名，签名的参数内容字符串必须与报文内容字符串保持一致，否则会导致验签失败。

签名步骤如下：

将bizData参数内容序列化为JSON字符串
将序列化后的bizData参数内容字符串结尾追加MD5密钥字符串
使用MD5对追加后的字符串内容生成数据签名
将生成的数据签名设置为报文中sign属性值

2.3 数据验签

当接收到报文后，为保证报文的原始一致性，必须严格检验数据签名是否有效。

验签步骤如下：

将接收到的密文报文使用AES解密
在明文报文中取得bizData参数内容
将bizData参数内容结尾追加MD5密钥字符串
使用MD5对追加后的字符串内容生成数据签名
对比明文报文中sign属性内容，如果一致表示验签成功，否则失败
如果验签失败，请拒绝本次请求或响应数据，并及时通知平台

2.4 数据加密

为保证数据安全、隐蔽，需要将签名后的报文进行AES加密处理，并以密文形式进行传输。

加密步骤如下：

先按照签名步骤，进行数据签名
将报文序列化为JSON字符串
使用AES加密序列化后的报文

2.5 数据解密

在接到密文报文后，需要先对密文进行解密，解密后获得明文报文，再进行验签，待验签成功后，执行业务处理。

解密步骤如下：

使用AES解密接收到的密文报文，并获得明文报文
在明文报文中取得bizData参数内容

import sun.misc.BASE64Decoder;

import javax.crypto.Cipher;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

/**
 * AES编码器工具
 * 使用AES加密解密 AES-128-ECB加密
 */
public class AesUtil {

    private static final String KEY_ALGORITHM = "AES";
    public static final String CIPHER_ALGORITHM = "AES/ECB/PKCS5Padding";
    private static final int KEY_SIZE = 128;
    private static final String CHARSET = "UTF-8";

    /**
     * 数据加密
     */
    public static String encryptAndBase64Encode(String data, String key) {
        try {
            return encryptAndBase64Encode(data.getBytes(CHARSET), key);
        } catch (Exception e) {
            throw new RuntimeException("AES加密报错，error=" + e.getMessage(), e);
        }
    }

    public static String encryptAndBase64Encode(String data, String key, String algorithm, AESKeyType aesKeyType) {
        try {
            return encryptAndBase64Encode(data.getBytes(CHARSET), key, algorithm, aesKeyType);
        } catch (Exception e) {
            throw new IllegalArgumentException("AES加密报错，error=" + e.getMessage(), e);
        }
    }

    public static String encryptAndBase64Encode(byte[] data, String key) {
        try {
            if (isBlank(key)) {
                throw new RuntimeException("AES Key为空");
            }
            return doEncryptAndBase64Encode(data, key, CIPHER_ALGORITHM, AESKeyType.plain);
        } catch (Exception ex) {
            throw new RuntimeException("AES加密报错，error=" + ex.getMessage(), ex);
        }
    }

    public static String encryptAndBase64Encode(byte[] data, String key, String algorithm, AESKeyType aesKeyType) {
        try {
            if (isBlank(key)) {
                throw new RuntimeException("AES Key为空");
            }
            if (isBlank(algorithm)) {
                throw new RuntimeException("AES 算法为空");
            }
            return doEncryptAndBase64Encode(data, key, algorithm, aesKeyType);
        } catch (Exception ex) {
            throw new RuntimeException("AES加密报错，error=" + ex.getMessage(), ex);
        }
    }

    private static String doEncryptAndBase64Encode(byte[] data, String key, String algorithm, AESKeyType aesKeyType) throws Exception {
        algorithm = isBlank(algorithm) ? CIPHER_ALGORITHM : algorithm;
        byte[] raw = toKey(key, aesKeyType);
        SecretKeySpec skeySpec = new SecretKeySpec(raw, KEY_ALGORITHM);
        Cipher cipher = Cipher.getInstance(algorithm);
        cipher.init(Cipher.ENCRYPT_MODE, skeySpec);
        byte[] encrypted = cipher.doFinal(data);
        return Base64.getEncoder().encodeToString(encrypted);
    }

    /**
     * 数据解密，返回字符串
     */
    public static String decryptAfterBase64Decode(String data, String key) {
        try {
            byte[] bytes = decryptAfterBase64DecodeToByte(data, key);
            if (bytes != null && bytes.length > 0) {
                return new String(bytes, CHARSET);
            }
        } catch (Exception e) {
            throw new RuntimeException("AES解密报错:" + e.getMessage(), e);
        }
        return null;
    }

    public static String decryptAfterBase64Decode(String data, String key, String algorithm, AESKeyType aesKeyType) {
        try {
            byte[] bytes = decryptAfterBase64DecodeToByte(data, key, algorithm, aesKeyType);
            if (bytes != null && bytes.length > 0) {
                return new String(bytes, CHARSET);
            }
        } catch (Exception e) {
            throw new RuntimeException("AES解密报错:" + e.getMessage(), e);
        }
        return null;
    }

    public static byte[] decryptAfterBase64DecodeToByte(String data, String key) {
        try {
            if (isBlank(key)) {
                throw new RuntimeException("AES Key为空");
            }
            return doDecryptAfterBase64DecodeToBtype(data, key, CIPHER_ALGORITHM, AESKeyType.plain);
        } catch (Exception ex) {
            throw new RuntimeException("AES解密报错:" + ex.getMessage(), ex);
        }
    }

    public static byte[] decryptAfterBase64DecodeToByte(String data, String key, String algorithm, AESKeyType aesKeyType) {
        try {
            if (isBlank(key)) {
                throw new RuntimeException("AES Key为空");
            }
            if (isBlank(algorithm)) {
                throw new RuntimeException("AES 算法为空");
            }
            return doDecryptAfterBase64DecodeToBtype(data, key, algorithm, aesKeyType);
        } catch (Exception ex) {
            throw new RuntimeException("AES解密报错:" + ex.getMessage(), ex);
        }
    }

    private static byte[] doDecryptAfterBase64DecodeToBtype(String data, String key, String algorithm, AESKeyType aesKeyType) throws Exception {
        algorithm = isBlank(algorithm) ? CIPHER_ALGORITHM : algorithm;
        byte[] raw = toKey(key, aesKeyType);
        SecretKeySpec skeySpec = new SecretKeySpec(raw, KEY_ALGORITHM);
        Cipher cipher = Cipher.getInstance(algorithm);
        cipher.init(Cipher.DECRYPT_MODE, skeySpec);
        byte[] encrypted1 = Base64.getDecoder().decode(data);
        byte[] original = cipher.doFinal(encrypted1);
        return original;
    }

    private static byte[] toKey(String key, AESKeyType aesKeyType) throws Exception {
        if (aesKeyType == AESKeyType.plain) {
            return key.getBytes(CHARSET);
        } else if (aesKeyType == AESKeyType.base64) {
            return new BASE64Decoder().decodeBuffer(key);
        }
        return null;
    }

    public enum AESKeyType {
        plain("普通字符串"),
        base64("base64编码字符串");

        public String text;

        AESKeyType(String text) {
            this.text = text;
        }
    }

    private static boolean isBlank(String str) {
        return str == null || str.trim().isEmpty();
    }
}

3. 接口规范

3.1 请求和响应报文规范

基础请求参数，是所有请求中都需要传递的参数，主要提供本系统处理请求数据使用，为保证数据的有效性，请严格按照下表说明使用。

本系统只提供了POST支持，为了更好的保证请求有效性，请严格按照如下要求发送请求：

Post请求，请将参数设置于RequestBody中，如果请求头为Content-Type=application/x-www-form-urlencoded时，请求内容需要使用"K-V格式"并以"&"连接（例如：name=ZhangSan&age=20），对于Post请求的服务接口，不接收UrlPath中的数据

3.2 请求和响应报文格式

3.2.1 POST + Form 规范

字段	说明
请求URL	平台提供的API服务地址
请求方法	POST
请求方式	同步请求
请求头	`Content-Type: application/x-www-form-urlencoded`
请求参数格式	`content=AesUtil.encryptAndBase64Encode（JSON.serialize（请求参数）, aesKey）`
请求参数位置	URLPath 待确认：3.1 要求参数位于 RequestBody，并说明不接收 UrlPath 数据；本表格标注为 URLPath。

请求参数：

同步结果格式： AesUtil.encryptAndBase64Encode（JSON.serialize（同步结果）, aesKey），返回值是加密后的字符串。

3.3 异步推送接口规范

推送请求和响应报文均采用JSON数据格式，渠道方在处理异步推送数据时，为避免触发本系统重试机制，重复请求渠道方服务，请确保返回给本系统正确的状态，具体接口规范如下：

字段	说明
请求URL	渠道方提供
请求方法	POST
请求方式	异步请求
请求头	`Content-Type: application/x-www-form-urlencoded`
请求参数格式	`content=AesUtil.encryptAndBase64Encode（JSON.serialize（请求参数）, aesKey）`
请求参数位置	Body
请求参数	Object（根据具体业务定）

同步结果（返回为明文）：

注：大多数回调接口返回明文，6.6 签章结果查询除外（返回密文，见下）。

同步结果（返回为密文，仅 6.6 签章结果查询）：

涉及协议信息的回调需对返回内容进行加密，加密规则与接口同步响应相同：先对明文 JSON 进行数据签名，再整体 AES 加密后返回。

其中 bizData 解密后的明文结构为：

3.4 异步推送重试机制

异步推送重试，是为保证异步结果最大努力推送至渠道方系统的一种机制，由于现实环境中各种复杂原因，都可能导致回调请求失败，所以本系统提供了5次重试，重试间隔如下（单位ms）：

1000, 120000, 600000, 3600000, 10800000, 21600000

当5次重试均为失败时，将终止重试，需要线下人工处理。

{
  "sign": "[String]",   // 数字签名
  "bizData": "[String]" // 请求内容
}

{
  "sign": "[String]",       // 数字签名
  "bizData": {
    "code": "[Integer]",         // 响应码: 0成功，-1失败
    "businessCode": "[String]",  // 业务状态码
    "msg": "[String]",           // 响应状态码描述信息
    "data": "[Object]"           // 业务数据
  }
}

4. 状态码

4.1 BusinessCode 通用状态码

通用状态码适用于全部接口，如果接口没有单独列出businessCode状态码列表的，请以通用代码为参考。

状态码	状态码描述
0000	success
0001	未知错误
0002	验签失败
0003	参数错误
0004	重复提交
0005	获取Token失败
0100	未查到符合条件的数据
3002	订单状态不合法
3005	用户不存在
9001	订单不存在