吉大正元数字签名服务器程序员手册（COM版VCTK接口）

吉大正元数字签名服务器 程序员手册 （VCTK 接口 COM 版） V2.0.24V2.0.24 长长 春春 吉吉 大大 正正 元元 信信 息息 技技 术术 股股 份份 有有 限限 公公 司司 JilinJilin UniversityUniversity InformationInformation TechnologiesTechnologies Co.,Co., Ltd.Ltd. 目录目录 1.引言引言.1 1.1.概述.1 1.2.开发平台及编程语言.1 1.3.名词解释.1 1.3.1.CRL.1 1.3.2.PFX文件.1 1.3.3.DN .1 1.3.4.Digital Certificate（数字证书）.1 2.接口说明接口说明.1 2.1.SETCERT.1 2.2.SETCERTCHOOSETYPE.2 2.3.GETCERTINFO.3 2.4.SETALGORITHM.4 2.5.ATTACHSIGN.5 2.6.VERIFYATTACHEDSIGN.5 2.7.DETACHSIGN.6 2.8.VERIFYDETACHEDSIGN.6 2.9.ENCRYPTENVELOP.7 2.10.DECRYPTENVELOP.8 2.11.CREATESIGNEDENVELOP.8 2.12.VERIFYSIGNEDENVELOP.9 2.13.GETDATA.10 2.14.ADDDATA.10 2.15.GETFILE.10 2.16.ADDFILE.11 2.17.GETBASE64ENCODE.11 2.18.GETBASE64DECODE.11 2.19.GETBASE64HASHENCODE.12 2.20.GETERRORCODE.12 2.21.GETERRORMESSAGE.12 2.22.SETCSP.12 2.23.SETPIN.13 2.24.GETCERTLIST.13 3.常量定义常量定义.14 3.1.证书类型.14 3.2.HASH 签名算法 .14 3.3.加密算法.14 3.4.证书信息.14 4.接口使用流程说明接口使用流程说明.15 4.1.对原文或表单的操作.15 4.1.1.带原文（Attach）签名.15 4.1.2.带原文（Attached）验签名.15 4.1.3.不带原文（Detach）签名.15 4.1.4.不带原文（Detached）验签名.15 4.1.5.制作数字信封.15 4.1.6.解密数字信封.15 4.1.7.制作带签名的数字信封.16 4.1.8.解密带签名的数字信封.16 4.2.对文件的操作.16 4.2.1.带原文（Attach）签名.16 4.2.2.带原文（Attached）验签名.16 4.2.3.不带原文（Detach）签名.16 4.2.4.不带原文（Detached）验签名.16 4.2.5.制作数字信封.17 4.2.6.解密数字信封.17 4.2.7.制作带签名的数字信封.17 4.2.8.解密带签名的数字信封.17 4.3.编码操作.17 4.3.1.Base64编码.17 4.3.2.Base64解码.17 4.3.3.HASH.17 5.HTML 调用调用 COM CLIENT 接口示例接口示例 .17 5.1.DEMO文件对应表 .18 5.2.对原文或表单的接口示例.18 5.2.1.带原文（Attach）签名.18 5.2.2.带原文（Attached）验签名.19 5.2.3.不带原文（Detach）签名.19 5.2.4.不带原文（Detached）验签名.20 5.2.5.制作数字信封.21 5.2.6.解密数字信封.22 5.2.7.制作带签名的数字信封.23 5.2.8.解密带签名的数字信封.24 5.3.对文件的接口示例.26 5.3.1.带原文（Attach）签名.26 5.3.2.带原文（Attached）验签名.27 5.3.3.不带原文（Detach）签名.29 5.3.4.不带原文（Detached）验签名.30 5.3.5.制作数字信封.31 5.3.6.解密数字信封.33 5.3.7.制作带签名的数字信封.35 5.3.8.解密带签名的数字信封.36 5.4.其他示例.38 5.4.1.Base64编码.38 5.4.2.Base64解码.38 5.4.3.HASH.39 5.4.4.SetPIN.39 6.错误代码与描述错误代码与描述.39 7.证书安装与使用证书安装与使用.40 7.1.PFX 证书安装.40 7.2.加密证书安装.40 7.3.根证书安装.41 7.4.测试证书说明.42 7.4.1.pfx_cert.42 7.4.2.enc_cert.42 7.4.3.root_cert.42 7.4.4.crl .43 7.5.证书主题获取.43 吉大正元数字签名服务器(com版) 程序员手册 吉大正元信息技术股份有限公司 1 1.1. 引言引言 1.1. 概述概述 数字签名服务器(客户端 com 版)是一套基于 PKCS7 标准的数字签名接口，提供对原文、文件、 表单的签名和验证等功能。完成以下功能接口： 带原文签名与验签名 无原文签名与验签名 制作和解密数字信封 制作和解密带签名的数字信封 可以对一个或是多个原文或文件进行操作 Base64 编码和解码 对数据制作摘要（hash） 获取证书信息 获取和设置原文、文件、表单信息 1.2. 开发平台及编程语言开发平台及编程语言 开发平台 Windows xp + sp2 编程语言 C 开发工具 VC2005 + sp1 1.3. 名词解释名词解释 1.3.1.1.3.1. CRLCRL 证书撤销列表，简称 CRL，一个已标识的列表，它指定了一套认证中心确认为无效的证书。 1.3.2.1.3.2. PFXPFX 文件文件 PFX 文件为标准个人私钥文件，内部使用口令保护封装有个人私钥及对应的公钥证书。一般情 况下，该文件中的用户私钥应由用户口令加密存放。 1.3.3.1.3.3. DNDN Distinguish Name，证书主题名称。 1.3.4.1.3.4. DigitalDigital CertificateCertificate（数字证书）（数字证书） Digital Certificate，是由国家认可的，具有权威性、可信性、公正性的第三方证书认证机构进行 数字签名的一个可信的数字化文件。数字证书包含公开密钥拥有者信息以及公开密钥的文件。 2.2. 接口说明接口说明 2.1. SetCert 功能简介功能简介： 设置签名、加密、解密或验签名证书 吉大正元数字签名服务器(com版) 程序员手册 吉大正元信息技术股份有限公司 2 原型原型： HRESULT SetCert( in BSTR bstrCertType, in BSTR bstrDN, in BSTR bstrSN, in BSTR bstrEmail, in BSTR bstrDNIssuer, in BSTR bstrCertBase64, out, retval long* pRetVal); 参数参数： 输入：bstrCertType- 证书的类型(包括签名证书，加密证书，解密证书，验签名证书) bstrDN - 证书主题(Distinguished Name) bstrSN - 证书序列号(Serial Number) bstrEmail - 证书主题中的 Email 项 bstrDNIssuer - 证书颁发者主题(Distinguished Name of Issuer) bstrCertBase64 - 证书的 BASE64 编码 输出：pRetVal- 操作错误码 返回值返回值： 类型为 HRESULT 0 表示成功，1 表示失败 备注备注 COM 客户端版本 bstrDN、bstrSN、bstrEmail 和 bstrCertBase64 都为空时，将弹出证书选择框让用户 选择证书。 bstrDN、bstrSN、bstrEmail 三个条件可以与 bstrDNIssuer 组合输入。 该接口在调用签名，数字信封接口前调用。 证书类型证书类型输入值（字符串）输入值（字符串） 签名证书SC 验签名证书“VS” 加密证书“EC” 解密证书“DC” 2.2. SetCertChooseType 功能简介功能简介： 仅供 COM 客户端版本调用，指定证书选择的方式 原型原型： HRESULT SetCertChooseType( in long nType, out, retval long* pRetVal); 参数参数： 输入：nType - 证书选择的类型（0 表示只有一张证书时也弹出证书选择框，1 表示只有一张证 时将不弹出证书选择框，默认值为 0） 输出：pRetVal- 操作错误码 返回值返回值： 类型为 HRESULT 0 表示成功，1 表示失败 备注备注 吉大正元数字签名服务器(com版) 程序员手册 吉大正元信息技术股份有限公司 3 COM客户端版本才会使用，当客户的证书存储单元中只有一张符合条件的证书，是否还弹出证书选 择框提示用户选择证书。默认情况是弹出证书选择框，用户应用中如不调用该接口将按照默认情况处理， 如果有些应用特殊情况希望在证书存储单元中只有一张证书时不弹出证书选择框，可以调用该接口简化 操作。 在做签名，加密之前调用该接口，如果证书存储单元中只有一张证书可以作为签名证书时，将不弹 出证书选择框，直接将该证书作为签名证书进行操作，如果有多张证书将弹出证书选择框，供用户选择。 2.3. GetCertInfo 功能简介功能简介： 获得相应证书的信息 原型原型： HRESULT GetCertInfo( in BSTR bstrCertType, in long lInfoType, in BSTR bstrOID, out, retval BSTR* pRetCerInfo) 参数参数： 输入：bstrCertType - 证书的类型(包括签名证书，加密证书，解密证书，验签名证书) lInfoType - 证书信息的类型(证书主题，序列号，颁发者主题，有效期起始日期，有效期 终止日期，版本号，主题中的 Email，证书扩展) bstrOID - 证书扩展的标识，如果 lInfoType 等于证书扩展，该输入项不能为空 输出：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=dsign) 颁发者主题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 吉大正元数字签名服务器(com版) 程序员手册 吉大正元信息技术股份有限公司 4 扩展域7例如：输入的 OID 为”1.2.86.11.7.4”，需要取国标中规 定的企业工商注册号扩展项，返回值为：2f8c87 公钥证书内容8是一个 base64 编码的 X509 证书 用户名称9例如:jit 省份10 城市11一个证书的主题中可能出现多个城市的信息.获取此信 息时需要设置参数 bstrOID.当 bstrOID 设置成”0”时,返 回值是证书的主题中包含的城市的信息的个数,当 bstrOID 设置为大于 0 且小于等于证书主题中城市信息 的个数时,返回第 bstrOID 个城市信息 组织名称12 机构名称13一个证书的主题中可能出现多个机构名称.获取此信息 时需要设置参数 bstrOID.当 bstrOID 设置成”0”时,返回 值是证书的主题中包含的机构名称的信息的个数,当 bstrOID 设置为大于 0 且小于等于证书主题中机构名称 信息的个数时,返回第 bstrOID 个机构名称信息 国家14例如:CN 2.4. SetAlgorithm 功能简介功能简介： 设置算法 原型原型： HRESULT SetAlgorithm( in BSTR bstrSignAlg, in BSTR bstrEncAlg, out, retval long* pRetVal) 参数参数： 输入：bstrSignType 签名算法类型 bstrEncType 加密算法类型 输出：pRetVal- 操作错误码 返回值返回值： 类型为 HRESULT 0 表示成功，1 表示失败 备注备注 该接口在签名，加密之前使用，若用户不调用该接口或不指定算法将采用默认算法，签名的默 认算法为“SHA1RSA”，加密的默认算法为“DES3CBC”。 支持的签名算法类型： 算法类型算法类型输入值（字符串）输入值（字符串）描述描述 SHA1RSA