格尔SVSAPICActiveX接口说明.docx
《格尔SVSAPICActiveX接口说明.docx》由会员分享，可在线阅读，更多相关《格尔SVSAPICActiveX接口说明.docx（41页珍藏版）》请在冰豆网上搜索。
格尔SVSAPICActiveX接口说明
格尔签名验证服务器
客户端API_C/ActiveX
接口说明
V1.7
上海格尔软件股份有限公司
2006年8月
保密事宜：
本文档包含上海格尔软件股份有限公司的专有商业信息和保密信息。
接受方同意维护本文档所提供信息的保密性，承诺不对其进行复制，或向评估小组以外、非直接相关的人员公开此信息。
对于以下三种信息，接受方不向格尔公司承担保密责任：
1）接受方在接收该文档前，已经掌握的信息。
2）可以通过与接受方无关的其它渠道公开获得的信息。
3）可以从第三方，以无附加保密要求方式获得的信息。
目录
1接口说明6
1.1客户端初始化6
1.2客户端清理6
1.3验证数据签名6
1.4验证签名数据和签名证书7
1.5验证Attach方式的PKCS7数据签名8
1.6验证Attach方式的PKCS7数据签名并获取原文9
1.7证书验证9
1.8获取证书信息10
1.9Attach方式PKCS7数据签名11
1.10数据签名（普通签名数据）11
1.11对文件签名12
1.12对文件签名数据验证签名13
1.13对文件解密数字信封14
1.14Detach方式的PKCS#7签名14
1.15验证Detach方式的PKCS#7数据签名15
1.16验证签名（实时从LDAP下载证书并验证）15
1.17验证原文HASH签名16
2错误码说明17
3消息格式定义23
3.1消息格式总体描述23
3.2验证数据签名24
3.2.1客户端消息请求格式24
3.2.2服务器端验证签名成功的返回消息格式25
3.2.3服务器端验证签名失败的返回消息格式25
3.3验证签名数据和签名证书26
3.3.1客户端消息请求格式26
3.3.2服务器端验证签名成功的返回消息格式27
3.3.3服务器端验证签名失败的返回消息格式27
3.4验证PKCS#7签名数据28
3.4.1客户端消息请求格式28
3.4.2服务器端验证签名成功的返回消息格式28
3.4.3服务器端验证签名失败的返回消息格式29
3.5证书验证29
3.5.1客户端消息请求的格式29
3.5.2服务器端验证成功的返回消息格式30
3.5.3服务器端验证失败的返回消息格式30
3.6获取证书信息31
3.6.1客户端消息请求格式31
3.6.2服务器端解析证书成功的返回消息格式31
3.6.3服务器端解析证书失败的返回消息格式32
3.7数据签名（PKCS#7签名数据）32
3.7.1客户端消息请求格式32
3.7.2服务器端签名成功的返回消息格式33
3.7.3服务器端签名失败的返回消息格式33
3.8数据签名（普通签名数据）34
3.8.1客户端消息请求格式34
3.8.2服务器端签名成功的返回消息格式35
3.8.3服务器端签名失败的返回消息格式35
3.9对文件签名36
3.9.1客户端消息请求格式36
3.9.2服务器端签名成功的返回消息格式36
3.9.3服务器端签名失败的返回消息格式37
3.10对文件签名数据验证签名37
3.10.1客户端消息请求格式37
3.10.2服务器端验证签名成功的返回消息格式38
3.10.3服务器端验证签名失败的返回消息格式38
3.11对文件解密数字信封39
3.11.1客户端消息请求格式39
3.11.2服务器端操作成功的返回消息格式40
3.11.3服务器端操作失败的返回消息格式40
3.12验证签名（实时从LDAP下载证书并验证）41
3.12.1客户端消息请求格式41
3.12.2服务器端操作成功的返回消息格式41
3.12.3服务器端操作失败的返回消息格式42
3.13Detach方式PKCS7签名42
3.13.1客户端消息请求格式42
3.13.2服务器端操作成功的返回消息格式43
3.13.3服务器端操作失败的返回消息格式43
3.14Detach方式PKCS7签名验证44
3.14.1客户端消息请求格式44
3.14.2服务器端操作成功的返回消息格式45
3.14.3服务器端操作失败的返回消息格式45
1
接口说明
注意：
输出缓冲区的空间请在接口外部分配，请预留足够的存储空间，建议预留64K字节。
另外输入的原文数据长度有限制，不能大于40K字节大小。
注意：
以下接口输入和输出的原文都不是B64编码，接口内部会自动转换为B64编码，以便于传送。
1.1客户端初始化
函数：
intInitialVerify（char*szIP,unsignedshortnPort）
*初始化环境，这个函数需要在使用之前调用
*它所完成的工作是初始化全局环境，并且建立与服务器的连接
*注意:
此接口会返回连接句柄，这个句柄将用于后续的操作参数
*
*@paramszIP服务器的IP地址;
*@paramnPort服务器的端口号
*@return返回连接的连接句柄，用于后续操作;如果为负数，表示出错
1.2客户端清理
函数：
intFinalizeVerify（inthContext）
*释放资源
*
*@paramhContext连接句柄，通过InitialVerify接口获得
1.3验证数据签名
函数：
intVerifySign（intnSignType,
intnSignStytle,
unsignedchar*pOriginData,
intnOriginLength,
char*pB64Cert,
char*pB64SignedData,
inthContext）
*验证签名有效性
*@paramnSignType是进行数字签名前，原文摘要时所用的算法
-1//采用直接对原文数据进行签名的方式
0//MD2摘要算法
1//MD5摘要算法
2//SHA1摘要算法
*@paramnSignStytle备用参数，目前无效
*@parampOriginData原文数据
*@paramnOriginLength原文数据长度
*@parampB64Cert待验证的证书B64编码（中间没有回车换行）
*@parampB64SignedData签名数据（b64编码）
*@paramhContext连接句柄，通过InitialVerify接口获得
*@return0succeed;otherfail
错误码信息参见“错误码说明”部分。
以下同。
1.4验证签名数据和签名证书
函数：
intVerifyCertSign（intnSignType,
intnSignStytle,
unsignedchar*pOriginData,
intnOriginLength,
char*pB64Cert,
char*pB64SignedData,
intiFlagCRL,
inthContext）
*验证签名和证书的有效性
*
*@paramnSignType是数字签名前，原文摘要时所用的算法
-1//采用直接对原文数据进行签名的方式
0//MD2摘要算法
1//MD5摘要算法
2//SHA1摘要算法
*@paramnSignStytle备用参数，目前无效
*@parampOriginData原文数据
*@paramnOriginLength原文数据长度
*@parampB64Cert待验证的证书B64编码（中间没有回车换行）
*@parampB64SignedData签名数据（b64编码）
*@paramiFlagCRL验证证书有效性方式
0,不验证；
1，验证黑名单；
2，使用OCSP验证；
其他，只验证证书链
*@paramhContext连接句柄，通过InitialVerify接口获得
*@return0succeed;otherfail
1.5验证Attach方式的PKCS7数据签名
函数：
intPKCS7DataVerify（constchar*pPKCS7B64Data,
constunsignedchar*pOriginData,
unsignedintnOriginLen,
inthContext）
*Attach方式的PKCS#7数据签名验证
*
*@parampPKCS7B64DataP7数据B64编码（包含原文）
*@parampOriginData签名数据的原文（Attach方式P7签名验证请置为NULL）
*@paramnOriginLen原文的长度（Attach方式P7签名验证请置为0）
*@paramhContext连接句柄，通过InitialVerify接口获得
*@return0succeed;otherfail
1.6验证Attach方式的PKCS7数据签名并获取原文
函数：
intPKCS7DataVerifyGetOriData（constchar*pPKCS7B64Data,
constunsignedchar*pOriginData,
unsignedint*pnOriginLen,
inthContext）
*Attach方式的PKCS#7数据签名验证,并获取原文信息
*
*@parampPKCS7B64DataP7数据B64编码（包含原文）
*@parampOriginData返回的原文数据
*@parampnOriginLen返回的原文数据长度
*@paramhContext连接句柄，通过InitialVerify接口获得
*@return0succeed;otherfail
1.7证书验证
函数：
intVerifyCert（char*pB64Cert,
intiFlagOCSP,
intiFlagCRL,
inthContext）
*验证证书有效性
*
*@parampB64Cert待验证的证书B64编码（中间没有回车换行）
*@paramiFlagOCSP使用OCSP方式验证标志，1--使用OCSP方式验证，0--不使用OCSP
*@paramiFlagCRL是否验证黑名单标志，1--验证黑名单，0--不验证黑名单
*@paramhContext连接句柄，通过InitialVerify接口获得
*@return0//证书没有问题
1//证书尚未生效
2//证书已经过期
3//证书时间有问题
4//没有有效证书链
5//签名验证失败
6//上级证书未通过验证
7//已被废除
1.8获取证书信息
函数：
intGetCertInfo（char*pB64Cert,
intnType,
char*pItemName,
char*pCertInfo,
inthContext）
*取证书信息
*
*@parampB64Cert待验证的证书B64编码（中间没有回车换行）
*@paramnType证书项的类型
0//取证书用户信息基本项
1//取证书的发布者信息项
2//取证书扩展项
*@parampItemName所要取得证书项名称，如"CN"等
*@parampCertInfo所要取得证书项的值
*@paramhContext连接句柄，通过InitialVerify接口获得
*@return0succeed;otherfail
1.9Attach方式PKCS7数据签名
函数：
intPKCS7DataSign（constunsignedchar*pOriginData,
unsignedintnOriginDataLen,
char*pSignedData,
inthContext）
*Attach方式的PKCS#7数据签名
*
*@parampOriginData待签名原文,数据长度不能超过40K
*@paramnOriginDataLen原文长度
*@parampSignedData签名后的P7数据B64编码（签名后的数据包含原文）
*@paramhContext连接句柄，通过InitialVerify接口获得
*@return0succeed;otherfail
1.10数据签名（普通签名数据）
函数：
intSignData（intnSignType,
constunsignedchar*pOriginData,
unsignedintnOriginDataLen,
char*pSignedData,
char*pB64Cert,
inthContext）
*普通格式的数据签名（不使用PKCS7格式封装签名结果）
*
*@paramnSignType是数字签名前，原文摘要时所用的算法
-1//采用直接对原文数据进行签名的方式
0//MD2摘要算法
1//MD5摘要算法
2//SHA1摘要算法
*@parampOriginData待签名原文
*@paramnOriginDataLen原文长度
*@parampSignedData签名后的数据
*@parampB64CertB64编码的签名证书
*@paramhContext连接句柄，通过InitialVerify接口获得
*@return0succeed;otherfail
1.11对文件签名
函数：
intSignFile（intnSignType,
char*strFile,
intiSignAlgo,
char*strSignedData,
char*pB64Cert,
inthContext）
*对文件进行签名（不使用PKCS7格式封装签名结果）
*
*@paramnSignType是数字签名前，原文摘要时所用的算法
-1//采用直接对原文数据进行签名的方式
0//SHA1摘要算法
1//MD5摘要算法
*@paramstrFile待签名的文件名
*@paramiSignALgo签名算法,作为扩展使用，暂时无效
*@paramstrSignedData签名后的数据
*@parampB64CertB64编码的签名证书
*@paramhContext连接句柄，通过InitialVerify接口获得
*@return0succeed;otherfail
1.12对文件签名数据验证签名
函数：
intVerifyFile（intnSignType,
intiSignAlgo,
char*strFile,
char*pB64Cert,
char*pB64SignedData,
intiVerifyFlag,
inthContext）
*对文件签名进行验证（签名结果不是PKCS7格式封装）
*
*@paramnSignType是数字签名前，原文摘要时所用的算法
-1//采用直接对原文数据进行签名的方式
0//SHA1摘要算法
1//MD5摘要算法
*@paramiSignALgo签名算法,作为扩展使用，暂时无效
*@paramstrFile待验证的文件名全路径
*@parampB64Cert用户证书数据（b64编码）
*@parampB64SignedData签名数据
*@paramiVerifyFlag验证证书有效性方法（暂时无效，仅作扩展使用，不验证证书）
0不验证证书有效性
1CRL方式验证证书有效性
2OCSP方式验证证书有效性
其他只验证证书链
*@paramhContext连接句柄，通过InitialVerify接口获得
*@return0succeed;otherfail
1.13对文件解密数字信封
函数：
intDecodeEnvelopeFile（char*strSrcFile,
char*strDstFile,
inthContext）
*使用服务器私钥解密数字信封
*
*@paramstrSrcFile待解密的文件的文件名，如果不在当前目录下，需要带路径名
*@paramstrDstFile解密后文件的文件名，如果不在当前目录下，需要带路径名
*@paramhContext连接句柄，通过InitialVerify接口获得
*@return0succeed;otherfail
1.14Detach方式的PKCS#7签名
函数：
intPKCS7DetachDataSign（constunsignedchar*pOriginData,
unsignedintnOriginDataLen,
char*pSignedData,
inthContext）
*Detach方式的PKCS#7数据签名
*
*@parampOriginData待签名原文,原文长度没有限制
*@paramnOriginLen原文的长度
*@parampSignedData签名后的P7格式数据,不包含原文
*@paramhContext连接句柄，通过InitialVerify接口获得
*@return0succeed;otherfail
1.15验证Detach方式的PKCS#7数据签名
函数：
intPKCS7DetachDataVerify（constchar*pPKCS7B64Data,
constunsignedchar*pOriginData,
unsignedintnOriginLen,
inthContext）
*Detach方式的PKCS#7数据签名验证
*
*@parampPKCS7B64DataP7数据B64编码（不包含原文）
*@parampOriginData签名数据的原文
*@paramnOriginLen原文的长度
*@paramhContext连接句柄，通过InitialVerify接口获得
*@return0succeed;otherfail
1.16验证签名（实时从LDAP下载证书并验证）
函数：
intVerifyLdapCertSign（intnSignType,
intiSignAlgo,
unsignedchar*strOriginData,
intiOriginLength,
char*strFilter,
char*strB64SignedData,
intiVerifyFlag,
inthContext）
*验证签名和证书的有效性（实时从LDAP下载证书并验证其有效性）
*
*@paramnSignType是数字签名前，原文摘要时所用的算法
-1//采用直接对原文数据进行签名的方式
0//SHA1摘要算法
1//MD5摘要算法
*@paramiSignAlgo0SHA1;1MD5（此参数当前已经失效，只支持SHA1）
*@paramstrOriginData原文数据
*@paramiOriginLength原文数据长度
*@paramstrFilter用户证书的证书序列号
*@paramstrB64SignedData签名数据（b64编码）
*@paramiVerifyFlag是否验证证书状态
0不验证证书状态
1验证证书状态
*@paramhContext连接句柄，通过InitialVerify接口获得
*@return0succeed;otherfail
1.17验证原文HASH签名
函数：
intVerifyHashSign（char*pB64OriginHashData,
char*pB64Cert,
char*pB64SignedData,
intiVerifyFlag,
inthContext）
*验证原文数据HASH签名和证书有效性，用户为了保密/避免传输大数据需要，
*将原文进行HASH，然后调用该接口，避免了原文数据外送
*
*@parampB64OriginHashData原文数据SHA-1HASH后的B64编码
*@parampB64Cert待验证的证书B64编码（中间没有回车换行）
*@parampB64SignedData签名数据（b64编码）
*@paramiVerifyFlag0，不验证证书；1，验证黑名单；2，使用OCSP验证
*@paramhContext连接句柄，通过InitialVerify接口获得
*@return0succeed;otherfail
2错误码说明
错误码
错误描述
0
函数操作成功
4
证书链不完整
-1
网络通信出现错误，或未知错误
-32
P7解密内存错误
-109
P7不支持的摘要类型
-100
P7密钥长度错误
-111
P7不支持的算法类型
-112
P7不支持的内容数据
-1000
输入参数错误
-1001
创建连接套接口失败
-1002
连接服务器失败
-1003
输入的数据超过限制
-4001
PKISDK内部错误
-4002
PKISDK内部错误
-4003
未知错误
-4004
不支持指定运算
-
升级会员 