概述
接口适用范围
此文档定义了LinkDaDa开放平台(以下简称LinkDaDa)和交易所的接口交互规范,包括LinkDaDa发起的请求接口和交易所发起的通知接口。
接口对接流程
注册/认证/提币.jpeg
币币/法币交易.jpeg
接口规范
接口为RESTful风格,除文件上传下载等特殊情况外,请求(POST时)和响应内容均为json格式。为避免交易所侧可能的改造成本,本规范避免使用http status code、path参数和GET/POST外的其他方法。
接口字段无特殊说明的, 默认为UTF-8编码。为增加接口兼容性,接口请求及响应字段均采用小写驼峰形式,如"signUrl", "createAt"。
GET 请求的 query 参数, 如果是数组(类型后面加[]表示数组)或者对象类型, 则实际传输的参数是经过 json 编码的字符串
接口响应规范:
{
"status":200, //状态码,表示成功或者失败。其中2xx表示成功,4xx为请求异常,5xx为服务器内部异常
"error": "", //错误类型
"message":"OK", //状态码描述
"maxPageSize":100, //允许每页最大的条数, 该字段只在有分页功能的接口响应中存在
"total": 1, //查询结果总条数,该字段只在有分页功能的接口响应中存在
"data":"{\"id\":1}", //具体业务数据, json形式的字符串
"signUrl":"GET /trades-for-his/orders/123", //本次请对应的url, **不含QueryString**
"signTime": 1490529625, //签名时刻的时间戳(Unix timestamp)
"sign":"xxxxxxxxxx" //签名
}
signUrl,signTime,sign为每个接口响应必须带的参数,后续接口响应示例省略不再重复说明
接口地址规范:
接口地址
LinkDaDa侧提供的接口地址, 用于交易订单创建、充提币通知等。
接口签名
双方接口都应使用签名作为安全通信机制。相关接口, 双方应使用RSA签名。
注意: 发起请求时, 应对QueryString和Content的所有内容进行签名; 接收响应时, 应对Content的所有内容进行签名。而不是仅对接口中定义的内容签名。
签名前, 先将待签名数据(请求或者响应的参数列表)进行预处理:
参数列表中加入signUrl和signTime参数, 如
{
"signTime":1490529625,//签名时刻的时间戳(Unix timestamp)
"signUrl":"GET /trades-for-his/orders/123", //本次请对应的方法和url, 不含QueryString
}
将请求参数以参数名按字典序升序排列,并拼接在一起,如“k1=v1&k2=v2&k3=v3”
以上处理输出"待签名文本", 以下为php代码片段:
/**
* 生成待签名文本
* @param array $data
*/
function genSignReq(array $data)
{
//1. 先将参数按参数名的字典序升序进行排序
$signReq = []; //待签名字符串
ksort($data);
//2. 将数组拼成字符串。注意, 对于json中的null、bool类型, 需要转换成约定好的文本
foreach ($data as $k => $v) {
if($v === null) { // null 转换成空字符串
$v = '';
}elseif ($v === true) { // true 转换文本'1'
$v = '1';
}elseif ($v === false) { // true 转换成文本'0'
$v = '0';
}
//为key/value对生成一个key=value格式的字符串,并拼接到待签名字符串后面
$signReq[] = "$k=$v";
}
return implode('&', $signReq);
}
注意:计算签名时,应将sign(签名)参数排除。
注意:计算签名的时候不需要对参数进行URLencode处理(“application/x-www-form-URLencoded”编码)。
RSA签名
OpenSSL工具安装
Linux用户(以Ubuntu为例)
sudo apt-get install openssl
Windows用户开发者可以在OpenSSL官方网站(https://www.openssl.org/related/binaries.html)下载Windows的OpenSSL安装包进行安装
RSA私钥及公钥生成
openssl #执行openssl, 进入openssl控制台
OpenSSL> genrsa -out rsa_private_key.pem 1024 #生成私钥
OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem -outform PEM -nocrypt #Java开发者需要将私钥转换成PKCS8格式
OpenSSL> rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem #生成公钥
注意:对于使用Java的开发者,将pkcs8在console中输出的私钥去除头尾、换行和空格,作为开发者私钥,对于.NET和PHP的开发者来说,无需进行pkcs8命令行操作。
私钥及公钥文件示例
经过以上步骤,开发者可以在当前目录下看到rsa_private_key.pem和rsa_public_key.pem两个文件,前者为私钥,后者为公钥。交易所侧保留私钥,将公钥提交给LinkDaDa,用于信息加密及解密。以下为使用OpenSSL生成的私钥文件和公钥文件示例。
标准的私钥文件示例(PHP、.NET使用)
-----BEGIN RSA PRIVATE KEY-----
MIICXAIBAAKBgQChKpLOsRHQ5L046EEseZn+lTbgD5H9N9Z/SsxrJMkQv5GL/NWl
jgPlaGSY4Eawi6k3b26RQUGHA9QZ7lSlNXPJByTjpghBti1wccv8xYQgbmVlKj5g
/bfqjVIDPDCj8oNa4dGCnfyJ6oW0bfZXfbtK6xeFFvJTRNNn+8Sz0IK4cQIDAQAB
AoGAasJ972dCawMrCYhoq+J9jTQg3rnRtlCHyViuIweCHZMZAgdhK0Lw98V4ZgCj
Mw3A8VTihFwa4So7FVZYQfwvjtz3SfpYvB6YSB9gnFNB3RvOUwFLqbnCtEw7tWyP
7vhE1HfyTzmngFpbjFTaGjioXvQA6zN7wj3ptycbwfZxWLECQQDQZflrgkdi7y59
Ab0fd2LQmgBawQjwUeqLMTrqVi6dy7q+r4PVK86t0AYruCXTK8Tl7kxE/ez5W88k
mw9fevx9AkEAxfq4nVmyFLXrD+3NcG86TSWIv4df1u695KfSiZISQzv7XmW/wlSX
QWFtpocz1nQL5mpkivx/YcZ0il5WELcSBQJBAJoymfb+kquVpqRAYRujTq5jBNgh
9Oc89XrAloNF+YAweqEVZUqZ+3eIcMhwnSw/OpWXWT/DU1C+qerAAQP5EFECQF8H
5EoTXfm3AOgae7x2h4O0epmE/6oJ2zjAnbzPUtjXF+fN62f6dsg5XgrLZ0SPW470
juJwJSznt9UbRzCqz4kCQG+nbP/ZmrJXocC9yWupDQysFBE+p3+Fpstb2pNymGyR
SblvImtWhRq+kPY48Uxbpy5u7G2KxwqGoxwkmXbmb6U=
-----END RSA PRIVATE KEY-----
PKCS8处理后的私钥文件示例(Java使用)
```
-----BEGIN PRIVATE KEY-----
MIICdgIBADANBgkqhkiG9w0BAQEFAASCAmAwggJcAgEAAoGBAKEqks6xEdDkvTjo
QSx5mf6VNuAPkf031n9KzGskyRC/kYv81aWOA+VoZJjgRrCLqTdvbpFBQYcD1Bnu
VKU1c8kHJOOmCEG2LXBxy/zFhCBuZWUqPmD9t+qNUgM8MKPyg1rh0YKd/InqhbRt
9ld9u0rrF4UW8lNE02f7xLPQgrhxAgMBAAECgYBqwn3vZ0JrAysJiGir4n2NNCDe
udG2UIfJWK4jB4IdkxkCB2ErQvD3xXhmAKMzDcDxVOKEXBrhKjsVVlhB/C+O3PdJ
+li8HphIH2CcU0HdG85TAUupucK0TDu1bI/u+ETUd/JPOaeAWluMVNoaOKhe9ADr
M3vCPem3JxvB9nFYsQJBANBl+WuCR2LvLn0BvR93YtCaAFrBCPBR6osxOupWLp3L
ur6vg9Urzq3QBiu4JdMrxOXuTET97PlbzySbD196/H0CQQDF+ridWbIUtesP7c1w
bzpNJYi/h1/W7r3kp9KJkhJDO/teZb/CVJdBYW2mhzPWdAvmamSK/H9hxnSKXlYQ
txIFAkEAmjKZ9v6Sq5WmpEBhG6NOrmME2CH05zz1esCWg0X5gDB6oRVlSpn7d4hw
yHCdLD86lZdZP8NTUL6p6sABA/kQUQJAXwfkShNd+bcA6Bp7vHaHg7R6mYT/qgnb
OMCdvM9S2NcX583rZ/p2yDleCstnRI9bjvSO4nAlLOe31RtHMKrPiQJAb6ds/9ma
slehwL3Ja6kNDKwUET6nf4Wmy1vak3KYbJFJuW8ia1aFGr6Q9jjxTFunLm7sbYrH
CoajHCSZduZvpQ==
-----END PRIVATE KEY-----
```
* 公钥文件示例
```
-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQChKpLOsRHQ5L046EEseZn+lTbg
D5H9N9Z/SsxrJMkQv5GL/NWljgPlaGSY4Eawi6k3b26RQUGHA9QZ7lSlNXPJByTj
pghBti1wccv8xYQgbmVlKj5g/bfqjVIDPDCj8oNa4dGCnfyJ6oW0bfZXfbtK6xeF
FvJTRNNn+8Sz0IK4cQIDAQAB
-----END PUBLIC KEY-----
```
签名和校验
LinkDaDa和交易所发起的请求、返回的响应均需要签名,签名方式为:
计算待签名文本的RSA签名。
将签名 base64编码,即为 sign的值(请求和响应中sign对应的值) 以下为php代码片段:
/**
* 签名
*
* @param array $data 需要签名的内容
* @param string $rsaPrivateKey rsa私钥
* @return string 生成的签名
*/
function genSign(array $data, $rsaPrivateKey)
{
//1. 生成待签名文本
$signReq = genSignReq($data);
//2. 对摘要进行签名
$signRes = null;
$key = openssl_get_privatekey($rsaPrivateKey) or Verify::fail('openssl_get_privatekey failed', [openssl_error_string()]);
openssl_sign($signReq, $signRes, $key) or Verify::fail('openssl_sign failed', [openssl_error_string()]);
openssl_free_key($key);
//3. base64编码
$sign = base64_encode($signRes);
return $sign;
}
/**
* @param array $data 待验签的文本
* @param $rsaPublicKey 公钥
* @return bool
*/
function verifySign(array $data, $rsaPublicKey)
{
if(!isset($data['sign'])){
return false;
}
$sign = base64_decode($data['sign']);
unset($data['sign']); // 验签前需要把sign排除
//1. 生成待签名文本
$signReq = genSignReq($data);
//2. 验签
$key = openssl_get_publickey($rsaPublicKey);
$result = openssl_verify($signReq, $sign, $key);
openssl_free_key($key);
if($result == -1){
Verify::fail('openssl_verify failed', [openssl_error_string()]);
}
return $result==1;
}
注意:LinkDaDa请求交易所的接口,如首次注册用户,LinkDaDa使用自己的私钥进行签名,交易所使用LinkDaDa的公钥进行验签,并将响应结果使用交易所私钥进行加签,LinkDaDa使用交易所公钥进行验签。同理,交易所通知LinkDaDa的接口,如订单成功接口,交易所使用自己的私钥进行加签,LinkDaDa收到通知后,使用交易所的公钥进行验签。