格尔SVSAPICActiveX接口说明.docx

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

2、验证数据签名 61.4 验证签名数据和签名证书 71.5 验证Attach方式的PKCS7数据签名 81.6 验证Attach方式的PKCS7数据签名并获取原文 91.7 证书验证 91.8 获取证书信息 101.9 Attach方式PKCS7数据签名 111.10 数据签名（普通签名数据） 111.11 对文件签名 121.12 对文件签名数据验证签名 131.13 对文件解密数字信封 141.14 Detach方式的PKCS#7签名 141.15 验证Detach方式的PKCS#7数据签名 151.16 验证签名（实时从LDAP下载证书并验证） 151.17 验证原文HASH签名 162

3、错误码说明 173 消息格式定义 233.1 消息格式总体描述 233.2 验证数据签名 243.2.1 客户端消息请求格式 243.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 证书

4、验证 293.5.1 客户端消息请求的格式 293.5.2 服务器端验证成功的返回消息格式 303.5.3 服务器端验证失败的返回消息格式 303.6 获取证书信息 313.6.1 客户端消息请求格式 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 服务器端签名成功的返回消息

5、格式 353.8.3 服务器端签名失败的返回消息格式 353.9 对文件签名 363.9.1 客户端消息请求格式 363.9.2 服务器端签名成功的返回消息格式 363.9.3 服务器端签名失败的返回消息格式 373.10 对文件签名数据验证签名 373.10.1 客户端消息请求格式 373.10.2 服务器端验证签名成功的返回消息格式 383.10.3 服务器端验证签名失败的返回消息格式 383.11 对文件解密数字信封 393.11.1 客户端消息请求格式 393.11.2 服务器端操作成功的返回消息格式 403.11.3 服务器端操作失败的返回消息格式 403.12 验证签名（实时从LD

6、AP下载证书并验证） 413.12.1 客户端消息请求格式 413.12.2 服务器端操作成功的返回消息格式 413.12.3 服务器端操作失败的返回消息格式 423.13 Detach方式PKCS7签名 423.13.1 客户端消息请求格式 423.13.2 服务器端操作成功的返回消息格式 433.13.3 服务器端操作失败的返回消息格式 433.14 Detach方式PKCS7签名验证 443.14.1 客户端消息请求格式 443.14.2 服务器端操作成功的返回消息格式 453.14.3 服务器端操作失败的返回消息格式 451 接口说明注意：输出缓冲区的空间请在接口外部分配，请预留足够的

7、存储空间，建议预留64K字节。另外输入的原文数据长度有限制，不能大于40K字节大小。注意：以下接口输入和输出的原文都不是B64编码，接口内部会自动转换为B64编码，以便于传送。1.1 客户端初始化函数：int InitialVerify(char *szIP, unsigned short nPort)* 初始化环境，这个函数需要在使用之前调用 * 它所完成的工作是初始化全局环境，并且建立与服务器的连接 * 注意:此接口会返回连接句柄，这个句柄将用于后续的操作参数 * * param szIP 服务器的IP地址; * param nPort 服务器的端口号 * return 返回连接的连接句柄

8、，用于后续操作;如果为负数，表示出错1.2 客户端清理函数：int FinalizeVerify(int hContext)* 释放资源 * * param hContext 连接句柄，通过InitialVerify接口获得1.3 验证数据签名函数：int VerifySign(int nSignType, int nSignStytle, unsigned char *pOriginData, int nOriginLength, char *pB64Cert, char *pB64SignedData, int hContext)* 验证签名有效性 * param nSignType是进行

9、数字签名前，原文摘要时所用的算法 -1 / 采用直接对原文数据进行签名的方式 0 / MD2摘要算法 1 / MD5摘要算法 2 / SHA1摘要算法 * param nSignStytle 备用参数，目前无效 * param pOriginData 原文数据 * param nOriginLength 原文数据长度 * param pB64Cert 待验证的证书B64编码(中间没有回车换行) * param pB64SignedData 签名数据（b64编码） * param hContext 连接句柄，通过InitialVerify接口获得 * return 0 succeed; othe

10、r fail错误码信息参见“错误码说明”部分。以下同。1.4 验证签名数据和签名证书函数：int VerifyCertSign(int nSignType, int nSignStytle, unsigned char *pOriginData, int nOriginLength, char *pB64Cert, char *pB64SignedData, int iFlagCRL, int hContext)* 验证签名和证书的有效性 * * param nSignType是数字签名前，原文摘要时所用的算法 -1 / 采用直接对原文数据进行签名的方式 0 / MD2摘要算法 1 / MD5

11、摘要算法 2 / SHA1摘要算法 * param nSignStytle 备用参数，目前无效 * param pOriginData 原文数据 * param nOriginLength 原文数据长度 * param pB64Cert 待验证的证书B64编码(中间没有回车换行) * param pB64SignedData 签名数据（b64编码） * param iFlagCRL 验证证书有效性方式0, 不验证；1，验证黑名单；2 ，使用OCSP验证；其他，只验证证书链 * param hContext 连接句柄，通过InitialVerify接口获得 * return 0 succeed;

12、 other fail1.5 验证Attach方式的PKCS7数据签名函数：int PKCS7DataVerify(const char *pPKCS7B64Data, const unsigned char *pOriginData, unsigned int nOriginLen, int hContext)* Attach方式的PKCS#7数据签名验证 * * param pPKCS7B64Data P7数据B64编码(包含原文) * param pOriginData 签名数据的原文 (Attach方式P7签名验证请置为NULL) * param nOriginLen 原文的长度(At

13、tach方式P7签名验证请置为0) * param hContext 连接句柄，通过InitialVerify接口获得 * return 0 succeed; other fail1.6 验证Attach方式的PKCS7数据签名并获取原文函数：int PKCS7DataVerifyGetOriData(const char *pPKCS7B64Data, const unsigned char *pOriginData, unsigned int *pnOriginLen, int hContext)* Attach方式的PKCS#7数据签名验证,并获取原文信息 * * param pPKCS

14、7B64Data P7数据B64编码(包含原文) * param pOriginData 返回的原文数据 * param pnOriginLen 返回的原文数据长度 * param hContext 连接句柄，通过InitialVerify接口获得 * return 0 succeed; other fail1.7 证书验证函数：int VerifyCert(char *pB64Cert, int iFlagOCSP, int iFlagCRL, int hContext)* 验证证书有效性 * * param pB64Cert 待验证的证书B64编码(中间没有回车换行) * param iF

15、lagOCSP 使用OCSP方式验证标志，1 - 使用OCSP方式验证，0 - 不使用OCSP * param iFlagCRL 是否验证黑名单标志，1 - 验证黑名单，0 - 不验证黑名单 * param hContext 连接句柄，通过InitialVerify接口获得 * return 0 / 证书没有问题 1 / 证书尚未生效 2 / 证书已经过期 3 / 证书时间有问题 4 / 没有有效证书链 5 / 签名验证失败 6 / 上级证书未通过验证 7 / 已被废除1.8 获取证书信息函数：int GetCertInfo(char *pB64Cert, int nType, char *p

16、ItemName, char *pCertInfo, int hContext)* 取证书信息 * * param pB64Cert 待验证的证书B64编码(中间没有回车换行) * param nType 证书项的类型 0 / 取证书用户信息基本项 1 / 取证书的发布者信息项 2 / 取证书扩展项 * param pItemName 所要取得证书项名称，如CN等 * param pCertInfo 所要取得证书项的值 * param hContext 连接句柄，通过InitialVerify接口获得 * return 0 succeed; other fail1.9 Attach方式PKCS

17、7数据签名函数：int PKCS7DataSign(const unsigned char *pOriginData, unsigned int nOriginDataLen, char *pSignedData, int hContext)* Attach方式的PKCS#7数据签名 * * param pOriginData 待签名原文,数据长度不能超过40K * param nOriginDataLen 原文长度 * param pSignedData 签名后的P7数据B64编码(签名后的数据包含原文) * param hContext 连接句柄，通过InitialVerify接口获得 *

18、 return 0 succeed; other fail1.10 数据签名（普通签名数据）函数：int SignData(int nSignType, const unsigned char *pOriginData, unsigned int nOriginDataLen, char *pSignedData, char *pB64Cert, int hContext)* 普通格式的数据签名(不使用PKCS7格式封装签名结果) * * param nSignType是数字签名前，原文摘要时所用的算法 -1 / 采用直接对原文数据进行签名的方式 0 / MD2摘要算法 1 / MD5摘要算法

19、 2 / SHA1摘要算法 * param pOriginData 待签名原文 * param nOriginDataLen 原文长度 * param pSignedData 签名后的数据 * param pB64Cert B64编码的签名证书 * param hContext 连接句柄，通过InitialVerify接口获得 * return 0 succeed; other fail1.11 对文件签名函数：int SignFile(int nSignType, char *strFile, int iSignAlgo, char *strSignedData, char *pB64Cer

20、t, int hContext)* 对文件进行签名(不使用PKCS7格式封装签名结果) * * param nSignType是数字签名前，原文摘要时所用的算法 -1 / 采用直接对原文数据进行签名的方式 0 / SHA1摘要算法 1 / MD5摘要算法 * param strFile 待签名的文件名 * param iSignALgo 签名算法, 作为扩展使用，暂时无效 * param strSignedData 签名后的数据 * param pB64Cert B64编码的签名证书 * param hContext 连接句柄，通过InitialVerify接口获得 * return 0 su

21、cceed; other fail1.12 对文件签名数据验证签名函数：int VerifyFile(int nSignType, int iSignAlgo, char *strFile, char *pB64Cert, char *pB64SignedData,int iVerifyFlag,int hContext)* 对文件签名进行验证(签名结果不是PKCS7格式封装) * * param nSignType是数字签名前，原文摘要时所用的算法 -1 / 采用直接对原文数据进行签名的方式 0 / SHA1摘要算法 1 / MD5摘要算法 * param iSignALgo 签名算法, 作

22、为扩展使用，暂时无效 * param strFile 待验证的文件名全路径 * param pB64Cert 用户证书数据（b64编码） * param pB64SignedData 签名数据 * param iVerifyFlag 验证证书有效性方法(暂时无效，仅作扩展使用，不验证证书) 0 不验证证书有效性 1 CRL方式验证证书有效性 2 OCSP方式验证证书有效性 其他 只验证证书链 * param hContext 连接句柄，通过InitialVerify接口获得 * return 0 succeed; other fail1.13 对文件解密数字信封函数：int DecodeEnv

23、elopeFile(char * strSrcFile, char * strDstFile, int hContext)* 使用服务器私钥解密数字信封 * * param strSrcFile 待解密的文件的文件名，如果不在当前目录下，需要带路径名 * param strDstFile 解密后文件的文件名，如果不在当前目录下，需要带路径名 * param hContext 连接句柄，通过InitialVerify接口获得 * return 0 succeed; other fail1.14 Detach方式的PKCS#7签名函数：int PKCS7DetachDataSign(const u

24、nsigned char *pOriginData, unsigned int nOriginDataLen, char *pSignedData, int hContext)* Detach方式的PKCS#7数据签名 * * param pOriginData 待签名原文,原文长度没有限制 * param nOriginLen 原文的长度 * param pSignedData 签名后的P7格式数据,不包含原文 * param hContext 连接句柄，通过InitialVerify接口获得 * return 0 succeed; other fail1.15 验证Detach方式的PKC

25、S#7数据签名函数：int PKCS7DetachDataVerify(const char *pPKCS7B64Data, const unsigned char *pOriginData, unsigned int nOriginLen, int hContext)* Detach方式的PKCS#7数据签名验证 * * param pPKCS7B64Data P7数据B64编码(不包含原文) * param pOriginData 签名数据的原文 * param nOriginLen 原文的长度 * param hContext 连接句柄，通过InitialVerify接口获得 * ret

26、urn 0 succeed; other fail1.16 验证签名（实时从LDAP下载证书并验证）函数：int VerifyLdapCertSign(int nSignType, int iSignAlgo, unsigned char *strOriginData, int iOriginLength, char *strFilter, char *strB64SignedData, int iVerifyFlag, int hContext)*验证签名和证书的有效性(实时从LDAP下载证书并验证其有效性) * * param nSignType是数字签名前，原文摘要时所用的算法 -1 /

27、 采用直接对原文数据进行签名的方式 0 / SHA1摘要算法 1 / MD5摘要算法 * param iSignAlgo 0 SHA1; 1 MD5(此参数当前已经失效，只支持SHA1) * param strOriginData 原文数据 * param iOriginLength 原文数据长度 * param strFilter 用户证书的证书序列号 * param strB64SignedData 签名数据（b64编码） * param iVerifyFlag 是否验证证书状态 0 不验证证书状态 1 验证证书状态* param hContext 连接句柄，通过InitialVerify

28、接口获得 * return 0 succeed; other fail1.17 验证原文HASH签名函数：int VerifyHashSign(char *pB64OriginHashData, char *pB64Cert, char *pB64SignedData, int iVerifyFlag, int hContext)* 验证原文数据HASH签名和证书有效性，用户为了保密/避免传输大数据需要， * 将原文进行HASH，然后调用该接口，避免了原文数据外送 * * param pB64OriginHashData 原文数据SHA-1 HASH后的B64编码 * param pB64Ce

29、rt 待验证的证书B64编码(中间没有回车换行) * param pB64SignedData 签名数据（b64编码） * param iVerifyFlag 0，不验证证书；1，验证黑名单；2 ，使用OCSP验证 * param hContext 连接句柄，通过InitialVerify接口获得 * return 0 succeed; other fail2 错误码说明错误码错误描述0函数操作成功4证书链不完整-1网络通信出现错误，或未知错误-32P7解密内存错误-109P7不支持的摘要类型-100P7密钥长度错误-111P7不支持的算法类型-112P7不支持的内容数据-1000输入参数错误-1001创建连接套接口失败-1002连接服务器失败-1003输入的数据超过限制-4001PKI SDK内部错误-4002PKI SDK内部错误-4003未知错误-4004不支持指定运算-