穿透式监管CTPAPI使用说明

穿透式监管CTPAPI使用说明文档修订历史记录修改记录修改状态修改页码及条款修改人审核人批准人修改日期V0.1创建V1.1内容申明内部资料，注意保存。此文件属于上海期货交易所（以下简称交易所或者上期所）和上海期货信息技术有限公司（以下简称技术公司）内部文件，包含敏感内容，未经交易所和技术公司负责人允许，不得对外展示本文件内容。 目录第1章 引言21.1 实现目的21.2 背景21.3 定义2第2章 流程设计32.1 终端认证方案32.1.1 背景条件32.1.2 appid对应的授权码分发流程32.1.3 登录前认证42.2 使用CTP交易API进行终端信息采集62.2.1 直接使用CTP交易API直连模式72.2.2 使用中继服务器操作员登录模式92.2.3 使用中继服务器多对多登录模式12第3章 CTP API使用说明133.1 采集API使用说明133.1.1 采集API说明133.2 TraderAPI133.2.1 穿透式监管涉及到的API133.2.2 客户使用流程15第1章 引言1.1 实现目的 简要描述CTP对于终端数据采集和终端认证的实现方案。用于指导终端厂商正确使用CTP的交易API和采集API。1.2 背景证监会发布关于进一步加强期货经营机构客户交易终端信息采集有关事项的公告监控中心发布的期货公司客户交易终端信息采集及接入认证技术规范 1.3 定义术语术语说明TraderApi交易API，提供登录、交易、银期等等功能采集API链接库负责采集终端信息的动态链接库，只有连接中继服务器的终端需要调用直连类型终端直接连接到CTP交易系统的客户交易终端中继类型终端先连接到中继服务器,中继服务器再调用TraderAPI连接到CTP交易系统的客户交易终端多对多类型中继服务器为每个客户终端，建立CTP API实例，每个用户独占一个交易API实例的中继服务器多对一类型中继服务器为多个客户终端，建立一个CTP API实例，使用操作员为多个客户进行交易的中继服务器第2章 穿透式监管方案设计2.1 终端认证方案2.1.1 背景条件每个期货终端软件需要向期货公司申请自己的appid。中继服务器软件需要向期货公司申请自己的relayappid。2.1.2 appid对应的授权码分发流程期货公司确认终端软件集成了正确的数据采集模块后，为该appid的终端软件分配授权码。终端软件需要保护好自己的appid和授权码，防止被其他软件盗用。2.1.2.1 直连终端认证流程对于直接连接期货公司交易柜台的终端，期货公司确认终端软件集成了正确的数据采集模块后。给该终端软件（根据appid）分配一个授权码。这个授权码和appid是绑定的，当终端试图登录期货公司交易软件的时候，交易后台会验证该终端是否持有合法的appid和授权码。2.1.2.2 中继和中继下属终端的认证流程对于使用中继服务器连接期货公司交易柜台的终端，期货公司确认终端软件集成了正确的数据采集模块和确认中继可以正常报送终端信息后。期货公司给该终端软件（根据appid）分配一个授权码，给中继服务器（根据semiapp） 分配一个授权码。当终端登录中继服务器时，中继服务器负责验证终端的合法性；当中继服务器登录期货公司交易软件的时候，交易后台会验证该中继服务器是否持有合法的relayappid和授权码。2.1.3 登录前认证当客户直接使用CTP交易API时，客户的终端软件（或者中继服务器）必须存有期货公司分配的授权码，在调用ReqAuthenticate()时填入appid和对应的授权码，交易API将该授权码（暂定16字节）缓存下来作为加密的AES_KEY，以对后续信息进行AES加密。接入认证的流程如下：图1.1处理流程：1. 在终端登录之前，用户通过交易API发起终端认证请求ReqAuthenticate。需要用户填写appid（relayappid）和授权码（authcode）, 该授权码只会缓存交易API中，不会在网络中直接传输授权码。2. 交易前置随机生成128字节的TimeStamp，将TimeStamp保存在session信息中，并将其通过RspAuthenticate回调信息返回给终端。3. 终端收到RspAuthenticate回调信息后，使用AES_KEY加密TimeStamp，并将其赋值到AuthInfo字段，再次发起ReqAuthenticate请求4. 交易前置收到第二次的FTD_TID_ReqAuthenticate之后，将之前session保存的TimeStamp 赋值到请求里面的TimeStamp字段中。将认证消息发送给交易核心5. 交易核心使用内存数据库中终端信息对应的授权码加密TimeStamp字段，并将加密结果与AuthInfo比较。如果相同设置当前终端为已经认证。并返回RspAuthenticate成功结果给交易前置。6. 交易前置通过API回调，将认证结果返回给用户对于认证失败的连接，不允许进行登录。2.2 使用CTP交易API进行终端信息采集用户可以直接使用CTP交易API进行交易，也可以通过中继服务器间接调用交易API进行交易。这就需要将信息采集动态库和CTP的交易API分离开来，因此信息的采集和上报有需要分为两步。 2.2.1 直接使用CTP交易API直连模式直接使用交易API进行交易时，API会直接调用GetSytemInfo()采集终端信息，并将信息填入LocalSystemInnerInfo字段，通过ReqUserLogin()将采集到的信息送给前置。前置收到交易API的ReqUserLogin请求后采集客户端的公网IP，并将该信息填写到登录请求的LocalSystemOuterInfo，然后将登录请求发送给交易核心。交易核心收到用户登录请求后，验证密码等信息。若通过验证则将请求中的客户端信息发送给TMDB(内存数据回写数据库组件)，TMDB(内存数据回写数据库组件)用监控中心发布的公钥对LocalSystemOuterInfo字段的信息进行加密，然后将该信息与其它信息一起回写数据库，结算系统读取数据库，将信息上报给监控中心。流程如下图:图1.2LocalSystemInnerInfo 里面存储的为公钥加密后的终端数据。LocalSystemOuterInfo里面存储的为明文的公网IP和登录时间，入库之前需要用公钥加密。带下划线的函数，为CTP交易系统内部函数。如_SubmitUserSystemInfo。步骤：1. 当终端软件通过交易API发起登录请求时，交易API调用GetSystemInfo()采集终端信息，将该信息填写到登录请求的LocalSystemInnerInfo字段中。上报用户系统信息给交易前置。2. 交易前置收到用户系统信息上报后，采集终端的公网IP填入LocalSystemOuterInfo字段，缓存该用户的系统信息，每个用户只缓存一条信息。3. 交易API发送登录请求给交易前置。交易前置转发给交易核心。4. 交易核心验证登录请求，并返回登录响应。5. 如果交易前置收到成功的登录响应，将响应中的登录时间与LocalSystemOuterInfo合并，通过tresult发送给TMDB。6. TMDB用监控中心的公钥加密LocalSystemOuterInfo信息，然后将所有的用户系统信息回写到物理数据库中。7. 结算系统读取物理数据库中的信息，每日汇总所有的采集信息，将信息报送给保证金监控中心2.2.2 使用中继服务器操作员登录模式采用中继服务器操作员模式时，信息采集的流程分为两个步骤：l 中继服务器以操作员的的身份调用TradeAPI登录CTP交易系统，这时交易后台对信息采集的处理方式与2.2.1中相同。l 中继服务器成功登录CTP交易系统后，须将投资者的终端信息报送上来。流程如下图所示：图1.3具体步骤：1. 中继服务器先以操作员的身份调用交易API登录CTP系统，登录时采集信息的方式与用户直接连接时相同。2. 中继服务器须采集客户端的信息，然后调用SubmitUserSystemInfo()上报终端信息（包含客户终端采集的信息、终端的appid、终端的登录时间和公网IP、中继服务器的relayappid等）。3. Front采集中继服务器的公网IP，并将信息填入LocalSystemOuterInfo字段中，然后将信息发送给tkernel。4. tkernel收到数据上报消息时，判断该登录账户是否有数据上报权限（只有操作员和超级用户有为其他用户上报信息的权限）。如果没有权限，直接丢弃消息。如果有权限则将信息发给TMDB。5. TMDB用监控中心的密钥加密LocalSystemOuterIno和RemoteSystemOuterInfo字段，然后将加密后的信息和采集的终端信息写入物理数据库，结算系统读取该数据库，将信息上报给监控中心。SubmitUserSystemInfo交易API接口只对操作员类型的中继服务器开放使用，其他类型的终端或者中继调用会直接返回失败。2.2.3 使用中继服务器多对多登录模式图1.4具体步骤：1. 中继服务器先为用户调用交易API的RegisterUserSystemInfo()接口（填写信息包含客户终端采集的信息、终端的appid、终端的登录时间和公网IP、中继服务器的relayappid等）。2. 其余过程与用户直接连接时相同。RegisterUserSystemInfo交易API接口只对多对多类型的中继服务器开放调用，其他类型的终端或者中继调用会直接返回失败。第3章 穿透式API使用说明为了实现穿透式监管方案， CTP会发布两个API，TraderAPI和信息采集API。下面新增或修改的API的说明。3.1 采集API使用说明3.1.1 采集API说明/获取AES加密和RSA加密的终端信息/ pSystemInfo的空间需要调用者自己分配 至少270个字节 / pSystemInfo 并不是一个字符串 而是数组 因为多次加密后可能断串 int CTP_GetSystemInfo(char* pSystemInfo, int& nLen);中继类型终端使用该函数获取终端信息数据（linux、windows ），安卓和ios的也会发布。3.2 TraderAPI3.2.1 穿透式监管涉及到的API1. /客户端认证请求virtual int ReqAuthenticate(CThostFtdcReqAuthenticateField *pReqAuthenticateField, int nRequestID) = 0;修改了结构体/客户端认证请求struct CThostFtdcReqAuthenticateField/经纪公司代码TThostFtdcBrokerIDTypeBrokerID;/用户代码TThostFtdcUserIDTypeUserID;/用户端产品信息TThostFtdcProductInfoTypeUserProductInfo;/认证码TThostFtdcAuthCodeTypeAuthCode;/App代码TThostFtdcAppIDTypeAppID; /需要按照规则定义;2. /客户端认证响应virtual void OnRspAuthenticate(CThostFtdcRspAuthenticateField *pRspAuthenticateField, CThostFtdcRspInfoField *pRspInfo, int nRequestID, bool bIsLast) ;/客户端认证响应struct CThostFtdcRspAuthenticateField/经纪公司代码TThostFtdcBrokerIDTypeBrokerID;/用户代码TThostFtdcUserIDTypeUserID;/用户端产品信息TThostFtdcProductInfoTypeUserProductInfo;/App代码TThostFtdcAppIDTypeAppID;/App类型TThostFtdcAppTypeTypeAppType;3. /上报用户终端信息，用于中继服务器操作员登录模式/操作员登录后，可以多次调用该接口上报客户信息virtual int SubmitUserSystemInfo(CThostFtdcUserSystemInfoField *pUserSystemInfo) = 0;/用户系统信息struct CThostFtdcUserSystemInfoField/经纪公司代码TThostFtdcBrokerIDTypeBrokerID;/用户代码TThostFtdcUserIDTypeUserID;/用户端系统内部信息长度TThostFtdcSystemInfoLenTypeClientSystemInfoLen;/用户端系统内部信息TThostFtdcClientSystemInfoTypeClientSystemInfo;/用户公网IPTThostFtdcIPAddressTypeClientPublicIP;/终端IP端口TThostFtdcIPPortTypeClientIPPort;/登录成功时间TThostFtdcTimeTypeClientLoginTime;/App代码TThostFtdcAppIDTypeClientAppID;ClientSystemInfoLen存储的为加密后的用户终端系统内部信息的长度ClientSystemInfo存储的为加密后的用户终端系统内部信息。ClientPublicIP存储的为用户终端IP，由中继服务器采集和填写ClientLoginTime 存储的为用户登录中继时间，由中继服务器采集和填写ClientAppid存储的为用户终端的appid，由中继服务器采集和填写4. /注册用户终端信息，用于中继服务器多连接模式/需要在终端认证成功后，用户登录前调用该接口virtual int RegisterUserSystemInfo(CThostFtdcUserSystemInfoField *pUserSystemInfo) = 0;3.2.2 客户使用流程每个类型的终端调用流程不同3.2.2.1 直连终端使用流程/在API连接后发起认证void CUser:OnFrontConnected()cout OnFrontConnected. GetApiVersion();cout -当前版本号 ： version - ReqAuthenticate(&field, 5);/认证成功后发起登录void CUser:OnRspAuthenticate(CThostFtdcRspAuthenticateField *pRspAuthenticateField, CThostFtdcRspInfoField *pRspInfo, int nRequestID, bool bIsLast)printf(OnRspAuthenticaten);if (pRspInfo != NULL & pRspInfo-ErrorID = 0):printf(认证成功,ErrorID=0x%04x, ErrMsg=%snn, pRspInfo-ErrorID, pRspInfo-ErrorMsg);ReqUserLogin();elsecout 认证失败， ErrorID= ErrorID ,ErrMsg= ErrorMsg ReqUserLogin(&reqUserLogin, +RequestID);3.2.2.2 多对多中继终端使用流程/终端侧采集信息 向中继发起登录 并将终端信息发送给中继char pSystemInfo344;int len;CTP_GetSystemInfo(pSystemInfo, len);cout CTP_GetSystemInfo once endl;/中继收到终端的登录请求，发起终端认证void CUser:OnFrontConnected()cout OnFrontConnected. GetApiVersion();cout -当前版本号 ： version - ReqAuthenticate(&field, 5);/认证成功后 注册信息 发起登录void CUser:OnRspAuthenticate(CThostFtdcRspAuthenticateField *pRspAuthenticateField, CThostFtdcRspInfoField *pRspInfo, int nRequestID, bool bIsLast)printf(OnRspAuthenticaten);if (pRspInfo != NULL & pRspInfo-ErrorID = 0):printf(认证成功,ErrorID=0x%04x, ErrMsg=%snn, pRspInfo-ErrorID, pRspInfo-ErrorMsg);RegSystemInfo();ReqUserLogin();elsecout 认证失败， ErrorID= ErrorID ,ErrMsg= ErrorMsg RegisterUserSystemInfo(&field);cout retd = ret ReqUserLogin(&reqUserLogin, +RequestID);3.2.2.3 多对一中继终端使用流程/终端侧采集信息 向中继发起登录 并将终端信息发送给中继char pSystemInfo344;int len;CTP_GetSystemInfo(pSystemInfo, len);cout CTP_GetSystemInfo once endl;/中继在启动后，在API连接后发起认证void CUser:OnFrontConnected()cout OnFrontConnected. GetApiVersion();cout -当前版本号 ： version - ReqAuthenticate(&field, 5);/认证成功后 中继发起登录void CUser:OnRspAuthenticate(CThostFtdcRspAuthenticateField *pRspAuthenticateField, CThostFtdcRspInfoField *pRspInfo, int nRequestID, bool bIsLast)printf(OnRspAuthenticaten);if (pRspInfo != NULL & pRspInfo-ErrorID = 0):printf(认证成功,ErrorID=0x%04x, ErrMsg=%snn, pRspInfo-ErrorID, pRspInfo-ErrorMsg);ReqUserLogin();elsecout 认证失败， ErrorID= ErrorID ,ErrMsg= ErrorMsg ReqUserLogin(&reqUserLogin, +RequestID);/中继使用操作员登录CTP后/终端登录中继时， 中继发起终端信息的上报void CUser:SubSystemInfo()char pSystemInfo344;int len;/CTP_GetSystemInfo(pSystemInfo, len);/终端信息由终端发送到中继/cout CTP_GetSystemInfo endl;cout SubSystemInfo 1 SubmitUserSystemInfo(&field);cout ret = retx SubmitUserSystemInfo(&field1);