安全中间件二次开发手册.docx
《安全中间件二次开发手册.docx》由会员分享，可在线阅读，更多相关《安全中间件二次开发手册.docx（53页珍藏版）》请在冰豆网上搜索。
安全中间件二次开发手册
（1）
安全中间件二次开发手册
Copyright©2003ShanghaiwellhopeInformationTechnologyCo.,Ltd.AllRightsReserved
目录
1引言4
1.1编写目的4
1.2项目背景4
1.3术语和缩写词5
1.4遵循标准5
2系统概述7
2.1功能8
2.2性能9
精度9
时间特性9
灵活性9
3运行环境10
3.1硬件系统10
3.2支撑软件10
4开发说明10
4.1客户端描述11
4.1.1APP客户端控件接口说明11
4.1.1.1AtvInit11
4.1.1.2AtvEnd11
4.1.1.3SetHardWare12
4.1.1.4Login12
4.1.1.5ChangeLoginPin12
4.1.1.6Logout13
4.1.1.7GetCert13
4.1.1.8CheckCert13
4.1.1.9GetCertInfo14
4.1.1.10SealEnvelope15
4.1.1.11SealEnvelopeEx16
4.1.1.12OpenEnvelope17
4.1.1.13SignData17
4.1.1.14SignDataEx18
4.1.1.15VerifySign18
4.1.1.16GenRandom19
4.1.1.17HashData19
4.1.1.18SymmEncrypt20
4.1.1.19SymmDecrypt20
4.1.1.20GetCertFromLDAP21
4.1.1.21GetAndSaveCRL21
4.1.1.22ReadFromFile22
4.1.1.23WriteToFile22
4.1.1.24GetStamp22
4.1.1.25VerifyStamp23
4.1.1.26GetAlgoFromPA23
4.1.1.27Base64Encode24
4.1.1.28Base64Decode24
4.1.1.29GetParamValue25
4.2服务端描述25
4.2.1APP应用服务器端JAVA接口25
4.2.1.1release25
4.2.1.2GetCurStatus25
4.2.1.3AdvBase64Encode26
4.2.1.4AdvBase64Decode26
4.2.1.5AdvGetCert26
4.2.1.6AdvCheckCert26
4.2.1.7AdvGetCertInfo27
4.2.1.8AdvSealEnvelope28
4.2.1.9AdvSealEnvelopeEx29
4.2.1.10AdvOpenEnvelope30
4.2.1.11AdvSignData30
4.2.1.12AdvSignDataEx31
4.2.1.13AdvVerifySign31
4.2.1.14AdvGenRandom32
4.2.1.15AdvHashData32
4.2.1.16AdvSymmEncrypt33
4.2.1.17AdvSymmDecrypt33
4.2.1.18AdvGetCertFromLDAP34
4.2.1.19AdvGetCRLFromLDAP34
4.2.1.20AdvUploadCRL35
4.2.1.21AdvReadFromFile35
4.2.1.22AdvWriteToFile35
4.2.1.23AdvGetStamp36
4.2.1.24AdvVerifyStamp36
4.2.1.25AdvGetAlgoFromPA36
4.2.1.26AdvGetAttrCertInfo37
4.2.1.27AdvGetPACertInfo37
4.2.1.28AdvGetAttrCertListFromLDAP38
5应用开发实例39
5.1身份认证参考模型40
5.2加解密功能参考模型43
5.3签名验签功能参考模型44
1引言
1.1编写目的
1.该文档主要规范了PKI安全中间件的功能接口定义。
在整个PKI体系中，安全中间件的作用非常关键，它通过调用底层的WHCSP及证书管理器等，封装了一系列PKI应用接口，满足上层PKI具体应用的需要。
本标准适用于PKI上层应用的需求，主要为CA系统。
适用对象为所有采用安全中间件的系统开发人员。
1.2项目背景
2.高级密码服务，顾名思义，是为用户提供相对高级和抽象的密码服务，而不是像底层的CSP和硬件加密算法那样，提供比较低级和具体的密码服务。
一般来说，高级的密码服务应该能够让不懂加密、解密和签名、验签等概念的用户也能够透明的使用，也就是说把密码学算法的细节给屏蔽掉了。
1.3术语和缩写词
缩写、术语
解释
（2）PKI
（3）公钥基础设施（PublicKeyInfrastructure）
（4）CSP
（5）CryptographicServiceProvider（密码服务提供者）
（6）CRL
（7）证书撤消列表（CertificateRevocationList）
（8）一个标记一系列不再被证书发布者所信任的证书的签名列表（通称黑名单）。
（9）LDAP
（10）目录查询协议（LightweightDirectoryAccessProtocol）
（11）本设计指轻型目录访问协议LDAP。
用户可使用LDAP协议，通过网络到目录服务器查询系统中的证书或证书撤消列表。
（12）OCSP
（13）在线证书状态查询协议（OnlineCertificateStatusProtocol）
（14）用户可使用OCSP协议，通过网络到OCSP服务器实时查询系统中证书的当前有效/无效状态。
（15）
1.4遵循标准
列出参考资料，如：
●RFC2459PKIXPKIX证书和CRL概要
●IETF：
PKIX证书策略和证书实践框架
●IETF：
RFC2510:
CMP（证书管理协议）
●RFC2797:
CMC（CMS上的证书管理消息）
●RFC2511:
CRMF（证书请求消息格式）
●X.208抽象语法符号1描述（ASN.1）
●X.209抽象语法符号1基本编码规范说明（ASN.1）
●X.680信息技术―抽象语法符号1（ASN.1）—基本符号规范
●X.681信息技术―抽象语法符号1（ASN.1）－信息目标规范
●X.682信息技术―抽象语法符号1（ASN.1）－强制规范
●X.690信息技术―ASN.1编码规则－基本编码规则（BER）,规范编码规则（CER）和主要编码规则（DER）
●X.509v4信息技术－开放式系统互连－目录：
公钥和属性证书框架
●X.500开放式系统互连—目录：
概念，模型和服务概述
●LDAP轻目录访问协议：
由ISO于1997年12月发布。
●PKCS#1（v1.5）RSA密码算法
●PKCS#5（v2.0）基于口令的密码标准
●PKCS#6（v1.5）扩展的数字证书语法标准
●PKCS#7（v1.5）密文消息语法标准
●PKCS#8（v1.5）私钥信息语法标准
●PKCS#9（v2.0）可选择的属性类型
●PKCS#10（v1.5）数字证书申请语法标准
●PKCS#11硬件密码设备接口标准
●PKCS#12（v1.0）个人信息交换语法
●PKCS#15（v1.1）多个应用访问标准
●X.509开放式系统互连—目录：
公钥和授权证书框架
●ITU-TX.500开放式系统互连—目录：
概念，模型和服务概述
●CORBA（公共对象请求代理体系结构）v2.4
3.
2系统概述
在PKI体系结构中【见上图】，安全中间件总揽了证书管理器和CSP的所有功能。
它在PC端和PKI服务器端都是直接面向最终用户的调用接口，因此，它必须能够屏蔽掉PC端和PKI服务器端的不同情况。
安全中间件是为用户提供相对高级和抽象的密码服务，而不是像底层的CSP和硬件加密算法那样，提供比较低级和具体的密码服务。
一般来说，安全中间件服务应该能够让不懂加密、解密和签名、验签等概念的用户也能够透明的使用，也就是说把密码学算法的细节给屏蔽掉了。
2.1功能
●抽象的算法服务
1.对指定的明文进行加密的功能，包括口令加密、对称密钥加密和公开密钥加密。
2.对指定的密文进行解密的功能，包括对称密钥解密和公开密钥解密。
3.对指定的明文进行签名的功能。
4.对指定的签名进行验签的功能
5.封装PKCS7数字信封
6.解开PKCS7数字信封
7.对明文进行散列。
8.产生随机数。
●抽象的证书服务
1.根据标签得到证书
2.验证证书的有效性
3.生成PKCS10格式的证书请求文件
4.输入绑定的证书和私钥。
●私钥和口令保护服务
1.检查私钥口令
2.更改私钥口令
3.检查PIN
4.更改PIN
●编码服务
5.ASE64的编码功能
6.BASE64的解码功能
2.2性能
精度
（16）TSP响应时间<1s；
（17）OCSP响应时间<1s；
（18）LDAP服务单元响应速度<0.5s
时间特性
（19）客户端RSA签名2次/秒
（20）验签5次/秒
（21）服务器端RSA签名20次/秒
（22）验签100次/秒
灵活性
（23）可以灵活支持多种硬件介质和硬件加密卡；
（24）可以提供C/C++、Java、C#等应用接口；
（25）一套软件结构可以同时为CA和应用提供服务；
（26）可以支持33算法、RC4算法、DES/3DES算法；
3运行环境
3.1硬件系统
（27）适用于各种PC兼容机、服务器、小型机等等
3.2支撑软件
（28）WINDOWS2000，WindowsXP，LINUX（RedHat9.0及AdvancedServer2.1）
4开发说明
4.描述系统为二次开发工作提供的接口、约束等。
安全中间件分为客户端和服务端2部分，安全中间件客户端主要的功能是在客户端通过对硬件存储介质的操作完成一些密码运算。
服务端主要是通过调用密码服务器为应用服务提供所需的密码服务。
客户端和服务端产的数据格式都采用国际同意标准。
服务端可以运算客户端产生的数据，客户端也可以运算服务端产生的数据。
主要用的功能为客户端进行签名、加密，服务端验签、解密或服务端签名、加密，客户端验签、解密。
客户端与服务端的数据传输可以由应用开发灵活处理，但要保证在传输前后数据的格式不发生变化。
5.通过安全中间件提供的抽象密码服务，为应用开发提供机密性，完整性，不可抵赖性方面的支持。
完成身份认证，电子印章，责任认定，密文传输等应用服务。
4.1客户端描述
6.客户端主要设备是硬件存储介质E-Key，E-Key做为数字证书的存储设备主要存储用户的签名私钥，加密私钥，签名证书，加密证书。
通过调用客户端控件可以使用E-Key完成签名，加密等密码服务。
4.1.1APP客户端控件接口说明
4.1.1.1AtvInit
功能简介
控件初始化。
读取客户端证书载体信息及其它初始化工作。
调用一些主要功能接口前必须先调用本接口。
接口名称
intAtvInit（）
参数说明
入参说明
无
出参说明
无
返回值
成功，则返回0
失败，则返回错误号,错误号小于0
4.1.1.2AtvEnd
功能简介
进行开发包函数库调用完毕后内部存储区的清除工作。
接口名称
intAtvEnd（）;
参数说明
入参说明
无
出参说明
无
返回值
成功，则返回0
失败，则返回错误号，小于0
4.1.1.3SetHardWare
功能简介
设置客户端硬件设备类型。
接口名称
BOOLSetHardWare（longhardwareType）;
参数说明
入参说明
hardwareType[IN]：
客户端硬件设备类型
目前支持：
1 软件摸拟实现
2 加密卡实现
3 SIM卡实现
4EKEY实现
出参说明
无
返回值
成功，则返回TRUE
失败，则返回FALSE
4.1.1.4Login
功能简介
登录客户端硬件设备。
接口名称
BOOLLogin（intloginType,
BSTRloginPin）;
参数说明
入参说明
loginType[IN]：
用户登陆类型，此处用户请输入1
loginPin[IN]：
用户登陆PIN码
出参说明
无
返回值
成功，则返回TRUE
失败，则返回FALSE
说明
调用本接口时，如果loginPin输入为””空，则会弹出输入口令对话框；如果不为空，则不会弹出，只返回登录是否成功。
4.1.1.5ChangeLoginPin
功能简介
修改客户端用户登陆PIN码。
接口名称
BOOLChangeLoginPin（BSTRkeyLabel,
BSTRoldPasswd,
BSTRnewPasswd）;
参数说明
入参说明
keyLabel[IN]：
私钥标签，此处请传入“wellhope”
oldPasswd[IN]：
旧的用户登陆口令
newPasswd[IN]：
新的用户登陆口令
出参说明
无
返回值
成功，则返回TRUE
失败，则返回FALSE
4.1.1.6Logout
功能简介
退出客户端硬件登录。
接口名称
BOOLLogout（）;
参数说明
入参说明
无
出参说明
无
返回值
成功，则返回TRUE
失败，则返回FALSE
4.1.1.7GetCert
功能简介
根据证书标签和证书类型读取客户端用户证书。
证书标签写在配置文件中，见前面Client.conf配置文件。
接口名称
BSTRGetCert（intcertType）;
参数说明
入参说明
certType[IN]：
证书类型
1---加密证书
2---签名证书
出参说明
无
返回值
返回编码后的证书信息。
4.1.1.8CheckCert
功能简介
验证证书的有效性。
在验证过程中会连接到OCSP服务器上进行证书的验证。
接口名称
BOOLCheckCert（BSTRi_inCert）;
参数说明
入参说明
i_inCert[IN]：
待验证的证书，已编码。
出参说明
无
返回值
成功，则返回TRUE
失败，则返回FALSE
4.1.1.9GetCertInfo
功能简介
解析证书信息，并以XML字符串格式返回
接口名称
BSTRGetCertInfo（BSTRi_inCert）;
参数说明
入参说明
i_inCert[IN]：
待解析的证书，已编码。
出参说明
无
返回值
返回采用XML标准结构的证书信息。
[举例]
3
00000000000000000000000000000042
SHA1RSA
CN
Shanghai
Zhangjiang
ShanghaiwellhopeE-BussinessCertificateAuthority
WELLHOPE
自然人CA
2003年08月21日
2004年08月21日
CN
Shanghai
Zhangjiang
wellhope
infosec
user5
30818902818100f34d52b7fb481752a506905e5b8a0698994dc3104fc8f7d1180912c6087dee594225d4ba1946dfad58598859d3501e59fc9cbd86b50c79b2ce09630fed4896651b54c37ae98855545c1434f9f4a15e3a15e9b09997b03af16c7465f816bfe2b1a49821a0090e283f82ebf2ed7daa2e76a5ada469a14e78108dde58ac13b826fb0203010001
4.1.1.10SealEnvelope
功能简介
数字信封加密。
内部的处理过程是首先随机生成一对称密钥（由入口参数指定其算法或者通过PA确定），然后用此对称密钥加密输入的数据，最后用公钥加密产生的此对称密钥。
这是我们推荐的一种对数据进行加密的方法，因为它不仅保证了加密的高效性（对称密钥的快速加密），还保证了加密的高强度性（公钥的强加密）。
此函数的加密输出结果遵循PKCS#7的编码标准（EnvelopedData）。
接口名称
BSTRSealEnvelope（BSTRi_encCert,
longi_symmAlgo,
BSTRi_inData）;
参数说明
入参说明
i_encCert[IN]：
用于加密的数字证书，已编过码。
i_symmAlgo[IN]：
信封中所用对称算法标识。
取值如下：
CALG_RC4=26625
CALG_3DES=26115
CALG_33=9
viaPA=0，说明加密过程首先将连接到PA（策略中心）获取相应的参数进行后续的工作
i_inData[IN]：
输入原文信息，如是二进制数据则已编过码。
出参说明
无
返回值
输出的已编码的密文结果。
4.1.1.11SealEnvelopeEx
功能简介
用多证书批量生成数字信封。
此函数的加密输出结果遵循PKCS#7的编码标准（EnvelopedData）。
接口名称
BSTRSealEnvelopeEx（BSTRi_encCert,
longi_certsize,
longi_symmAlgo,
BSTRi_inData）;
参数说明
入参说明
i_encCert[IN]：
用于加密的数字证书，已编过码,多个证书间以“｜”隔开。
i_certsize[IN]：
保留参数
i_symmAlgo[IN]：
信封中所用对称算法标识。
CALG_RC4=26625
CALG_3DES=26115
CALG_33=9
viaPA=0，说明加密过程首先将连接到PA（策略中心）获取相应的参数进行后续的工作
i_inData[IN]：
输入原文信息，如是二进制数据则已编过码。
出参说明
无
返回值
输出的已编码的密文结果。
4.1.1.12OpenEnvelope
功能简介
解析数字信封
私钥标签在配置文件中定义，运行时弹出输入框提示用户输入私钥保护口令。
接口名称
BSTROpenEnvelope（BSTRi_inData）;
参数说明
入参说明
i_inData[IN]：
输入已编码的信封数据。
出参说明
无
返回值
输出原文信息,如是二进制数据则已编过码。
4.1.1.13SignData
功能简介
对输入数据进行数字签名。
私钥标签在配置文件中定义，运行时弹出输入框提示用户输入私钥保护口令。
接口名称
BSTRSignData（BSTRi_inData,
inti_algoType,
inti_signType）;
参数说明
入参说明
i_inData[IN]：
输入的待签名数据，二进制数据需要做编码处理。
i_algoType[IN]：
签名算法
取值如：
32772--------sha1RSA
32771-------md5RSA
sha1RSA、md5RSA说明签名采用的是何种摘要算法＋签名算法
i_signType[IN]：
签名值类型
取值：
0－－不包含原文的纯签名
1－－包含原文的PKCS7格式数据
出参说明
无
返回值
输出的已编码的签名数据。
4.1.1.14SignDataEx
功能简介
对输入数据进行数字签名。
私钥标签在配置文件中定义，运行时弹出输入框提示用户输入私钥保护口令。
接口名称
BSTRSignData（BSTRi_sigCert,
BSTRi_inData,
inti_algoType,
inti_signType）;
参数说明
入参说明
i_sigCert[IN]：
通信对方的证书，当需要通过PA获取签名算法时需输入
i_inData[IN]：
输入的待签名数据，二进制数据需要做编码处理。
i_algoType[IN]：
签名算法
取值如：
32772--------sha1RSA
32771-------md5RSA
0--------viaPA等
sha1RSA、md5RSA说明签名采用的是何种摘要算法＋签名算法
viaPA=0，说明签名过程首先将连接到PA（策略中心）获取相应的参数进行后续的工作
i_signType[IN]：
签名值类型
取值：
0－－不包含原文的纯签名
1－－包含原文的符合PKCS7格式的数据
出参说明
无
返回值
输出的已编码的签名数据。
4.1.1.15VerifySign
功能简介
对输入数据进行数字签名的验证
接口名称
BOOLVerifySign（BSTRi_checkCert,
BSTRi_clearText,
BSTRi_signature,
inti_algoType,
inti_signType）;
参数说明
入参说明
i_checkCert[IN]：
验证所用的证书。
i_clearText[IN]：
签名的原文。
如签名值包含原文，置空即可。
i_signature[IN]：
待验证的签名数据。
i_algoType[IN]：
签名算法。
如签名值不
升级会员 