# 底层协议介绍

Futu API 是富途为主流的编程语言（Python、Java、C#、C++、JavaScript）封装的 API SDK，以方便您调用，降低策略开发难度。
这部分主要介绍策略脚本与 OpenD 服务之间通信的底层协议，适用于非上述 5 种编程语言用户，自行对接实现底层裸协议。

提示

如果您使用的编程语言在上述的 5 种主流编程语言之内，可以直接跳过这部分内容。

# 协议请求流程

建立连接
初始化连接
请求数据或接收推送数据
定时发送 KeepAlive 保持连接

proto-process

# 协议设计

协议数据包括协议头以及协议体，协议头固定字段，协议体根据具体协议决定。

# 协议头

struct APIProtoHeader
{
    u8_t szHeaderFlag[2];
    u32_t nProtoID;
    u8_t nProtoFmtType;
    u8_t nProtoVer;
    u32_t nSerialNo;
    u32_t nBodyLen;
    u8_t arrBodySHA1[20];
    u8_t arrReserved[8];
};

1
2
3
4
5
6
7
8
9
10
11

字段	说明
szHeaderFlag	包头起始标志，固定为“FT”
nProtoID	协议 ID
nProtoFmtType	协议格式类型，0 为 Protobuf 格式，1 为 Json 格式
nProtoVer	协议版本，用于迭代兼容，目前填 0
nSerialNo	包序列号，用于对应请求包和回包，要求递增
nBodyLen	包体长度
arrBodySHA1	包体原始数据(解密后)的 SHA1 哈希值
arrReserved	保留 8 字节扩展

提示

u8_t 表示 8 位无符号整数，u32_t 表示 32 位无符号整数
OpenD 内部处理使用 Protobuf，因此协议格式建议使用 Protobuf，减少 Json 转换开销
nProtoFmtType 字段指定了包体的数据类型，回包会回对应类型的数据；推送协议数据类型由 OpenD 配置文件指定
arrBodySHA1 用于校验请求数据在网络传输前后的一致性，必须正确填入
协议头的二进制流使用的是小端字节序，即一般不需要使用 ntohl 等相关函数转换数据

# 协议体

# Protobuf 协议请求包体结构

message C2S
{
    required int64 req = 1;
}

message Request
{
    required C2S c2s = 1;
}

1
2
3
4
5
6
7
8
9

# Protobuf 协议回应包体结构

message S2C
{
    required int64 data = 1;
}

message Response
{
    required int32 retType = 1 [default = -400]; //RetType，返回结果
    optional string retMsg = 2;
    optional int32 errCode = 3;
    optional S2C s2c = 4;
}

1
2
3
4
5
6
7
8
9
10
11
12

字段	说明
c2s	请求参数结构
req	请求参数，实际根据协议定义
retType	请求结果
retMsg	若请求失败，说明失败原因
errCode	若请求失败对应错误码
s2c	回应数据结构，部分协议不返回数据则无该字段
data	回应数据，实际根据协议定义

提示

包体格式类型请求包由协议头 nProtoFmtType 指定，OpenD 主动推送格式在 InitConnect 设置。
原始协议文件格式是以 Protobuf 格式定义，若需要 json 格式传输，建议使用 protobuf3 的接口直接转换成 json。
枚举值字段定义使用有符号整形，注释指明对应枚举，枚举一般定义于 Common.proto，Qot_Common.proto，Trd_Common.proto 文件中。
协议中价格、百分比等数据用浮点类型来传输，直接使用会有精度问题，需要根据精度（如协议中未指明，默认小数点后三位）做四舍五入之后再使用。

# 心跳保活

syntax = "proto2";
package KeepAlive;
option java_package = "com.futu.openapi.pb";
option go_package = "github.com/futuopen/ftapi4go/pb/keepalive";

import "Common.proto";

message C2S
{
	required int64 time = 1; //客户端发包时的格林威治时间戳，单位秒
}

message S2C
{
	required int64 time = 1; //服务器回包时的格林威治时间戳，单位秒
}

message Request
{
	required C2S c2s = 1;
}

message Response
{
	required int32 retType = 1 [default = -400]; //RetType,返回结果
	optional string retMsg = 2;
	optional int32 errCode = 3;
	
	optional S2C s2c = 4;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

介绍

心跳保活
协议 ID

1004
使用

根据初始化链接返回的心跳保活间隔时间，向 OpenD 发送保活协议

# 加密通信流程

若 OpenD 配置了加密，InitConnect 初始化连接协议必须使用 RSA 公钥加密，后续其他协议使用 InitConnect 返回的随机密钥进行 AES 加密通信。
OpenD 的加密流程借鉴了 SSL 协议，但考虑到一般是本地部署服务和应用，简化了相关流程，OpenD 与接入 Client 共用了同一个 RSA 私钥文件，请妥善保存和分发私钥文件。
可到这个网址在线生成随机 RSA 密钥对，密钥格式必须为 PCKS#1，密钥长度 512，1024 都可以，不要设置密码，将生成的私钥复制保存到文件中，然后将私钥文件路径配置到 OpenD 配置约定的 rsa_private_key 配置项中。
建议有实盘交易的用户配置加密，避免账户和交易信息泄露。

encrypt

# RSA 加解密

OpenD 配置约定 rsa_private_key 为私钥文件路径
OpenD 与接入客户端共用相同的私钥文件
RSA 加解密仅用于 InitConnect 请求，用于安全获取其它请求协议的对称加密 Key
OpenD 的 RSA 密钥为 1024 位，填充方式 PKCS1，公钥加密，私钥解密，公钥可通过私钥生成
Python API 参考实现：RsaCrypt 类的 encrypt / decrypt 接口

# 发送数据加密

RSA 加密规则:若密钥位数是 key_size，单次加密串的最大长度为 (key_size)/8 - 11，目前位数 1024，一次加密长度可定为 100。
将明文数据分成一个或数个最长 100 字节的小段进行加密，拼接分段加密数据即为最终的 Body 加密数据。

# 接收数据解密

RSA 解密同样遵循分段规则，对于 1024 位密钥，每小段待解密数据长度为 128 字节。
将密文数据分成一个或数个 128 字节长的小段进行解密，拼接分段解密数据即为最终的 Body 解密数据。

# AES 加解密

加密 key 由 InitConnect 协议返回
默认使用的是 AES 的 ecb 加密模式。
Python API 参考实现: ConnMng 类的 encrypt_conn_data / decrypt_conn_data 接口

# 发送数据加密

AES 加密要求源数据长度必须是 16 的整数倍，故需补‘0’对齐后再加密，记录 mod_len 为源数据长度与 16 取模值。
因加密前有可能对源数据作修改，故需在加密后的数据尾再增加一个 16 字节的填充数据块，其最后一个字节赋值 mod_len，其余字节赋值‘0’，将加密数据和额外的填充数据块拼接作为最终要发送协议的 body 数据。

# 接收数据解密

协议 body 数据，先将最后一个字节取出，记为 mod_len，然后将 body 截掉尾部 16 字节填充数据块后再解密（与加密填充额外数据块逻辑对应）。
mod_len 为 0 时，上述解密后的数据即为协议返回的 body 数据，否则需截掉尾部(16 - mod_len)长度的用于填充对齐的数据。

aes

← 通用定义 OpenD 相关 →