格尔签名验证客户端(应用服务器)API_C_ActiveX接口说明

1、.格尔签名验证服务器客户端api_c/activex接口说明v1.7上海格尔软件股份有限公司2006年8月保密事宜：本文档包含上海格尔软件股份有限公司的专有商业信息和保密信息。接受方同意维护本文档所提供信息的保密性，承诺不对其进行复制，或向评估小组以外、非直接相关的人员公开此信息。对于以下三种信息，接受方不向格尔公司承担保密责任：1 ) 接受方在接收该文档前，已经掌握的信息。2 ) 可以通过与接受方无关的其它渠道公开获得的信息。3 ) 可以从第三方，以无附加保密要求方式获得的信息。目 录1接口说明61.1客户端初始化61.2客户端清理61.3验证数据签名61.4验证签名数据和签名证书71.5验

2、证attach方式的pkcs7数据签名81.6验证attach方式的pkcs7数据签名并获取原文91.7证书验证91.8获取证书信息101.9attach方式pkcs7数据签名111.10数据签名（普通签名数据）111.11对文件签名121.12对文件签名数据验证签名131.13对文件解密数字信封141.14detach方式的pkcs#7签名141.15验证detach方式的pkcs#7数据签名151.16验证签名（实时从ldap下载证书并验证）151.17验证原文hash签名162错误码说明173消息格式定义233.1消息格式总体描述233.2验证数据签名243.2.1客户端消息请求格式24

3、3.2.2服务器端验证签名成功的返回消息格式253.2.3服务器端验证签名失败的返回消息格式253.3验证签名数据和签名证书263.3.1客户端消息请求格式263.3.2服务器端验证签名成功的返回消息格式273.3.3服务器端验证签名失败的返回消息格式273.4验证pkcs#7签名数据283.4.1客户端消息请求格式283.4.2服务器端验证签名成功的返回消息格式283.4.3服务器端验证签名失败的返回消息格式293.5证书验证293.5.1客户端消息请求的格式293.5.2服务器端验证成功的返回消息格式303.5.3服务器端验证失败的返回消息格式303.6获取证书信息313.6.1客户端消息

4、请求格式313.6.2服务器端解析证书成功的返回消息格式313.6.3服务器端解析证书失败的返回消息格式323.7数据签名（pkcs#7签名数据）323.7.1客户端消息请求格式323.7.2服务器端签名成功的返回消息格式333.7.3服务器端签名失败的返回消息格式333.8数据签名（普通签名数据）343.8.1客户端消息请求格式343.8.2服务器端签名成功的返回消息格式353.8.3服务器端签名失败的返回消息格式353.9对文件签名363.9.1客户端消息请求格式363.9.2服务器端签名成功的返回消息格式363.9.3服务器端签名失败的返回消息格式373.10对文件签名数据验证签名373

5、.10.1客户端消息请求格式373.10.2服务器端验证签名成功的返回消息格式383.10.3服务器端验证签名失败的返回消息格式383.11对文件解密数字信封393.11.1客户端消息请求格式393.11.2服务器端操作成功的返回消息格式403.11.3服务器端操作失败的返回消息格式403.12验证签名（实时从ldap下载证书并验证）413.12.1客户端消息请求格式413.12.2服务器端操作成功的返回消息格式413.12.3服务器端操作失败的返回消息格式423.13detach方式pkcs7签名423.13.1客户端消息请求格式423.13.2服务器端操作成功的返回消息格式433.13.3

6、服务器端操作失败的返回消息格式433.14detach方式pkcs7签名验证443.14.1客户端消息请求格式443.14.2服务器端操作成功的返回消息格式453.14.3服务器端操作失败的返回消息格式451 接口说明注意：输出缓冲区的空间请在接口外部分配，请预留足够的存储空间，建议预留64k字节。另外输入的原文数据长度有限制，不能大于40k字节大小。注意：以下接口输入和输出的原文都不是b64编码，接口内部会自动转换为b64编码，以便于传送。1.1 客户端初始化函数：int initialverify(char *szip, unsigned short nport)* 初始化环境，这个函数需

7、要在使用之前调用 * 它所完成的工作是初始化全局环境，并且建立与服务器的连接 * 注意:此接口会返回连接句柄，这个句柄将用于后续的操作参数 * * param szip 服务器的ip地址; * param nport 服务器的端口号 * return 返回连接的连接句柄，用于后续操作;如果为负数，表示出错1.2 客户端清理函数：int finalizeverify(int hcontext)* 释放资源 * * param hcontext 连接句柄，通过initialverify接口获得1.3 验证数据签名函数：int verifysign(int nsigntype, int nsigns

8、tytle, unsigned char *porigindata, int noriginlength, char *pb64cert, char *pb64signeddata, int hcontext)* 验证签名有效性 * param nsigntype是进行数字签名前，原文摘要时所用的算法 -1 / 采用直接对原文数据进行签名的方式0 / md2摘要算法1 / md5摘要算法2 / sha1摘要算法 * param nsignstytle 备用参数，目前无效 * param porigindata 原文数据 * param noriginlength 原文数据长度 * param

9、pb64cert 待验证的证书b64编码(中间没有回车换行) * param pb64signeddata 签名数据（b64编码） * param hcontext 连接句柄，通过initialverify接口获得 * return 0 succeed; other fail错误码信息参见“错误码说明”部分。以下同。1.4 验证签名数据和签名证书函数：int verifycertsign(int nsigntype, int nsignstytle, unsigned char *porigindata, int noriginlength, char *pb64cert, char *pb6

10、4signeddata, int iflagcrl, int hcontext)* 验证签名和证书的有效性 * * param nsigntype是数字签名前，原文摘要时所用的算法 -1 / 采用直接对原文数据进行签名的方式0 / md2摘要算法1 / md5摘要算法2 / sha1摘要算法 * param nsignstytle 备用参数，目前无效 * param porigindata 原文数据 * param noriginlength 原文数据长度 * param pb64cert 待验证的证书b64编码(中间没有回车换行) * param pb64signeddata 签名数据（b6

11、4编码） * param iflagcrl 验证证书有效性方式0, 不验证；1，验证黑名单；2 ，使用ocsp验证；其他，只验证证书链 * param hcontext 连接句柄，通过initialverify接口获得 * return 0 succeed; other fail1.5 验证attach方式的pkcs7数据签名函数：int pkcs7dataverify(const char *ppkcs7b64data,const unsigned char *porigindata,unsigned int noriginlen,int hcontext)* attach方式的pkcs#7

12、数据签名验证 * * param ppkcs7b64data p7数据b64编码(包含原文) * param porigindata 签名数据的原文 (attach方式p7签名验证请置为null) * param noriginlen 原文的长度(attach方式p7签名验证请置为0) * param hcontext 连接句柄，通过initialverify接口获得 * return 0 succeed; other fail1.6 验证attach方式的pkcs7数据签名并获取原文函数：int pkcs7dataverifygetoridata(const char *ppkcs7b64d

13、ata,const unsigned char *porigindata,unsigned int *pnoriginlen,int hcontext)* attach方式的pkcs#7数据签名验证,并获取原文信息 * * param ppkcs7b64data p7数据b64编码(包含原文) * param porigindata 返回的原文数据 * param pnoriginlen 返回的原文数据长度 * param hcontext 连接句柄，通过initialverify接口获得 * return 0 succeed; other fail1.7 证书验证函数：int verifyc

14、ert(char *pb64cert, int iflagocsp, int iflagcrl, int hcontext)* 验证证书有效性 * * param pb64cert 待验证的证书b64编码(中间没有回车换行) * param iflagocsp 使用ocsp方式验证标志，1 - 使用ocsp方式验证，0 - 不使用ocsp * param iflagcrl 是否验证黑名单标志，1 - 验证黑名单，0 - 不验证黑名单 * param hcontext 连接句柄，通过initialverify接口获得 * return 0 / 证书没有问题1 / 证书尚未生效2 / 证书已经过期

15、3 / 证书时间有问题4/ 没有有效证书链5 / 签名验证失败6 / 上级证书未通过验证7/ 已被废除1.8 获取证书信息函数：int getcertinfo(char *pb64cert, int ntype, char *pitemname, char *pcertinfo, int hcontext)* 取证书信息 * * param pb64cert 待验证的证书b64编码(中间没有回车换行) * param ntype 证书项的类型0 / 取证书用户信息基本项1 / 取证书的发布者信息项2/ 取证书扩展项 * param pitemname 所要取得证书项名称，如cn等 * para

16、m pcertinfo 所要取得证书项的值 * param hcontext 连接句柄，通过initialverify接口获得 * return 0 succeed; other fail1.9 attach方式pkcs7数据签名函数：int pkcs7datasign(const unsigned char *porigindata, unsigned int norigindatalen, char *psigneddata, int hcontext)* attach方式的pkcs#7数据签名 * * param porigindata 待签名原文,数据长度不能超过40k * param

17、 norigindatalen 原文长度 * param psigneddata 签名后的p7数据b64编码(签名后的数据包含原文) * param hcontext 连接句柄，通过initialverify接口获得 * return 0 succeed; other fail1.10 数据签名（普通签名数据）函数：int signdata(int nsigntype, const unsigned char *porigindata, unsigned int norigindatalen, char *psigneddata, char *pb64cert, int hcontext)*

18、普通格式的数据签名(不使用pkcs7格式封装签名结果) * * param nsigntype是数字签名前，原文摘要时所用的算法 -1 / 采用直接对原文数据进行签名的方式0 / md2摘要算法1 / md5摘要算法2 / sha1摘要算法 * param porigindata 待签名原文 * param norigindatalen 原文长度 * param psigneddata 签名后的数据 * param pb64cert b64编码的签名证书 * param hcontext 连接句柄，通过initialverify接口获得 * return 0 succeed; other fa

19、il1.11 对文件签名函数：int signfile(int nsigntype, char *strfile, int isignalgo, char *strsigneddata, char *pb64cert, int hcontext)* 对文件进行签名(不使用pkcs7格式封装签名结果) * * param nsigntype是数字签名前，原文摘要时所用的算法 -1 / 采用直接对原文数据进行签名的方式0 / sha1摘要算法1 / md5摘要算法 * param strfile 待签名的文件名 * param isignalgo 签名算法,作为扩展使用，暂时无效 * param

20、strsigneddata 签名后的数据 * param pb64cert b64编码的签名证书 * param hcontext 连接句柄，通过initialverify接口获得 * return 0 succeed; other fail1.12 对文件签名数据验证签名函数：int verifyfile(int nsigntype, int isignalgo, char *strfile, char *pb64cert, char *pb64signeddata,int iverifyflag,int hcontext)* 对文件签名进行验证(签名结果不是pkcs7格式封装) * * p

21、aram nsigntype是数字签名前，原文摘要时所用的算法 -1 / 采用直接对原文数据进行签名的方式0 / sha1摘要算法1 / md5摘要算法 * param isignalgo 签名算法,作为扩展使用，暂时无效 * param strfile 待验证的文件名全路径 * param pb64cert 用户证书数据（b64编码） * param pb64signeddata 签名数据 * param iverifyflag 验证证书有效性方法(暂时无效，仅作扩展使用，不验证证书) 0 不验证证书有效性 1 crl方式验证证书有效性 2 ocsp方式验证证书有效性 其他 只验证证书链 *

22、 param hcontext 连接句柄，通过initialverify接口获得 * return 0 succeed; other fail1.13 对文件解密数字信封函数：int decodeenvelopefile(char * strsrcfile, char * strdstfile, int hcontext)* 使用服务器私钥解密数字信封 * * param strsrcfile 待解密的文件的文件名，如果不在当前目录下，需要带路径名 * param strdstfile 解密后文件的文件名，如果不在当前目录下，需要带路径名 * param hcontext 连接句柄，通过ini

23、tialverify接口获得 * return 0 succeed; other fail1.14 detach方式的pkcs#7签名函数：int pkcs7detachdatasign(const unsigned char *porigindata, unsigned int norigindatalen, char *psigneddata, int hcontext)* detach方式的pkcs#7数据签名 * * param porigindata 待签名原文,原文长度没有限制 * param noriginlen 原文的长度 * param psigneddata 签名后的p7格

24、式数据,不包含原文 * param hcontext 连接句柄，通过initialverify接口获得 * return 0 succeed; other fail1.15 验证detach方式的pkcs#7数据签名函数：int pkcs7detachdataverify(const char *ppkcs7b64data,const unsigned char *porigindata,unsigned int noriginlen,int hcontext)* detach方式的pkcs#7数据签名验证 * * param ppkcs7b64data p7数据b64编码(不包含原文) *

25、param porigindata 签名数据的原文 * param noriginlen 原文的长度 * param hcontext 连接句柄，通过initialverify接口获得 * return 0 succeed; other fail1.16 验证签名（实时从ldap下载证书并验证）函数：int verifyldapcertsign(int nsigntype, int isignalgo, unsigned char *strorigindata, int ioriginlength, char *strfilter, char *strb64signeddata, int iv

26、erifyflag, int hcontext)*验证签名和证书的有效性(实时从ldap下载证书并验证其有效性) * * param nsigntype是数字签名前，原文摘要时所用的算法 -1 / 采用直接对原文数据进行签名的方式0 / sha1摘要算法1 / md5摘要算法 * param isignalgo 0 sha1; 1 md5(此参数当前已经失效，只支持sha1) * param strorigindata 原文数据 * param ioriginlength 原文数据长度 * param strfilter 用户证书的证书序列号 * param strb64signeddata

27、签名数据（b64编码） * param iverifyflag 是否验证证书状态 0 不验证证书状态 1 验证证书状态* param hcontext 连接句柄，通过initialverify接口获得 * return 0 succeed; other fail1.17 验证原文hash签名函数：int verifyhashsign(char *pb64originhashdata, char *pb64cert, char *pb64signeddata, int iverifyflag, int hcontext)* 验证原文数据hash签名和证书有效性，用户为了保密/避免传输大数据需要，

28、 * 将原文进行hash，然后调用该接口，避免了原文数据外送 * * param pb64originhashdata 原文数据sha-1 hash后的b64编码 * param pb64cert 待验证的证书b64编码(中间没有回车换行) * param pb64signeddata 签名数据（b64编码） * param iverifyflag 0，不验证证书；1，验证黑名单；2 ，使用ocsp验证 * param hcontext 连接句柄，通过initialverify接口获得 * return 0 succeed; other fail2 错误码说明错误码错误描述0函数操作成功1证书

29、未生效2证书已过期3证书未在有效期内4证书链不完整5证书签名无效6自签名证书或者证书链太长7证书在黑名单中8内存错误-1网络通信出现错误，或未知错误-32p7解密内存错误-109p7不支持的摘要类型-100p7密钥长度错误-111p7不支持的算法类型-112p7不支持的内容数据-1000输入参数错误-1001创建连接套接口失败-1002连接服务器失败-1003输入的数据超过限制-4001pki sdk内部错误-4002pki sdk内部错误-4003未知错误-4004不支持指定运算-4005token没有正确初始化-4006token不可用-4007消息格式不正确-4008处理失败-4009操

30、作暂时不能完成，但以后再试可能成功-4010需要签名-4011没有结构验证-4012token内部错误-4013token不支持此操作-4014文件操作中到达文件尾-4015空指针-4016传入缓冲区太小-4017数组越界-4018内存空间不够-4019参数无效-4020结构中的成员无效-4021没有经过登录无法访问私有对象-4022实例化失败-4023数字格式错误-4024无效的强制类型转换-4025输入/输出错误-4026输出错误-4027输入错误-4028不可序列化-4029用户取消操作-4030无效状态-4031没有找到找到的对象-4032对象已经存在-4033操作被中断-4034连接

31、失败-4035验证失败-4036md2运算时输入数据长度不对-4037rsa解密失败-4038rsa运算时输入数据长度不对-4040无效日期-4050证书已经过期-4300证书链不完整-6001参数为空-6002内存缓冲区太小-6003未初始化kpi环境-6004未初始化token设备-6005无效的session句柄-6006不正确的摘要类型-6007签名数据验证环境未初始化-6008证书验证环境未初始化-6009时间戳验证环境未初始化-6010openssl函数库环境未初始化-6101无效的错误码-6102获取kpi错误信息失败-6201找不到该文件-6202文件格式不正确-6203找不到

32、指定键或键值无效-6204对象未正确初始化-6301找不到指定的slot设备-6302没有指定默认的slot设备-6303token句柄无效-6401缓冲区长度为无效值-6402缓冲区为空-6403不支持的摘要算法-6404b64解码错误-6405数据摘要错误-6406没有通过数据验证-6501缓冲区长度为无效值-6502缓冲区为空-6503b64解码错误-6504非预期的证书格式-6505证书长度超出预定值-6506ocsp验证失败-6507未找到上级证书-6508自签名证书-6509无验证请求-6510无效的黑名单读取路径-6511指定的路径下无有效的黑名单文件-6512找不到指定的文件-

33、6513非预期的文件长度-6514无效的证书文件读取路径-6515指定的路径下无有效的证书文件-6516ocsp的url为空-6517要获取的证书项类型错误-6518获取证书项信息出错-6519指定的证书项不存在-6520缓冲区长度过小-6521将证书转换成x509格式出错-6522内存空间不足-6523字符码转换出错-6524不能根据oid字符创建asn对象-6525指定的扩展项不存在-6526扩展项的字符长度超过预期长度-6527创建bio对象失败-6528主机名不能被解析-6529创建套接字失败-6530连接ocsp服务器失败-6531ocsp服务的url地址无效-6601缓冲区长度为无

34、效值-6602缓冲区为空-6603b64解码错误-6604证书信息无效-6605时间戳签名数据结构无效-6606找不到内部签名数据-6607不能解析出数据原文-6608缓冲区长度不足-6701未成功解析pkcs#7数据-6702, -6801无效的配置模块指针-6802无签名配置信息-6803不能打开指定的文件-6804文件大小不符合预期范围-6805无效的证书文件-6806无效的私钥文件-6807pkcs#7签名环境未初始化-6808无效的参数-6809接收签名数据的缓冲区太小-6810不正确的pkcs#7签名请求格式-6811签名错误-6812无足够的内存空间创建操作对象-6813不是pk

35、cs#7数字信封-6814证书状态无效（针对ldap方式验证证书）组装p7报文失败（针对p7签名验证）-6815待验签名原文hash长度不合法-6816从p7包中获取签名证书失败-6817从p7包中获取签名数据失败-6818验证p7签名失败-7001ldap未初始化（针对ldap方式验证证书）获取证书公钥失败（针对普通证书验证）-7002ldap服务器登录失败（针对ldap方式验证）错误的签名算法（针对普通证书验证）-7003，-7004ldap服务器上找不到指定节点-7005从ldap服务器查询操作失败(可能是查询条件不合法)-7100打开文件失败-7101文件大小超过大小限制-7102rs

36、a加密失败-7103rsa解密失败-7104加密失败-7105解密失败-7106从p7数据中获取证书失败-7107从p7数据中获取签名结果失败-9000不支持的功能3 消息格式定义3.1 消息格式总体描述本章定义客户端与服务器端通信的所有消息格式以及接口说明。与服务器端的通信协议采用tcp端口，默认情况下，服务器tcp端口是5000消息包括消息头和消息体两个部分，消息头的定义如下：字段名称字段意义字段值msg_type消息的类型0-消息请求1-正确结果返回2-错误结果返回msg_id消息id1000-验证证书1001-验证签名数据1002-验证签名及签名证书1003-验证时间戳1004-获取证书信息1005-attach方式pkcs7格式签名1006-attach方式pkcs7格式签名验证1007-