吉大正元数字签名服务器程序员手册（COM版VCTK接口）(共58页).doc

《吉大正元数字签名服务器程序员手册（COM版VCTK接口）(共58页).doc》由会员分享，可在线阅读，更多相关《吉大正元数字签名服务器程序员手册（COM版VCTK接口）(共58页).doc（58页珍藏版）》请在得力文库 - 分享文档赚钱的网站上搜索。

1、精选优质文档-倾情为你奉上吉大正元数字签名服务器程序员手册（VCTK接口 COM版） V2.0.24 长 春 吉 大 正 元 信 息 技 术 股 份 有 限 公 司 Jilin University Information Technologies Co., Ltd.目录专心-专注-专业1. 引言1.1. 概述数字签名服务器(客户端com版)是一套基于PKCS7标准的数字签名接口，提供对原文、文件、表单的签名和验证等功能。完成以下功能接口：n 带原文签名与验签名n 无原文签名与验签名n 制作和解密数字信封n 制作和解密带签名的数字信封n 可以对一个或是多个原文或文件进行操作n Base64编码

2、和解码n 对数据制作摘要（hash）n 获取证书信息n 获取和设置原文、文件、表单信息1.2. 开发平台及编程语言n 开发平台Windows xp + sp2n 编程语言Cn 开发工具VC2005 + sp11.3. 名词解释1.3.1. CRL证书撤销列表，简称CRL，一个已标识的列表，它指定了一套认证中心确认为无效的证书。1.3.2. PFX文件PFX文件为标准个人私钥文件，内部使用口令保护封装有个人私钥及对应的公钥证书。一般情况下，该文件中的用户私钥应由用户口令加密存放。1.3.3. DNDistinguish Name，证书主题名称。1.3.4. Digital Certificate

3、（数字证书）Digital Certificate，是由国家认可的，具有权威性、可信性、公正性的第三方证书认证机构进行数字签名的一个可信的数字化文件。数字证书包含公开密钥拥有者信息以及公开密钥的文件。2. 接口说明2.1. SetCert功能简介： 设置签名、加密、解密或验签名证书原型：HRESULT SetCert(in BSTR bstrCertType, in BSTR bstrDN, in BSTR bstrSN, in BSTR bstrEmail, in BSTR bstrDNIssuer, in BSTR bstrCertBase64, out, retval long* pRe

4、tVal);参数：输入：bstrCertType- 证书的类型(包括签名证书，加密证书，解密证书，验签名证书) bstrDN - 证书主题(Distinguished Name) bstrSN - 证书序列号(Serial Number)bstrEmail - 证书主题中的Email项bstrDNIssuer - 证书颁发者主题(Distinguished Name of Issuer)bstrCertBase64 - 证书的BASE64编码输出：pRetVal- 操作错误码返回值：类型为HRESULT 0表示成功，1表示失败备注COM客户端版本bstrDN、bstrSN、bstrEmail和

5、bstrCertBase64都为空时，将弹出证书选择框让用户选择证书。bstrDN、bstrSN、bstrEmail三个条件可以与bstrDNIssuer组合输入。该接口在调用签名，数字信封接口前调用。证书类型输入值（字符串）签名证书SC验签名证书“VS”加密证书“EC”解密证书“DC”2.2. SetCertChooseType功能简介： 仅供COM客户端版本调用，指定证书选择的方式原型：HRESULT SetCertChooseType( in long nType, out, retval long* pRetVal);参数：输入：nType - 证书选择的类型（0 表示只有一张证书时也

6、弹出证书选择框，1 表示只有一张证时将不弹出证书选择框，默认值为0）输出：pRetVal- 操作错误码返回值：类型为HRESULT 0表示成功，1表示失败备注COM客户端版本才会使用，当客户的证书存储单元中只有一张符合条件的证书，是否还弹出证书选择框提示用户选择证书。默认情况是弹出证书选择框，用户应用中如不调用该接口将按照默认情况处理，如果有些应用特殊情况希望在证书存储单元中只有一张证书时不弹出证书选择框，可以调用该接口简化操作。在做签名，加密之前调用该接口，如果证书存储单元中只有一张证书可以作为签名证书时，将不弹出证书选择框，直接将该证书作为签名证书进行操作，如果有多张证书将弹出证书选择框，

7、供用户选择。2.3. GetCertInfo功能简介：获得相应证书的信息原型：HRESULT GetCertInfo( in BSTR bstrCertType, in long lInfoType, in BSTR bstrOID, out, retval BSTR* pRetCerInfo)参数：输入：bstrCertType - 证书的类型(包括签名证书，加密证书，解密证书，验签名证书)lInfoType - 证书信息的类型(证书主题，序列号，颁发者主题，有效期起始日期，有效期终止日期，版本号，主题中的Email，证书扩展)bstrOID - 证书扩展的标识，如果lInfoType等于证

8、书扩展，该输入项不能为空输出：pRetCerInfo -相应的证书信息返回值：类型为HRESULT 0表示成功，1表示失败备注该接口在做完验签名或是解密数字信封后使用，验签名完成后调用该接口传入“VS”，获得验签名证书信息，解密数字信封完成后传入“DC”，获得解密证书信息。证书类型和证书信息类型分别为下面所示的值。证书类型输入值（字符串）签名证书SC验签名证书“VS”加密证书“EC”解密证书“DC”信息类型输入值（long）返回值描述证书主题0例如：CN=dsign, O=JIT, C=CN.当bstrOID设置成”1”时,返回的证书主题是反序的(也就是C=CN, O=JIT, CN=dsig

9、n)颁发者主题1例如：CN=JIT CA, O=JIT, C=CN序列号2例如：2f8c878efe534bc4版本3例如：3电子邮件地址4例如：dsign有效期起始时间5例如：2004年12月23日 18:09:31有效期终止时间6例如：2005年12月23日 18:09:31扩展域7例如：输入的OID为”1.2.86.11.7.4”，需要取国标中规定的企业工商注册号扩展项，返回值为：2f8c87公钥证书内容8是一个base64编码的X509证书用户名称9例如:jit省份10城市11一个证书的主题中可能出现多个城市的信息.获取此信息时需要设置参数bstrOID.当bstrOID设置成”0”时

10、,返回值是证书的主题中包含的城市的信息的个数,当bstrOID设置为大于0且小于等于证书主题中城市信息的个数时,返回第bstrOID个城市信息组织名称12机构名称13一个证书的主题中可能出现多个机构名称.获取此信息时需要设置参数bstrOID.当bstrOID设置成”0”时,返回值是证书的主题中包含的机构名称的信息的个数,当bstrOID设置为大于0且小于等于证书主题中机构名称信息的个数时,返回第bstrOID个机构名称信息国家14例如:CN2.4. SetAlgorithm功能简介：设置算法原型：HRESULT SetAlgorithm( in BSTR bstrSignAlg, in BS

11、TR bstrEncAlg, out, retval long* pRetVal)参数：输入：bstrSignType 签名算法类型 bstrEncType 加密算法类型输出：pRetVal- 操作错误码返回值：类型为HRESULT 0表示成功，1表示失败备注该接口在签名，加密之前使用，若用户不调用该接口或不指定算法将采用默认算法，签名的默认算法为“SHA1RSA”，加密的默认算法为“DES3CBC”。支持的签名算法类型： 算法类型输入值（字符串）描述SHA1RSA“SHA1RSA”文摘算法采用SHA1，非对称加密算法采用RSA，签名时默认采用该算法MD5RSA“MD5RSA”文摘算法采用MD

12、5，非对称加密算法采用RSAMD2RSA“MD2RSA”文摘算法采用MD2，非对称加密算法采用RSA支持的加密算法类型： 算法类型输入值（字符串）描述DES3CBC“DES3CBC”带向量的DES3对称加密算法，加密时默认采用该算法DESCBC“DESCBC”带向量的DES对称加密算法2.5. AttachSign功能简介：Attach签名原型1：HRESULT AttachSign(in BSTR bstrDN, in unsigned char* pszSrcData, in long lSrcDataLen, out, retval BSTR* pbstrSignedData)参数：输入

13、：bstrDN - 指定证书的主题bstrSrcData- 原文数据lSrcDataLen- 原文数据长度输出： pbstrSignedData- 签名结果（Base64编码格式）返回值：类型为HRESULT 0表示成功，1表示失败原型2：HRESULT AttachSignEx( in BSTR bstrDN, in BSTR bstrFileName, in BSTR bstrFileNameOut, out, retval BSTR* pbstrSignedData)参数：输入：bstrDN - 指定证书的主题bstrFileName 待签名文件的文件名bstrFileNameOut -

14、 签名结果输出的文件名输出： pbstrSignedData- 签名结果（Base64编码格式）返回值：类型为HRESULT 0表示成功，1表示失败原型3：HRESULT AttachSignStr( in BSTR bstrDN, in BSTR bstrSrc, out, retval BSTR* pbstrSignedData)参数：输入：bstrDN-指定证书的主题bstrSrc- 签名数据输出：pbstrSignedData -签名数据结果返回值：类型为HRESULT 0表示成功，1表示失败备注对文件的签名，如果指定bstrFileNameOut，结果记录在bstrFileNameO

15、ut参数对应的文件里，如果不指定，设置该参数为NULL，结果直接从返回值返回。如果用户先调用SetCert接口设置了签名证书，bstrDN输入项可以为空，如果bsrDN不为空，将按照输入的bstrDN查找证书2.6. VerifyAttachedSign功能简介：Attach验签名，即验证带原文的数字签名原型1：HRESULT VerifyAttachedSign( in BSTR bstrSignedData, out, retval long* pRetVal)参数：输入：bstrSignedData -签名结果输出：pRetVal- 操作错误码返回值：类型为HRESULT 0表示成功，1

16、表示失败原型2：HRESULT VerifyAttachedSignEx( in BSTR bstrFileNameAttached, out, retval long* pRetVal)参数：输入：bstrFileNameAttached - 存放签名结果的文件名（带路径）输出：pRetVal- 操作错误码返回值：类型为HRESULT 0表示成功，1表示失败2.7. DetachSign功能简介：Detach签名原型1：HRESULT DetachSign( in BSTR bstrDN, in unsigned char* pszSrcData, in long lSrcDataLen,

17、out, retval BSTR* pbstrSignedData)参数：输入：bstrDN -指定证书的主题pszSrcData - 原文lSrcDataLen- 原文长度输出： pbstrSignedData-签名结果（Base64编码格式）返回值：类型为HRESULT 0表示成功，1表示失败原型2：HRESULT DetachSignEx( in BSTR bstrDN, in BSTR bstrFileName, in BSTR bstrFileNameOut, out, retval BSTR* pbstrSignedData)参数：输入：bstrDN - 指定证书的主题bstrFi

18、leName - 文件名bstrFileNameOut - 签名结果存储文件输出： PbstrSignedData-签名结果（Base64编码格式）返回值：类型为HRESULT 0表示成功，1表示失败原型3：HRESULT DetachSignStr( in BSTR bstrDN, in BSTR bstrSrc, out, retval BSTR* pbstrSignedData)参数：输入：bstrDN- 指定证书的主题bstrSrc- 原文输出： pbstrSignedData- 签名结果（Base64编码格式）返回值：类型为HRESULT 0表示成功，1表示失败使用条件（特殊情况写）

19、对文件的签名，如果指定bstrFileNameOut，结果记录在bstrFileNameOut参数对应的文件里，如果不指定，设置该参数为NULL，结果直接从返回值返回。如果用户先调用SetCert接口设置了签名证书，bstrDN输入项可以为空，如果bsrDN不为空，将按照输入的bstrDN查找证书2.8. VerifyDetachedSign功能简介：Detach验签名原型1：HRESULT VerifyDetachedSign( in BSTR bstrSignedData, in unsigned char* pszSrcData, in long lSrcDataLen, out, re

20、tval long* pRetVal)参数：输入：bstrSignedData - Detached签名结果pszSrcData 原文lSrcDataLen- 原文长度输出：pRetVal- 操作错误码返回值：类型为HRESULT 0表示成功，1表示失败原型2：HRESULT VerifyDetachedSignEx( in BSTR bstrSignedData, in BSTR bstrFileNameDetached, in BSTR bstrFileName, out, retval long* pRetVal)参数：输入：bstrSignedData - 签名结果bstrFileNa

21、meDetached - 签名结果存储文件bstrFileName Detach验签名时用到的文件输出： pRetVal- 操作错误码返回值：类型为HRESULT 0表示成功，1表示失败原型3：HRESULT VerifyDetachedSignStr( in BSTR bstrSignedData, in BSTR bstrSrc, out, retval long* pRetVal)参数：输入：bstrSignedData - Detached签名结果bstrSrc 原文输出：pRetVal- 操作错误码返回值：类型为HRESULT 0表示成功，1表示失败备注：bstrSignedData

22、和bstrFileNameDetached只能输入一项，但不能同时为空。当对文件detach签名的结果直接返回时，bstrSignedData输入不为空，bstrFileNameDetached输入为空；当对文件的detach签名的结果存放在文件中时，在验签的时候指定bstrSignedData为空，bstrFileNameDetached不为空。2.9. EncryptEnvelop功能简介：制作数字信封原型1：HRESULT EncryptEnvelop( in BSTR bstrDN, in unsigned char* pszSrcData, in long lSrcDataLen,

23、out, retval BSTR* pRetValue)参数：输入：bstrDN 指定证书的主题pszSrcData 原文lSrcDataLen- 原文长度输出： pRetVal-数字信封（Base64编码格式）返回值：类型为HRESULT 0表示成功，1表示失败原型2：HRESULT EncryptEnvelopEx( in BSTR bstrDN, in BSTR bstrFileName, in BSTR bstrFileNameOut, out, retval BSTR* pRetValue)参数：输入：bstrDN - 指定证书的主题bstrFileName- 文件名称（包含路径）b

24、strFileNameOut - 加密结果存储文件名（包含路径）输出： pRetValue-数字信封（Base64编码格式）返回值：类型为HRESULT 0表示成功，1表示失败原型3：HRESULT EncryptEnvelopStr( in BSTR bstrDN, in BSTR bstrSrc, out, retval BSTR* pRetValue)参数：输入：bstrDN 指定证书的主题bstrSrc 原文输出： pRetVal- 数字信封（Base64编码格式）返回值：类型为HRESULT 0表示成功，1表示失败使用条件（特殊情况写）对文件的签名，如果指定bstrFileNameO

25、ut，结果记录在bstrFileNameOut参数对应的文件里，如果不指定，设置该参数为NULL，结果直接从返回值返回。如果用户先调用SetCert接口设置了加密证书，bstrDN输入项可以为空，如果bsrDN不为空，将按照输入的bstrDN查找证书。2.10. DecryptEnvelop功能简介：解密数字信封原型1：HRESULT DecryptEnvelop( in BSTR bstrEnvelop, out, retval long* pRetVal)参数：输入：bstrEnvelop - 数字信封输出：pRetVal- 操作错误码返回值：类型为HRESULT 0表示成功，1表示失败原

26、型2：HRESULT DecryptEnvelopEx( in BSTR bstrFileNameDetached, out, retval long* pRetVal)参数：输入：bstrFileNameDetached - 存放数字信封结果的文件名输出：pRetVal- 操作错误码返回值：类型为HRESULT 0表示成功，1表示失败2.11. CreateSignedEnvelop功能简介：制作带签名的数字信封原型1：HRESULT CreateSignedEnvelop( in BSTR bstrSignCertDN, in BSTR bstrEncCertDN, in unsigned

27、 char* pszSrcData, in long lSrcDataLen, out, retval BSTR* pRetValue)参数：输入：bstrSignCertDN - 签名证书的主题bstrEncCertDN - 加密证书的主题pszSrcData- 原文lSrcDataLen- 原文长度输出： pRetValue- 带签名的数字信封（Base64编码格式）返回值：类型为HRESULT 0表示成功，1表示失败原型2：HRESULT CreateSignedEnvelopEx( in BSTR bstrSignCertDN, in BSTR bstrEncCertDN, in BS

28、TR bstrFileName, in BSTR bstrFileNameOut, out, retval BSTR* pRetValue)参数：输入：bstrSignCertDN - 签名证书的主题bstrEncCertDN - 加密证书的主题bstrFileName - 需要做操作的文件名称bstrFileNameOut - 操作结果输出的文件名称（带路径）输出： pRetValue- 带签名的数字信封（Base64编码格式）返回值：类型为HRESULT 0表示成功，1表示失败原型3：HRESULT CreateSignedEnvelopStr( in BSTR bstrSignCertD

29、N, in BSTR bstrEncCertDN, in BSTR bstrSrc, out, retval BSTR* pRetValue)参数：输入：bstrSignCertDN - 签名证书的主题bstrEncCertDN - 加密证书的主题bstrSrc - 原文输出： pRetValue- 带签名的数字信封（Base64编码格式）返回值：类型为HRESULT 0表示成功，1表示失败使用条件（特殊情况写）对文件的签名，如果指定bstrFileNameOut，结果记录在bstrFileNameOut参数对应的文件里，如果不指定，设置该参数为NULL，结果直接从返回值返回。如果用户先调用S

30、etCert接口设置了签名和加密证书，bstrSignCertDN或bstrEncCertDN输入项可以为空，如果bstrSignCertDN或bstrEncCertDN不为空，将按照输入的bstrSignCertDN或bstrEncCertDN查找证书。2.12. VerifySignedEnvelop功能简介：解密并验证带签名的数字信封原型1：HRESULT VerifySignedEnvelop( in BSTR bstrEnvelop, out, retval long* pRetVal)参数：输入：bstrEnvelop - 数字信封 输出：pRetVal- 操作错误码返回值：类型为

31、HRESULT 0表示成功，1表示失败原型2：HRESULT VerifySignedEnvelopEx( in BSTR bstrEvpFile, out, retval long* pRetVal)参数：输入：bstrEvpFile - 存放数字信封结果的文件名输出：pRetVal- 操作错误码返回值：类型为HRESULT 0表示成功，1表示失败2.13. GetData功能简介：获得原文原型1：HRESULT GetDataEx( out unsigned char* pszSrcData, in, out long* plSrcDataLen, out, retval long* pR

32、etVal)参数：pszSrcData- 取得数据缓冲区plSrcDataLen-取得数据缓冲区长度pRetVal- 操作错误码返回值：类型为HRESULT 0表示成功，1表示失败原型2：HRESULT GetData(out, retval BSTR* bstrBase64Data)参数：bstrBase64Data- 获得原文数据返回值：类型为HRESULT 0表示成功，1表示失败2.14. GetFile功能简介：获得文件原型：HRESULT GetFile( in BSTR bstrFileSavePath, out, retval BSTR* bstrFileName)参数：输入：b

33、strFileSavePath - 要存在本地的文件路径 输出： bstrFileName- 存储的文件名返回值：类型为HRESULT 0表示成功，1表示失败2.15. GetBase64Encode功能简介：Base64编码原型：HRESULT GetBase64Encode( in unsigned char* pszSrcData, in long lSrcDataLen, out, retval BSTR* pbstrBase64Data)参数：输入：bstrSrcData- 需做编码的原文lSrcDataLen-需做编码的原文长度输出：pbstrBase64Data -类型为BSTR

34、，原文的base64编码返回值：类型为HRESULT 0表示成功，1表示失败2.16. GetBase64Decode功能简介：Base64解码原型：HRESULT GetBase64Decode( in BSTR bstrBase64Data, out unsigned char* pszSrcData, in, out long* pSrcDataLen, out, retval long* pRetVal)参数：输入：bstrBase64Data - base64编码数据输出：pszSrcData- 解码数据缓存区pSrcDataLen-解码数据缓存区长度pRetVal- 操作错误码返回

35、值：类型为HRESULT 0表示成功，1表示失败2.17. GetBase64HashEnCode功能：对一段原文做HASH原型：public BSTR getBase64HashEnCode(BSTRbstrSrcData,)参数：输入：bstrSrcData - 原文输出：pRetVal- 操作错误码返回值：原文HASH值的base64编码备注：默认的HASH算法是SHA12.18. GetErrorCode功能简介：获得上次调用的错误码原型：long GetErrorCode()参数：输入：无输出：pRetVal- 操作错误码返回值：错误码2.19. GetErrorMessage功能简介：获得上次调用的出错信息描述原型：HRESULT GetErrorMessage( in long lErrorCode, out, retval BSTR* pErrorMessage)参数：输入：lErrorCode- 错误码号码输出：pErrorMessage - 类型为BSTR的错误描述返回值：类型为HRESULT 0表示成功，1表示失败2.20. SetCSP功能简介设置Cryptographic Service