基于WEB的电子签章客户端开发说明书

1、基于web的电子签章客户端开发说明书v1.0山东省数字证书认证管理有限公司2006年4月目录目录21简介41.1电子签章41.2数字签名41.3数字证书、pki/ca41.4加解密基础理论41.5山东ca电子签章系统简介52接口说明62.1jitsecuritytool62.1.1 initcontrol62.1.2 readsinglecert62.1.3 readcert72.1.4 getcryptcert72.1.5 getsigncert82.1.6 encryptsign82.1.7 getconten82.1.8 getcontenlen82.1.9 decryptverify9

2、2.1.10 signenvelop92.1.11 verifyenvelop102.1.12 encenvelop102.1.13 decenvelop102.1.14获取证书信息112.1.15 verifypin112.1.16 changepin112.1.17 digest122.1.18 signdata122.1.19 verifysign122.1.20 signdataex132.1.21 verifysignex132.1.22 encryptsignex132.1.23 decryptverifyex142.1.24 encryptsignf2f142.1.25 decr

3、yptverifyf2f152.1.26 showpic152.1.27 showsinglepic152.1.28 hermit162.1.29 recover162.1.30 makeseal162.1.31 getusercert172.1.32 servertime172.1.33 获取路径172.1.34常见错误列表172.2imgconvert182.2.1 bmp2transparentgif192.2.2常见错误码列表192.3sdgetessfromelsign192.3.1 decompresspic192.3.2 getsealfromelsign192.3.3 getv

4、aluefromelsign202.3.4 getconten202.3.5 getcontenlen202.3.6常见错误码列表212.4挂接流程212.5系统硬件要求212.6系统运行环境223应用拓展221简介1.1电子签章电子签章，泛指所有以电子形式存在，依附在电子文件并与其逻辑关联，用以辨识电子文件签署者身份，保证文件的完整性，并表示签署者同意电子文件所陈述事实的内容。1.2数字签名数字签名是附加在数据单元上的一些数据，或是对数据单元所作的密码变换，这种数据和变换允许数据单元的接收者用以确认数据单元来源和数据单元的完整性，并保护数据，防止伪造。1.3数字证书、pki/ca数字证书是用

5、电子手段来证实一个用户的身份和对网络资源的访问权限。数字证书是由权威机构(ca)采用数字签名技术，颁发给用户，用以在数字领域中证实用户其本身的一种数字凭证。 数字证书的内部格式是由ccitt x.509国际标准所规定的，它主要包含了以下几点： 证书拥有者的姓名证书拥有者的公共密钥证书的有效期证书的序列号颁发证书的单位机构颁发证书单位的数字签名证书的扩展信息等pki(public key infrastructure公钥基础设施) 是一种遵循标准的利用公钥加密技术为电子商务的开展提供一套安全基础平台的技术和规范。它能够为所有网络应用提供加密和数字签名等密码服务及所必需的密钥和证书管理体系，简单来

6、说，pki就是利用公钥理论和技术建立的提供安全服务的基础设施。用户可利用pki平台提供的服务进行安全的电子交易，通信和互联网上的各种活动。ca（certification authority 认证中心）是用来颁发数字证书的权威机构，它具有权威性、公正性和可靠性。其主要任务是受理数字证书的申请、签发及对数字证书的管理。在受理申请的同时，一般还会核对申请者的身份，以确保正确。1.4加解密基础理论对数据的加密一般分为对称加密和非对称加密，对称加密以des为代表，非对称加密以rsa为代表。 des算法：des（data encryption standard）是一种单密钥算法，也是一种最有代表性的分组

7、加密体制，数据分组长度是64bit(8 byte)，密文分组长度也是64bit，没有数据扩展。密钥长度为64bit，其中有8bit奇偶校验，有效长度为56bit。为加强安全性，又可采用三重des。des的整个体制是公开的，系统的安全性倚赖于密钥。rsa算法：rsa是一种基于公钥体制的双密钥的算法，这一算法的最大特点就是有一对密钥，一个公开发布作为加密密钥，一个由用户妥善保管作为解密密钥，通讯双方无须事先交换密钥就可进行保密通讯。该体制的另一个特点是无法从一个密钥推断出另一个密钥，以及不能用加密密钥进行解密。rsa算法可以用来加密数据（用公钥加密，私钥解密），也可以用来签名（用私钥加密，公钥解密

8、）。 1.5山东ca电子签章系统简介功能结构图 山东ca电子签章系统是一套完善的应用软件，可实现在网页上加盖电子签章。由三大模块组成：签章服务器模块、签章客户端模块、认证服务器模块。具有如下功能：签章制作:支持灵活的签章制作，用户可选择传统的公章形式或个人签名形式。登陆控制:可代替传统的用户名、密码登陆方式，实现授权管理、安全访问的功能。签章/验证功能:对指定区域进行签章，支持区域签章、多人汇签功能。加密/解密功能:支持对指定区域包装数字信封，实现密文传输功能，保证了电子信息网络传输的安全性。查看证书:查看签署者个人证书的基本信息。记载可信时间:山东ca电子签章产品提供读取标准时间的接口或通过

9、记载服务器的时间满足记载签章可信时间的需求。2接口说明本系统客户端采用activex技术进行开发，可嵌入到包括基于web进行开发的分布式系统中。2.1jitsecuritytooljitsecuritytool控件实现对文件格式证书、usb ekey中证书的读取等几种常用操作。主要包括：初始化引擎、数字证书的读取、数字摘要、数字签名、封装数字信封等功能。clsid：f1fdd7d2-0192-4f66-a015-4fc6235e8b74 版本号：1.0.1.22.1.1 initcontrol函数原型：long initcontrol()功能说明：这个接口提供初始化应用api引擎，打开设备句柄

10、，用户在使用api com接口的其他功能之前，必须初始化引擎。参数说明：无返回值： 0 初始化成功50 在控件已经初始化过的情况下又进行了第二次初始化（返回这个值并不影响以后的功能调用，可以忽略这个值） 其他初始化失败2.1.2 readsinglecert函数原型：long readsinglecert(lpctstr singlecertpath, long apptype, lpctstr singlecertpwd)功能说明：读取文件格式单证证书。调用该函数成功后，将pem编码的公钥证书存入临时变量中，用户通过调用getcryptcert()和getsigncert()获得相应的加密和

11、签名证书,通过调用getsinglecertpath()获得相应证书路径。参数说明：singlecertpath：证书路径,路径可以为空，而自动寻找证书 apptype：证书开通应用类型（视证书开通目的而定） singlecertpwd：证书口令注意： 单证证书的名称均不一样，可将singlecertpath设空，实现自动寻找证书。返回值： 0 读取证书成功 其他读取证书失败2.1.3 readcert函数原型：long readcert(lpctstr cryptcertpath, long cryptcerttype, lpctstr cryptcertpasswd, lpctstr si

12、gncertpath, long signcerttype, lpctstr signcertpasswd)功能说明：读取双证（文件、ekey）证书。调用该函数成功后，将pem编码的公钥证书存入临时变量中，用户通过调用getcryptcert()和getsigncert()获得相应的加密和签名证书。参数说明：cryptcertpath：加密证书路径如：文件格式证书:file:/d:encrypt.cer 智能卡证书:usbcsp:/.2cer cryptcerttype：证书开通应用类型（视证书开通目的而定） cryptcertpasswd：加密证书口令 signcertpath：签名证书路径

13、 参数设定如同参数cryptcertpath signcerttype：证书开通应用类型（视证书开通目的而定） signcertpasswd：签名证书口令注意： cryptcertpath及signcertpath参数类型必须一致。返回值： 0 读取证书成功 51 证书不在有效期内 其他读取证书失败2.1.4 getcryptcert函数原型：bstr getcryptcert()功能说明：获取加密证书（对应公钥），调用readcert函数后才能调用。返回值：base64编码的证书。2.1.5 getsigncert函数原型：bstr getsigncert()功能说明：获取签名证书（对应公钥

14、），调用readcert函数后才能调用。参数说明：无返回值：base64编码的证书。2.1.6 encryptsign函数原型：long encryptsign(lpctstr signcertpath, lpctstr signkeypasswd, lpctstr recvencryptcert64, lpctstr msgraw) 功能说明：产生pkcs7数字信封，实现加密签名。密文将存放在临时变量中，通过getconten()函数获得。参数说明：signcertpath：签名证书路径 signkeypasswd：签名证书口令 recvencryptcert64：接受方加密证书的pem编码

15、，字符串类型 msgraw：要加密的明文，字符串类型注意： 证书为文件格式时，signcertpath中的证书必须为pfx格式。返回值： 0 产生签名加密数字信封成功 其他产生签名加密数字信封失败2.1.7 getconten函数原型：bstr getconten()功能说明：获取密文或者明文信息参数说明：无返回值： 密文或者明文 base64编码2.1.8 getcontenlen函数原型：long getcontenlen()功能说明：获取密文或者明文信息长度参数说明：无返回值： 密文或者明文的长度2.1.9 decryptverify函数原型：long decryptverify(lpc

16、tstr encryptcertpath, lpctstr encryptcertpasswd, lpctstr sendsigncert64, lpctstr cipherdata64) 功能说明：验证pkcs7数字信封，实现解密并验证签名的功能。解密后的明文将存放临时变量中，通过getconten()函数获得。参数说明：encryptcertpath：加密证书路径 encryptcertpasswd：加密证书口令 sendsigncert64：发送方签名证书的pem编码，字符串类型 cipherdata64：base64编码的密文，字符串类型注意： 证书为文件格式时，signcertpat

17、h中的证书必须为pfx格式。返回值： 0 验证签名加密数字信封成功 其他验证签名加密数字信封失败2.1.10 signenvelop函数原型：long signenvelop(lpctstr signcertpath, lpctstr signcertpwd, lpctstr msgraw)功能说明：产生签名数字信封。密文将存放在临时变量中，通过getconten()函数获得。参数说明：signcertpath：签名证书路径如：文件格式证书:file:/d:encrypt.cer 智能卡证书:usbcsp:/.2cer signcertpwd：签名证书口令 msgraw： 需要签名的原文返回值

18、： 0 制作签名数字信封成功 其他制作签名数字信封失败2.1.11 verifyenvelop函数原型：long verifyenvelop(lpctstr signcertpem, lpctstr verifymsgbase64)功能说明：验证签名数字信封。解密的明文将存放在临时变量中，通过getconten（）函数获得。参数说明：signcertpem： 签名证书公钥证书base64编码 verifymsgbase64：签名返回值： 0 验证签名数字信封成功 其他验证签名数字信封失败2.1.12 encenvelop函数原型：long encenvelop(lpctstr cryptcer

19、tpem, lpctstr msgraw)功能说明：产生加密数字信封。密文将存放在临时变量中，通过getconten()函数获得。参数说明：cryptcertpem： 加密证书公钥证书base64编码 msgraw： 需要加密的原文返回值： 0 产生加密数字信封成功 其他产生加密数字信封失败2.1.13 decenvelop函数原型：long decenvelop(lpctstr cryptcertpath, lpctstr cryptcertpwd, lpctstr decmsgbase64)功能说明：验证加密数字信封。解密的明文将存放在临时变量中，通过getconten()函数获得。参数说

20、明：cryptcertpath：加密证书路径如：文件格式证书:file:/d:encrypt.cer 智能卡证书:usbcsp:/.2cer cryptcertpwd：加密证书口令 decmsgbase64：密文返回值： 0 验证加密数字信封成功 其他验证加密数字信封失败2.1.14获取证书信息bstr email() /返回电子信箱地址，字符串类型bstr issuer () /返回证书发布者信息，字符串类型bstr subject() /返回证书主题信息，字符串类型bstr starttime() /返回证书有效期起始时间，字符串类型bstr endtime() /返回证书有效期截止时间，

21、字符串类型bstr signcertsn() /返回签名证书序列号，字符串类型bstr enccertsn() /返回加密证书序列号，字符串类型bstr getunit() /返回单位信息，字符串类型注意：证书发布者、证书主题的信息内容包含若干项，比如cn为名字，c为国家等等，在调用issuer()或subject()获取证书发布者信息或证书主题信息时，这些项的信息都存放在同一字符串中，作为返回值。使用者可以再经过字符运算等取得各项的内容。2.1.15 verifypin函数原型：long verifypin(lpctstr ppin, long len)功能说明：验证ekey证书口令参数说明

22、：ppin：需要验证ekey证书的密码len：需要验证的密码的长度返回值：0：成功 其他：失败2.1.16 changepin函数原型：long changepin(lpctstr poldpin, long oldpinlen, lpctstr pnewpin, long newpinlen)功能说明：修改ekey证书口令参数说明：poldpin：ekey证书的旧密码oldpinlen：旧密码的长度pnewpin：ekey证书的新密码newpinlen：新密码的长度返回值：0：成功其他：失败2.1.17 digest函数原型：long digest(lpctstr msgraw, long

23、msgrawlen)功能说明：修改ekey证书口令参数说明：msgraw：输入的原文msgrawlen：原文长度返回值：0：成功其他：失败注：通过getconten()获取输出摘要的内容2.1.18 signdata函数原型：long signdata(lpctstr signcertpath, lpctstr signcertpwd, lpctstr msgraw, long msgrawlen)功能说明：对字符串进行签名，用户通过调用getconten获得用户的签名值参数说明：signcertpath：签名证书路径文件格式证书:file:/d:encrypt.pfx 智能卡证书:usbcs

24、p:/.2cer signcertpwd：签名证书口令 msgraw：明文msgrawlen：明文长度返回值： 0 签名成功 其他签名失败2.1.19 verifysign函数原型：long verifysign(lpctstr signcertder, lpctstr msgraw, long msgrawlen, lpctstr signdata)功能说明：对签名值进行验证参数说明：signcertder：公钥证书（base64编码） msgraw：要验证的明文msgrawlen：要验证的明文长度signdata：签名值返回值： 0 验证成功 其他验证失败2.1.20 signdataex

25、函数原型：long signdataex(lpctstr signcertpath, lpctstr signcertpwd, lpctstr filepath)功能说明：对文件进行签名，用户通过调用getconten获得用户的签名值参数说明：signcertpath：签名证书路径如：文件格式证书:file:/d:encrypt.pfx 智能卡证书:usbcsp:/.2cer signcertpwd：签名证书口令 filepath：文件路径返回值： 0 签名成功 其他签名失败2.1.21 verifysignex函数原型：long verifysignex(lpctstr signcertde

26、r, lpctstr filepath, lpctstr signdata)功能说明：对文件进行的签名值进行验证参数说明：signcertder：公钥证书（base64编码） filepath：要验证的文件路径signdata：签名值返回值： 0 验证成功 其他验证失败2.1.22 encryptsignex函数原型：long encryptsignex(lpctstr signcertpath, lpctstr signcertpwd, lpctstr recvencryptcert64, lpctstr filepath)功能说明：对文件产生pkcs7数字信封，实现加密签名。密文将存放在临

27、时变量中，通过getconten（）函数获得。参数说明：signcertpath：签名证书路径如：文件格式证书:file:/d:encrypt.pfx 智能卡证书:usbcsp:/.2cer signcertpwd： 签名证书口令recvencryptcert64：接受方加密证书的pem编码，字符串类型 filepath： 文件路径返回值： 0 数字信封封装成功 其他数字信封封装失败2.1.23 decryptverifyex函数原型：long decryptverifyex(lpctstr encryptcertpath, lpctstr encryptcertpwd, lpctstr se

28、ndsigncert64, lpctstr cipherdata64, lpctstr filepath)功能说明：对文件封装的pkcs7数字信封进行验证，实现解密并验证签名的功能。验证成功，通过filepath返回明文文件 参数说明：encryptcertpath：加密证书路径 encryptcertpasswd：加密证书口令 sendsigncert64：发送方签名证书的pem编码，字符串类型 cipherdata64：base64编码的密文，字符串类型filepath：需要返回的文件路径返回值： 0 验证成功 其他验证失败2.1.24 encryptsignf2f函数原型：long en

29、cryptsignf2f(lpctstr signcertpath, lpctstr signcertpwd, lpctstr recvencryptcert64, lpctstr filepath, lpctstr outfilepath)功能说明：对文件产生pkcs7数字信封，实现加密签名。参数说明：signcertpath： 签名证书路径如：文件格式证书:file:/d:encrypt.pfx 智能卡证书:usbcsp:/.2cer signcertpwd： 签名证书口令recvencryptcert64：接受方加密证书的pem编码，字符串类型 filepath： 明文文件路径outfi

30、lepath： 密文文件路径返回值： 0 数字信封封装成功 其他数字信封封装失败2.1.25 decryptverifyf2f函数原型：long decryptverifyf2f(lpctstr encryptcertpath, lpctstr encryptcertpwd, lpctstr sendsigncert64, lpctstr infilepath, lpctstr filepath)功能说明：对文件封装的pkcs7数字信封进行验证，实现解密并验证签名的功能。验证成功，通过filepath返回明文文件 参数说明：encryptcertpath： 加密证书路径 encryptcert

31、passwd：加密证书口令 sendsigncert64：发送方签名证书的pem编码，字符串类型 infilepath：base64编码的密文文件路径filepath：需要返回的文件路径返回值： 0 验证数字信封成功 其他验证数字信封失败2.1.26 showpic函数原型：long showpic(lpctstr keypwd, lpctstr compicpath, lpctstr aupicpath)功能说明：从key中获取所有签章图片 参数说明：keypwd：key口令 compicpath：返回图章一路径 aupicpath：返回图章二路径返回值： 0 获取图片成功 其他获取图片失败

32、2.1.27 showsinglepic函数原型：long showsinglepic(lpctstr keypwd, long picindex, lpctstr picpath, long rgbflag)功能说明：从key中获取指定签章图片 参数说明：keypwd：key口令picindex： key中图章序列号。现key只支持存放两张图章，0-图章一，1-图章二, 2-图章三， 3-图章四 picpath：返回图章路径rgbflag：设置图章前景色，暂支持三种前景色的设置：0-红色，1-蓝色，2-黑色返回值： 0 获取图片成功 其他获取图片失败2.1.28 hermit函数原型：lon

33、g hermit(lpctstr picpath, lpctstr signdata, lpctstr nszsigncert)功能说明：将签名值、公钥隐藏到图章中参数说明： picpath：要嵌入图片路径signdata：要嵌入的签名值nszsigncert：要嵌入的公钥，可为空值返回值： 0 嵌入成功 其他嵌入失败2.1.29 recover函数原型：long recover(lpctstr picpath)功能说明：从指定签章图片中提取隐藏信息，签名值及公钥将存放在临时变量中，通过getconten()函数获得签名值，getsigncert()函数获得公钥。参数说明： picpath：要

34、嵌入图片路径返回值： 0 提取成功 其他提取失败2.1.30 makeseal函数原型：long makeseal(lpctstr maintext, lpctstr picpath, long sealtype, long rgbflag)功能说明：该接口实现自动印章，支持圆章和方章的自动生成。参数说明：maintext：生成印章的文字内容picpath：生成图片的路径sealtype：图章类型 0-圆章 1-方章rgbflag:设置图章前景色，暂支持三种前景色的设置：0-红色，1-蓝色，2-黑色返回值： 0 生成印章成功 其他生成印章失败2.1.31 getusercert函数原型：lon

35、g getusercert(lpctstr certsn, long certtype)功能说明：该接口满足通过证书序列号查询到公钥证书。参数说明：certsn：证书序列号certtype：证书类型1-签名证书，2-加密证书返回值： 0 成功 其他失败2.1.32 servertime函数原型：long servertime()功能说明：该接口实现本地时间与服务器时间同步，应在initcontrol()初始化后使用。参数说明：无返回值： 0 时间同步成功 其他时间同步失败2.1.33 获取路径函数原型：long getworkpath()功能说明：获取系统路径参数说明：无函数原型：long g

36、ettemppath()功能说明：获取临时路径参数说明：无2.1.34常见错误列表50-系统路径已经初始化，该错误可忽略！51-证书已过期或系统时间设置错误-1001-证书路径参数格式错误-1003-ekey未插好-2001-验证密码错误-3000-加载图章文件底层库失败-3001-读取图章文件失败-3002-创建图章文件失败-3004-要嵌入的字符长度超过图片所容纳长度-3006-解压失败-3009-打开文件错误-3011-参数错误-3012-文件保存错误-3013-内存申请错误-4001-证书未到应用期或系统时间设置错误-4002-证书没有开通相关应用-4003-证书的安全应用已过期或系统

37、时间设置错误-4004-证书与其配置文件不匹配-4100-证书没有开通应用或者应用文件已损坏或软盘、ekey没有插好-5001-编码base64错误-5002-解码base64错误-5101-不能实例化ekey证书-9003-不能访问加密设备（针对ekey）-9005-证书密码错误或证书不完整-9008-证书查询失败-9009-crl不完整-9012-证书链不完整-9014-根证书无效-9018-没有找到证书-9021-私钥不存在-9022-算法和密钥不匹配-9026-证书和算法不匹配-9027-签名失败-9028-验证签名失败-9029-加密失败-9030-解密失败-9043-配置文件不存在

38、-9050-ldap引擎失败2.2imgconvertimgconvert控件实现bmp图片转换为透明图片的功能。clsid:041f253d-bb69-4688-93f3-b3c19f0712bf版本号：1.0.0.12.2.1 bmp2transparentgif函数原型：long bmp2transparentgif(bmpfile,giffile,rgbflag)参数说明：bmpfile:bmp文件路径giffile:转换后文件路径rgbflag：转换后前景色，默认为0即可返回值：0成功其他失败2.2.2常见错误码列表-1001-参数错误-1002-转换失败2.3sdgetessfro

39、melsignsdgetessfromelsign控件实现从签章服务器中按照图章索引号获取指定的印章及相应时间的公钥证书等。clsid: 32a78765-a53a-485e-aacf-b64498c02d74版本号：1.0.0.22.3.1 decompresspic函数原型：long decompresspic(lpctstr scrbuf, long scrbuflen, lpctstr filepath, long rgbflag)功能说明：用于解压图片信息，只对base64编码操作，生成硬盘图片参数说明：scrbuf：要处理的压缩串，base64编码 scrbuflen：要处理的压缩

40、串的长度filepath： 要生成图片的路径rgbflag：设置图片前景色，0-红章 1-蓝章 2-黑色返回值： 0 解压成功 其他失败，请查看错误码2.3.2 getsealfromelsign函数原型：bstr getsealfromelsign(lpctstr userid, lpctstr dateon, lpctstr sealtype, lpctstr elsignurl, long sealflag) 功能说明：从签章服务器中获取指定公钥、图章参数说明：userid：图章索引号，如个人身份证号码或者纳税人识别号等 dateon：指定图章所在日期，格式必须采用：yyyy-mm-ddsealtype：所需图章号。暂为个人签章提供存放一个图章功能，查询输入格式为：01#；为电子申报等应用的企业图章提供存放两个图章功能，查询输入格式为：01#或02#或01#02#elsignurl：签章服务器发布urlsealflag：图章标记，先支持个人图章、企业图章，一般个人图章为1，企业图章为2返回值： 签章服务器返回的字符串，按照公钥#图章1#图章2；failed为查询失败2.3.3 getvalu