中国结算CA系统对外服务接口开发使用文档.docx

中国结算CA系统对外服务接口开发使用文档

北京信安世纪科技有限公司

目录
1 基本功能 4
2 接口描述 4
2.1 接口约定 4
2.2 接口定义 5
2.2.1 申请证书 5
2.2.1.1 个人证书 5
2.2.1.2 企业证书 11
2.2.1.3 企业员工证书 17
2.2.2 更新证书 22
2.2.2.1 个人证书 22
2.2.2.2 企业证书 26
2.2.2.3 企业员工证书 31
2.2.3 补办证书 35
2.2.3.1 个人证书 35
2.2.3.2 企业证书 39
2.2.3.3 企业员工证书 43
2.2.4 冻结证书 47
2.2.4.1 个人证书 47
2.2.4.2 企业证书 49
2.2.4.3 企业员工证书 50
2.2.5 解冻证书 52
2.2.5.1 个人证书 52
2.2.5.2 企业证书 54
2.2.5.3 企业员工证书 55
2.2.6 作废证书 57
2.2.6.1 个人证书 57
2.2.6.2 企业证书 59
2.2.6.3 企业员工证书 60
2.2.7 查询证书 62
2.2.7.1 个人证书 62
2.2.7.2 企业证书 65
2.2.7.3 企业员工证书 67
2.2.8 查询用户及证书信息 69
2.2.8.1 个人用户及证书 69
2.2.8.2 企业用户及证书 72
2.2.8.3 企业员工及证书 75
2.2.9 证书下载 78
附录1证书类型 81
附录2证书状态 82
附录3个人身份证件类型 83
附录4 机构证件类型 84
附录5证书DN 85
附录6名词解释 86
附录7国籍（地区）代码 88
附录8错误码定义 94
附录9证书申请方式 97

修订历史记录

Revision
Author/Modifier
Comments
No.
Date

2013-05-14
jhliu/zhenggg

1 基本功能
中国证券登记结算有限责任公司（以下简称：中国结算）CA系统对外服务支持多个证书代理服务机构的接入，同时能够管理和连接多个CA系统，并能对接入的所属机构的个人和企业信息进行管理，提供证书的申请、更新、作废、冻结、解冻、补办和下载等操作，以及证书统计和查询等操作功能。中国结算CA系统概述详见《中国结算CA系统准入测试方案》。
2 接口描述
2.1 准备环境
所需资源：
Windows系统（win7系统）
iconv-1.9.2.win32
openssl-1.0.0d
安装vs2005。

其中，iconv-1.9.2.win32和openssl-1.0.0d已在项目工程文件下的lib文件夹中，项目工程已经配置了该路径，只需运行工程即可。

2.2 接口定义
2.2.1 申请证书
2.2.1.1 个人证书
2.2.1.1.1 申请返回两码（后续需要调用证书下载的接口）
WebService调用方法：int perCertRequest( PERSONINFO personReq, char serial[128] , PROCESSRESULT* processresult)

接口参数
参数名称personReq：请求XML消息报文；
Serial：序列号；
包含两码的返回结果：processresult

示例请求XML消息报文：
<?xml version="1.0" encoding="utf-8"?>
<request>
<caid>1</caid>
<transactioncode>1000200030004000</transactioncode>
<parameters>
<accountholdername>张三</accountholdername>
<accountholderabbre>address</accountholderabbre>
<nationality>156</nationality>
<cardtype1>02</cardtype1>
<cardnum1>20001</cardnum1>
<cardissuingauthority1></cardissuingauthority1>
<cardexpirationtime1></cardexpirationtime1>
<cardtype2></cardtype2>
<cardnum2></cardnum2>
<cardissuingauthority2></cardissuingauthority2>
<cardexpirationtime2></cardexpirationtime2>
<cardtype3></cardtype3>
<cardnum3></cardnum3>
<cardissuingauthority3></cardissuingauthority3>
<cardexpirationtime3></cardexpirationtime3>
<headpic></headpic>
<fingerprint></fingerprint>
<mobilephone>13901234567</mobilephone>
<mail>zhangsan@</mail>
<certtype>1</certtype>
<timestamp>20130509202500</timestamp>
<requesttype>01</requesttype>
</parameters>
<sign>
<signAlg>SHA1withRSA</signAlg>
<signValue>
hk2QnDmaRCBXc1f65/N7MM8NFyWp0PC4nqZGdAnCAtHwOfn46jpPIq0KAoEYuN9dZ+SjbSv2FTkoA8dezFfskCXk1gxuurWpHIglvtD1bEk+83sNNIRHoGXQylhocd2K2KZAtLa5nuH331nmxndxT0mlX/HefoHa9Sviyd7YaEw=
</signValue>
<signCertDN>CN=10011001@1000000001,OU=Acess,O=CSDCCA,C=CN
</signCertDN>
</sign>
</request>
参数说明
字段名
最大长度
是否必选
说明

caid
1
是
连接CA ID
RSA算法CA（目前不开放其他算法CA）
transactioncode
20
是
交易流水号
机构生成，4位机构号8位机构号+随机码，机构编号为机构组织代码证的前8位，RAServer不判断唯一性
accountholdername
128
是
账户持有人名称
用户信息
1）账户持有人名称
2）国籍
3）第一证件类型
4）第一证件号
为关键要素，确认一张个人用户证书。申请后不能修改
accountholderabbre
32
否
账户持有人简称
nationality
8
是
国籍（附录7）
cardtype1
2
是
第一证件类型（附录3）
cardnum1
32
是
第一证件号
cardissuingauthority1
128
否
第一证件发证机关
cardexpirationtime1
14
否
第一证件失效时间

cardtype2
2
否
第二证件类型（附录3）

cardnum2
32
否
第二证件号

cardissuingauthority2
128
否
第二证件发证机关

cardexpirationtime2
14
否
第二证件失效时间

cardtype3
2
否
第三证件类型（附录3）

cardnum3
32
否
第三证件号

cardissuingauthority3
128
否
第三证件发证机关

cardexpirationtime3
14
否
第三证件失效时间

headpic
2048
否
投资者头像

fingerprint
2048
否
指纹信息

mobilephone
20
否
手机

mail
64
否
邮件

certtype
2
是
请求证书类型（见附录1证书类型）

timestamp
14
是
申请时间
时间格式：yyyyMMddHHmmss
（由机构保证，RA不验证日期格式）
requesttype
2
是
证书申请方式（附录9）

signAlg
20
是
签名算法
请求签名信息，请求签名信息，对<parameters>参数内进行签名（含<parameters>）
signValue
1024
是
签名值(使用机构接入证书签名)
signCertDN
128
是
机构接入证书DN

对应于上面的消息报文，构造结构体PERSONINFO如下：
typedef struct personinfo_s {
//============开始进行个人用户证书申请操作============
char Accountholdername[132]; //账户持有人名称
char Accountholderabbre[36]; //账户持有人简称
char Nationality[64]; //国籍编号（参看中登接口附录）
char Cardtype1[4]; //第一证件类型（参看中登接口附录）
char Cardnum1[36]; //第一证件号
char Cardissuingauthority1[132]; //第一证件发证机关
char Cardexpirationtime1[16]; //第一证件失效时间
char Cardtype2[4]; //第二证件类型（参看中登接口附录）
char Cardnum2[36]; //第二证件编号
char Cardissuingauthority2[132]; //第二证件发证机关
char Cardexpirationtime2[16]; //第二证件失效时间
char Cardtype3[4]; //第三证件类型（参看中登接口附录）
char Cardnum3[36]; //第三证件编号
char Cardissuingauthority3[132]; //第三证件发证机关
char Cardexpirationtime3[16]; //第三证件失效时间
char Headpic[2052]; //投资者头像
char Fingerprint[2052]; //指纹
char Mobilephone[24]; //手机
char Mail[68]; //邮件
char Certtype[4]; //请求证书类型（见接口规范附录证书类型）
char Timestamp[16]; //14位申请时间
char Requesttype[4]; //证书申请方式（见接口规范附录）
char usbkeyid[16]; //14位Usbkey序列号
char P10[2052];
} PERSONINFO;

示例返回XML消息报文：
<?xml version=“1.0” encoding=“UTF-8”?>
<response command=“perCertRequest”>
<transactioncode>1001123443420123410222</transactioncode>
<errorcode>0</errorcode>
<errormsg></errormsg>
<refno>RDKSAFDD</refno>
<authcode>CCDFKDSA</authcode>
<certsn>A012BD21</certsn>
</response>
参数说明
字段名
最大长度
是否必选
说明
transactioncode
20
是
交易流水号
errorcode
8
是
0成功，返回refno authcode certsn
非0为失败，返回错误码
errormsg
128
否
错误信息
refno
32
否
参考号（errorcode为0返回）
authcode
32
否
授权码（errorcode为0返回）
certsn
32
否
证书SN（errorcode为0返回）
对应于上面的返回消息报文，构造结构体PROCESSRESULT，用于保存返回的信息，如下：
typedef struct processresult_s {
char Refnumber[36]; /* 访问者DN*/
char Authcode[36]; /* ca序列号*/
char CertSN[36]; /* 签名算法*/
char Certstring[5000]; /* 证书*/
char Errcode[12];
char Errmsg[132]; /*128位错误信息（errorcode非返回）*/
//char p7cert[4096]; /*4096位P7b格式证书（errorcode为返回）；*/
int Reserved; /*预留*/
char Transactioncode[24];
} PROCESSRESULT;
2.2.1.1.2 申请下载证书
WebService调用方法：int perCertRequestAndDown( PERSONINFO personReq, char serial[128] , PROCESSRESULT* processresult)
接口参数：
personReq：请求XML消息报文；
serial：序列号；
返回参数：processresult
2.2.1.2 企业证书
2.2.1.2.1 申请返回两码
WebService调用方法：int entCertRequest( ENTERPRISEINFO entReq, char serial[128] , PROCESSRESULT* processresult)
接口参数
entReq：请求XML消息报文；
serial：序列号；
返回参数：processresult

示例请求XML消息报文：
<?xml version=“1.0” encoding=“UTF-8”?>
<request>
<caid>1</caid>
<transactioncode>1001123443420123410222</transactioncode>
<parameters>
<entname>北京科技有限公司</entname>
<username>张三</username>
<cardtype>02</cardtype>
<cardnum>00021</cardnum>
<businessenterprisetype1>02</businessenterprisetype1>
<businessenterprisenum1>21321321312</businessenterprisenum1>
<businessissuingauthority1></businessissuingauthority1>
<expirationtime1></expirationtime1>
<businessenterprisetype2></businessenterprisetype2>
<businessenterprisenum2></businessenterprisenum2>
<businessissuingauthority2></businessissuingauthority2>
<expirationtime2></expirationtime2>
<businessenterprisetype3></businessenterprisetype3>
<businessenterprisenum3></businessenterprisenum3>
<businessissuingauthority3></businessissuingauthority3>
<expirationtime3></expirationtime3>
<mobilephone></mobilephone>
<mail></mail>
<certtype>4</certtype>
<timestamp>20130509205207</timestamp>
<requesttype>01</requesttype>
</parameters>
<sign>
<signAlg>SHA1withRSA</signAlg>
<signValue>
hk2QnDmaRCBXc1f65/N7MM8NFyWp0PC4nqZGdAnCAtHwOfn46jpPIq0KAoEYuN9dZ+SjbSv2FTkoA8dezFfskCXk1gxuurWpHIglvtD1bEk+83sNNIRHoGXQylhocd2K2KZAtLa5nuH331nmxndxT0mlX/HefoHa9Sviyd7YaEw=
</signValue>
<signCertDN> CN=10011001@1000000001,OU=Acess,O=CSDCCA,C=CN
</signCertDN>
</sign>
</request>

参数说明
字段名
最大长度
是否必选
说明

caid
1
是
连接CA ID
RSA算法CA（目前不开放其他算法CA）
transactioncode
20
是
交易流水号
机构生成，4位机构号8位机构号+随机码，RA不判断唯一性
entname
128
是
企业名称
企业用户信息
1）企业名称
2）企业证书持有人证件类型
3）企业证书持有人证件号
4）企业机构证件类型1
5）企业机构证件号1
为关键要素，确认一张企业证书。申请后不能修改
username
64
是
企业证书持有人姓名
cardtype
2
是
企业证书持有人证件类型（附录3）
cardnum
32
是
企业证书持有人证件号
businessenterprisetype 1
2
是
企业机构证件类型1（附录4）
businessenterprisenum1
64
是
企业机构证件号1
businessissuingauthority1
128
否
企业机构证件发证机关1
expirationtime1
14
否
企业机构证件失效时间1
businessenterprisetype2
2
否
企业机构证件类型2（附录4）
businessenterprisenum2
64
否
企业机构证件号2
businessissuingauthority2
128
否
企业机构证件发证机关2
expirationtime2
14
否
企业机构证件失效时间2
businessenterprisetype3
2
否
企业机构证件类型3（附录4）
businessenterprisenum3
64
否
企业机构证件号3
businessissuingauthority3
128
否
企业机构证件发证机关3
expirationtime3
14
否
企业机构证件失效时间3

mobilephone
20
否
企业联系人电话

mail
64
否
企业联系人邮箱

certtype
2
是
请求证书类型

timestamp
14
是
申请时间
时间格式：yyyyMMddHHmmss
（由机构保证，RA不验证日期格式）
requesttype
2
是
证书申请方式（附录9）

signAlg
20
是
签名算法
请求签名信息，请求签名信息，对<parameters>参数内进行签名（含<parameters>）
signValue
1024
是
签名值(使用机构接入证书签名)
signCertDN
128
是
机构接入证书DN
对应于上面的请求消息报文，构造结构体ENTERPRISEINFO用于发送数据，如下
typedef struct enterpriseinfo_s {
//============开始进行企业用户证书申请操作============
char entname[132]; //企业名称
char username[68]; //企业证书持有人
char Cardtype[4]; //企业证书持有人证件类型（附录）
char Cardnum[36]; //企业证书持有人证件号
char businessenterprisetype1 [4]; //企业机构证件类型（附录）
char businessenterprisenum1[68]; //企业机构证件号
char businessissuingauthority1[132]; //企业机构证件发证机关
char expirationtime1[16]; //企业机构证件失效时间

char businessenterprisetype2 [4]; //企业机构证件类型（附录）
char businessenterprisenum2[68]; //企业机构证件号
char businessissuingauthority2[132]; //企业机构证件发证机关
char expirationtime2[16]; //企业机构证件失效时间

char businessenterprisetype3 [4]; //企业机构证件类型（附录）
char businessenterprisenum3[68]; //企业机构证件号
char businessissuingauthority3[132]; //企业机构证件发证机关
char expirationtime3[16]; //企业机构证件失效时间

char Mobilephone[32]; //手机
char Mail[68]; //邮件
char Certtype[4]; //请求证书类型（见接口规范附录证书类型）
char Timestamp[16]; //14位申请时间
char Requesttype[4]; //证书申请方式（见接口规范附录）
char usbkeyid[16]; //14位Usbkey序列号

char P10[2052];//2048
} ENTERPRISEINFO;

示例返回XML消息报文：
<?xml version=“1.0” encoding=“UTF-8”?>
<response command=“entCertRequest”>
<transactioncode>121</transactioncode>
<errorcode>0</errorcode>
<errormsg></errormsg>
<refno>RDKSAFDD</refno>
<authcode>CCDFKDSA</authcode>
<certsn>A012BD21</certsn>
</response>
参数说明
字段名
最大长度
是否必选
说明
transactioncode
20
是
交易流水号
errorcode
8
是
0成功，返回refno authcode certsn
非0失败，返回错误码
errormsg
128
否
错误信息（errorcode非0返回）
refno
32
否
参考号（errorcode为0返回）
authcode
32
否
授权码（errorcode为0返回）

Certsn
32
否
证书SN（errorcode为0返回）
对应于返回消息报文，构造结构体PROCESSRESULT用来保存返回消息。
typedef struct processresult_s {
char Refnumber[36]; /* 访问者DN*/
char Authcode[36]; /* ca序列号*/
char CertSN[36]; /* 签名算法*/
char Certstring[5000]; /* 证书*/
char Errcode[12];
char Errmsg[132]; /*128位错误信息（errorcode非返回）*/
//char p7cert[4096]; /*4096位P7b格式证书（errorcode为返回）；*/
int Reserved; /*预留*/
char Transactioncode[24];
} PROCESSRESULT;

2.2.1.2.2 申请下载证书
WebService调用方法：int entCertRequestAndDown ( ENTERPRISEINFO personReq, char serial[128] , PROCESSRESULT* processresult)
接口参数
personReq：请求XML消息报文；
serial：序列号；
返回参数：processresult
2.2.1.3 企业员工证书
2.2.1.3.1 申请返回两码
WebService调用方法：int operatorCertRequest( OPERATORINFO operatorReq, char serial[128] , PROCESSRESULT* processresult)
接口参数
operatorReq：请求XML消息报文；
serial：序列号；
返回参数：processResult

请求XML消息报文：
<?xml version=“1.0” encoding=“UTF-8”?>
<request>
<caid>1</caid>
<transactioncode>1001123443420123410222</transactioncode>
<parameters>
<entname>北京科技有限公司</entname>
<operatorname>张三</operatorname>
<cardtype>01</cardtype>
<cardnum>110101199001011234</cardnum>
<mobilephone>13901234123</mobilephone>
<mail>test@</mail>
<certtype>7</certtype>
<timestamp>20130101120000</timestamp>
</parameters>
<sign>
<signAlg>SHA1withRSA</signAlg>
<signValue>
hk2QnDmaRCBXc1f65/N7MM8NFyWp0PC4nqZGdAnCAtHwOfn46jpPIq0KAoEYuN9dZ+SjbSv2FTkoA8dezFfskCXk1gxuurWpHIglvtD1bEk+83sNNIRHoGXQylhocd2K2KZAtLa5nuH331nmxndxT0mlX/HefoHa9Sviyd7YaEw=
</signValue>
<signCertDN>CN=10011001@1000000001,OU=Acess,O=CSDCCA,C=CN
</signCertDN>
</sign>
</request>

参数说明
字段名
最大长度
是否必选
说明

caid
1
是
连接CA ID
RSA算法CA（目前不开放其他算法CA）
transactioncode
20
是
交易流水号
机构生成，4位机构号8位机构号+随机码，RA不判断唯一性
entname
128
是
企业名称
企业员工信息
1） 企业名称
2） 企业员工姓名
3） 企业员工证件类型
4） 企业员工证件号
为关键要素，确认一张企业操作员证书

operatorusername
128
是
企业员工姓名
cardtype
2
是
企业员工证件类型（附录3）
cardnum
32
是
企业员工证件号
mobilephone
20
否
企业联系人电话
mail
100
否
企业联系人邮箱
certtype
2
是
请求证书类型

timestamp
14
是
申请时间
时间格式：yyyyMMddHHmmss
（由机构保证，RA不验证日期格式）
signAlg
20
是
签名算法
请求签名信息，请求签名信息，对<parameters>参数内进行签名（含<parameters>）
signValue
1024
是
签名值(使用机构接入证书签名)
signCertDN
128
是
机构接入证书DN
构造结构体用于发送报文消息，
typedef struct operatorinfo_s {
//============开始进行企业员工证书申请操作============
char entname[132]; //企业名称
char operatorname[132]; //企业员工
char Cardtype[4]; //企业员工证件类型（附录）
char Cardnum[36]; //企业员工证件号

char Mobilephone[32]; //手机
char Mail[128]; //邮件
char Certtype[4]; //请求证书类型（见接口规范附录证书类型）
char Timestamp[16]; //14位申请时间

char Requesttype[4]; //证书申请方式（见接口规范附录）
char usbkeyid[16]; //14位Usbkey序列号
char P10[2052];

}OPERATORINFO;

返回XML消息报文：
<?xml version=“1.0” encoding=“UTF-8”?>
<response command=“operatorCertRequest”>
<transactioncode>121</transactioncode>
<errorcode>0</errorcode>
<errormsg></errormsg>
<refno>RDKSAFDD</refno>
<authcode>CCDFKDSA</authcode>
<certsn>A012BD21</certsn>
</response>
参数说明
字段名
最大长度
是否必选
说明
transactioncode
20
是
交易流水号
errorcode
8
是
0成功，返回refno authcode certsn
非0失败，返回错误码
errormsg
128
否
错误信息（errorcode非0返回）
refno
32
否
参考号（errorcode为0返回）
authcode
32
否
授权码（errorcode为0返回）
certsn
32
否
证书SN（errorcode为0返回）

2.2.1.3.2 申请下载证书
WebService调用方法：int operatorCertRequestAndDown ( OPERATORINFO operatorReq, char serial[128] , PROCESSRESULT* processresult)

接口参数
operatorReq：请求XML消息报文；
serial：序列号；
返回参数：processresult

请求XML消息报文：

<?xml version=“1.0” encoding=“UTF-8”?>
<request>
<caid>1</caid>
<transactioncode>1001123443420123410222</transactioncode>
<parameters>
<entname>北京科技有限公司</entname>
<operatorname>张三</operatorname>
<cardtype>01</cardtype>
<cardnum>110101199001011234</cardnum>
<mobilephone>13901234123</mobilephone>
<mail>test@</mail>
<certtype>7</certtype>
<timestamp>20130101120000</timestamp>
<usbkeyid>11111111</usbkeyid>
<pkcs10>
MIGJAoGBAJsUuq28