安全中间件二次开发手册模板.doc

安全中间件二次开发手册Copyright Shanghai wellhope Information Technology Co.,Ltd. All Rights Reserved目 录1引言41.1编写目标41.2项目背景41.3术语和缩写词51.4遵照标准52系统概述72.1功效82.2性能9精度9时间特征9灵活性93运行环境103.1硬件系统103.2支撑软件104开发说明104.1用户端描述114.1.1APP用户端控件接口说明114.1.1.1AtvInit114.1.1.2AtvEnd114.1.1.3SetHardWare124.1.1.4Login124.1.1.5ChangeLoginPin124.1.1.6Logout134.1.1.7GetCert134.1.1.8CheckCert134.1.1.9GetCertInfo144.1.1.10SealEnvelope154.1.1.11SealEnvelopeEx164.1.1.12OpenEnvelope174.1.1.13SignData174.1.1.14SignDataEx184.1.1.15VerifySign184.1.1.16GenRandom194.1.1.17HashData194.1.1.18SymmEncrypt204.1.1.19SymmDecrypt204.1.1.20GetCertFromLDAP214.1.1.21GetAndSaveCRL214.1.1.22ReadFromFile224.1.1.23WriteToFile224.1.1.24GetStamp224.1.1.25VerifyStamp234.1.1.26GetAlgoFromPA234.1.1.27Base64Encode244.1.1.28Base64Decode244.1.1.29GetParamValue254.2服务端描述254.2.1 APP应用服务器端JAVA接口254.2.1.1 release254.2.1.2GetCurStatus254.2.1.3AdvBase64Encode264.2.1.4 AdvBase64Decode264.2.1.5AdvGetCert264.2.1.6AdvCheckCert264.2.1.7AdvGetCertInfo274.2.1.8AdvSealEnvelope284.2.1.9 AdvSealEnvelopeEx294.2.1.10 AdvOpenEnvelope304.2.1.11 AdvSignData304.2.1.12 AdvSignDataEx314.2.1.13 AdvVerifySign314.2.1.14 AdvGenRandom324.2.1.15 AdvHashData324.2.1.16 AdvSymmEncrypt334.2.1.17 AdvSymmDecrypt334.2.1.18 AdvGetCertFromLDAP344.2.1.19 AdvGetCRLFromLDAP344.2.1.20 AdvUploadCRL354.2.1.21 AdvReadFromFile354.2.1.22 AdvWriteToFile354.2.1.23 AdvGetStamp364.2.1.24 AdvVerifyStamp364.2.1.25 AdvGetAlgoFromPA364.2.1.26 AdvGetAttrCertInfo374.2.1.27 AdvGetPACertInfo374.2.1.28 AdvGetAttrCertListFromLDAP385应用开发实例395.1身份认证参考模型405.2加解密功效参考模型435.3署名验签功效参考模型441 引言1.1 编写目标该文档关键规范了PKI安全中间件功效接口定义。在整个PKI体系中，安全中间件作用很关键，它经过调用底层WHCSP及证书管理器等，封装了一系列PKI应用接口，满足上层PKI具体应用需要。本标准适适用于PKI上层应用需求，关键为CA系统。适用对象为全部采取安全中间件系统开发人员。1.2 项目背景高级密码服务，顾名思义，是为用户提供相对高级和抽象密码服务，而不是像底层CSP和硬件加密算法那样，提供比较低级和具体密码服务。通常来说，高级密码服务应该能够让不懂加密、解密和署名、验签等概念用户也能够透明使用，也就是说把密码学算法细节给屏蔽掉了。1.3 术语和缩写词缩写、术语解 释PKI公钥基础设施(Public Key Infrastructure)CSPCryptographic Service Provider（密码服务提供者）CRL证书撤消列表（ Certificate Revocation List ）一个标识一系列不再被证书公布者所信任证书署名列表（通称黑名单）。LDAP目录查询协议( Lightweight Directory Access Protocol )本设计指轻型目录访问协议LDAP。用户可使用LDAP协议，经过网络到目录服务器查询系统中证书或证书撤消列表。OCSP在线证书状态查询协议（Online Certificate Status Protocol）用户可使用OCSP协议，经过网络到OCSP服务器实时查询系统中证书目前有效/无效状态。1.4 遵照标准列出参考资料，如：l RFC 2459 PKIX PKIX证书和CRL概要l IETF： PKIX证书策略和证书实践框架l IETF：RFC 2510: CMP(证书管理协议)l RFC 2797: CMC(CMS上证书管理消息)l RFC 2511: CRMF(证书请求消息格式) l X.208 抽象语法符号1 描述(ASN.1) l X.209 抽象语法符号1 基础编码规范说明(ASN.1) l X.680 信息技术抽象语法符号1 (ASN.1)基础符号规范l X.681 信息技术抽象语法符号1 (ASN.1)信息目标规范l X.682 信息技术抽象语法符号1 (ASN.1)强制规范l X.690 信息技术ASN.1 编码规则基础编码规则(BER), 规范编码规则(CER)和关键编码规则(DER) l X.509v4 信息技术开放式系统互连目录：公钥和属性证书框架l X.500 开放式系统互连目录：概念，模型和服务概述l LDAP 轻目录访问协议：由ISO于1997年12月公布。l PKCS#1 (v1.5) RSA密码算法l PKCS#5 (v2.0) 基于口令密码标准l PKCS#6 (v1.5) 扩展数字证书语法标准l PKCS#7 (v1.5) 密文消息语法标准l PKCS#8 (v1.5) 私钥信息语法标准l PKCS#9 (v2.0) 可选择属性类型l PKCS#10 (v1.5) 数字证书申请语法标准l PKCS#11硬件密码设备接口标准l PKCS#12 (v1.0) 个人信息交换语法l PKCS#15 (v1.1) 多个应用访问标准l X.509 开放式系统互连目录：公钥和授权证书框架l ITU-T X.500 开放式系统互连目录：概念，模型和服务概述l CORBA(公共对象请求代理体系结构) v2.4 2 系统概述 在PKI体系结构中【见上图】，安全中间件总揽了证书管理器和CSP全部功效。它在PC端和PKI服务器端全部是直接面向最终用户调用接口，所以，它必需能够屏蔽掉PC端和PKI服务器端不一样情况。安全中间件是为用户提供相对高级和抽象密码服务，而不是像底层CSP和硬件加密算法那样，提供比较低级和具体密码服务。通常来说，安全中间件服务应该能够让不懂加密、解密和署名、验签等概念用户也能够透明使用，也就是说把密码学算法细节给屏蔽掉了。2.1 功效l 抽象算法服务1. 对指定明文进行加密功效，包含口令加密、对称密钥加密和公开密钥加密。2. 对指定密文进行解密功效，包含对称密钥解密和公开密钥解密。3. 对指定明文进行署名功效。4. 对指定署名进行验签功效5. 封装PKCS7数字信封6. 解开PKCS7数字信封7. 对明文进行散列。8. 产生随机数。l 抽象证书服务1. 依据标签得到证书2. 验证证书有效性3. 生成PKCS10格式证书请求文件4. 输入绑定证书和私钥。l 私钥和口令保护服务1. 检验私钥口令2. 更改私钥口令3. 检验PIN4. 更改PINl 编码服务5. ASE64编码功效6. BASE64解码功效2.2 性能精度TSP响应时间1s；OCSP响应时间1s；LDAP服务单元响应速度0.5s时间特征用户端RSA署名2次/秒验签5次/秒服务器端RSA署名20次/秒验签100次/秒灵活性能够灵活支持多个硬件介质和硬件加密卡；能够提供C/C+、Java、C#等应用接口；一套软件结构能够同时为CA和应用提供服务；能够支持33算法、RC4算法、DES/3DES算法；3 运行环境3.1 硬件系统适适用于多种PC兼容机、服务器、小型机等等3.2 支撑软件WINDOWS ，WindowsXP，LINUX（RedHat9.0及Advanced Server2.1）4 开发说明描述系统为二次开发工作提供接口、约束等。安全中间件分为用户端和服务端2部分，安全中间件用户端关键功效是在用户端经过对硬件存放介质操作完成部分密码运算。服务端关键是经过调用密码服务器为应用服务提供所需密码服务。用户端和服务端产数据格式全部采取国际同意标准。服务端能够运算用户端产生数据，用户端也能够运算服务端产生数据。关键用功效为用户端进行署名、加密，服务端验签、解密或服务端署名、加密，用户端验签、解密。用户端和服务端数据传输能够由应用开发灵活处理，但要确保在传输前后数据格式不发生改变。经过安全中间件提供抽象密码服务，为应用开发提供机密性，完整性，不可抵赖性方面支持。完成身份认证，电子印章，责任认定，密文传输等应用服务。4.1 用户端描述用户端关键设备是硬件存放介质E-Key，E-Key做为数字证书存放设备关键存放用户署名私钥，加密私钥，署名证书，加密证书。经过调用用户端控件能够使用E-Key完成署名，加密等密码服务。4.1.1APP用户端控件接口说明4.1.1.1 AtvInit功效介绍控件初始化。读取用户端证书载体信息及其它初始化工作。调用部分关键功效接口前必需先调用本接口。接口名称int AtvInit()参数说明入参说明无出参说明无返回值成功，则返回0失败，则返回错误号,错误号小于04.1.1.2 AtvEnd 功效介绍进行开发包函数库调用完成后内部存放区清除工作。接口名称int AtvEnd();参数说明入参说明无出参说明无返回值成功，则返回0失败，则返回错误号，小于04.1.1.3 SetHardWare 功效介绍设置用户端硬件设备类型。接口名称BOOL SetHardWare(long hardwareType);参数说明入参说明hardwareTypeIN：用户端硬件设备类型现在支持：1软件摸拟实现2加密卡实现3SIM卡实现4 EKEY实现出参说明无返回值成功，则返回TRUE失败，则返回FALSE4.1.1.4 Login功效介绍登录用户端硬件设备。接口名称BOOL Login(int loginType, BSTR loginPin);参数说明入参说明loginTypeIN：用户登陆类型，此处用户请输入1loginPinIN：用户登陆PIN码出参说明无返回值成功，则返回TRUE失败，则返回FALSE说明调用本接口时，假如loginPin输入为”空，则会弹出输入口令对话框；假如不为空，则不会弹出，只返回登录是否成功。4.1.1.5 ChangeLoginPin功效介绍修改用户端用户登陆PIN码。接口名称BOOL ChangeLoginPin(BSTR keyLabel,BSTR oldPasswd,BSTR newPasswd);参数说明入参说明keyLabelIN： 私钥标签，此处请传入“wellhope”oldPasswdIN： 旧用户登陆口令newPasswdIN：新用户登陆口令 出参说明无返回值成功，则返回TRUE失败，则返回FALSE4.1.1.6 Logout功效介绍退出用户端硬件登录。接口名称BOOL Logout();参数说明入参说明无出参说明无返回值成功，则返回TRUE失败，则返回FALSE4.1.1.7 GetCert功效介绍依据证书标签和证书类型读取用户端用户证书。证书标签写在配置文件中，见前面Client.conf配置文件。接口名称BSTR GetCert(int certType);参数说明入参说明certTypeIN：证书类型 1 - 加密证书 2 - 署名证书出参说明无返回值返回编码后证书信息。4.1.1.8 CheckCert功效介绍验证证书有效性。在验证过程中会连接到OCSP服务器上进行证书验证。接口名称BOOL CheckCert(BSTR i_inCert);参数说明入参说明i_inCertIN：待验证证书，已编码。出参说明无返回值成功，则返回TRUE失败，则返回FALSE4.1.1.9 GetCertInfo功效介绍解析证书信息，并以XML字符串格式返回接口名称BSTR GetCertInfo(BSTR i_inCert);参数说明入参说明i_inCertIN：待解析证书，已编码。出参说明无返回值返回采取XML标准结构证书信息。举例300000042SHA1RSACNShanghaiZhangjiangShanghai wellhope E-Bussiness Certificate AuthorityWELLHOPE自然人CA08月21日08月21日CNShanghaiZhangjiangwellhopeinfosecuser5308f34d52b7fb481752a506905e5b8a0698994dc3104fc8f7d1180912c6087dee594225d4ba1946dfad58598859d3501e59fc9cbd86b50c79b2ce09630fed4896651b54c37ae98855545c1434f9f4a15e3a15e9b09997b03af16c7465f816bfe2b1a49821a0090e283f82ebf2ed7daa2e76a5ada469a14e78108dde58ac13b826fb4.1.1.10 SealEnvelope功效介绍数字信封加密。内部处理过程是首先随机生成一对称密钥（由入口参数指定其算法或经过PA确定），然后用此对称密钥加密输入数据，最终用公钥加密产生此对称密钥。这是我们推荐一个对数据进行加密方法，因为它不仅确保了加密高效性（对称密钥快速加密），还确保了加密高强度性（公钥强加密）。此函数加密输出结果遵照PKCS#7编码标准（EnvelopedData）。接口名称BSTR SealEnvelope( BSTR i_encCert, long i_symmAlgo,BSTR i_inData);参数说明入参说明i_encCertIN： 用于加密数字证书，已编过码。i_symmAlgoIN： 信封中所用对称算法标识。取值以下： CALG_RC4 = 26625CALG_3DES = 26115CALG_33 = 9viaPA = 0，说明加密过程首先将连接到PA（策略中心）获取对应参数进行后续工作i_inDataIN： 输入原文信息，如是二进制数据则已编过码。出参说明无返回值输出已编码密文结果。4.1.1.11 SealEnvelopeEx功效介绍用多证书批量生成数字信封。此函数加密输出结果遵照PKCS#7编码标准（EnvelopedData）。接口名称BSTR SealEnvelopeEx(BSTR i_encCert, long i_certsize, long i_symmAlgo, BSTR i_inData);参数说明入参说明i_encCertIN： 用于加密数字证书，已编过码,多个证书间以“”隔开。i_certsizeIN： 保留参数i_symmAlgoIN： 信封中所用对称算法标识。CALG_RC4 = 26625CALG_3DES = 26115CALG_33 = 9viaPA = 0，说明加密过程首先将连接到PA（策略中心）获取对应参数进行后续工作i_inDataIN： 输入原文信息，如是二进制数据则已编过码。出参说明无返回值输出已编码密文结果。4.1.1.12 OpenEnvelope功效介绍解析数字信封私钥标签在配置文件中定义，运行时弹出输入框提醒用户输入私钥保护口令。接口名称BSTR OpenEnvelope(BSTR i_inData);参数说明入参说明i_inDataIN： 输入已编码信封数据。出参说明无返回值输出原文信息, 如是二进制数据则已编过码。4.1.1.13 SignData功效介绍对输入数据进行数字署名。私钥标签在配置文件中定义，运行时弹出输入框提醒用户输入私钥保护口令。接口名称BSTR SignData(BSTR i_inData,int i_algoType,int i_signType);参数说明入参说明i_inDataIN：输入待署名数据，二进制数据需要做编码处理。i_algoTypeIN：署名算法取值如：32772 - sha1RSA32771 - md5RSAsha1RSA、md5RSA说明署名采取是何种摘要算法署名算法i_signTypeIN：署名值类型取值：0不包含原文纯署名 1包含原文PKCS7格式数据出参说明无返回值输出已编码署名数据。4.1.1.14 SignDataEx功效介绍对输入数据进行数字署名。私钥标签在配置文件中定义，运行时弹出输入框提醒用户输入私钥保护口令。接口名称BSTR SignData(BSTR i_sigCert,BSTR i_inData,int i_algoType,int i_signType);参数说明入参说明i_sigCertIN：通信对方证书，当需要经过PA获取署名算法时需输入i_inDataIN：输入待署名数据，二进制数据需要做编码处理。i_algoTypeIN：署名算法取值如：32772 - sha1RSA32771 - md5RSA0 -viaPA等sha1RSA、md5RSA说明署名采取是何种摘要算法署名算法viaPA = 0，说明署名过程首先将连接到PA（策略中心）获取对应参数进行后续工作i_signTypeIN：署名值类型取值：0不包含原文纯署名 1包含原文符合PKCS7格式数据出参说明无返回值输出已编码署名数据。4.1.1.15 VerifySign功效介绍对输入数据进行数字署名验证接口名称BOOL VerifySign( BSTR i_checkCert, BSTR i_clearText,BSTR i_signature,int i_algoType,int i_signType);参数说明入参说明i_checkCert IN：验证所用证书。i_clearText IN：署名原文。如署名值包含原文，置空即可。i_signature IN：待验证署名数据。i_algoTypeIN：署名算法。如署名值不符合PKCS7标准，需要输入署名算法。取值如：32772 - sha1RSA32771 - md5RSA0 -viaPA等sha1RSA、md5RSA说明署名采取是何种摘要算法署名算法viaPA参数说明署名过程将连接到PA（策略中心）获取对应署名参数进行后续工作。i_signTypeIN：署名值类型取值：0不包含原文（纯署名值）1包含原文符合PKCS7格式数据出参说明无返回值TRUE：成功FALSE：失败说明现在使用方法是：当验证纯署名值时，需要输入署名算法或经过策略解析器获取匹配算法；当验证PKCS7格式署名内容时，因为本身自带了署名算法，所以没有必需再次调用对应策略解析器了。4.1.1.16 GenRandom功效介绍生成一定长度随机数/对称密钥。接口名称BSTR GenRandom(int len);参数说明入参说明lenIN： 指定长度（字节数）。出参说明无返回值输出已编码随机数/对称密钥。4.1.1.17 HashData功效介绍对输入数据进行哈希运算。接口名称BSTR HashData( int hashAlgo,BSTR inData );参数说明入参说明hashAlgoIN： 哈希算法标识 ALGO_SHA1 32772 ALGO_MD5 32771inDataIN： 输入数据信息，如是二进制数据则已编码。出参说明无返回值返回编码后哈希值。4.1.1.18 SymmEncrypt功效介绍用指定产生对称密钥KEY来加密数据。接口名称BSTR SymmEncrypt(long i_symmAlgo,BSTR i_symmkey,BSTR i_indata);参数说明入参说明i_symmAlgoIN： 对称算法标识。 比如： CALG_RC4 = 26625CALG_3DES = 26115CALG_33 = 9i_symmKeyIN： 对称密钥，已编码。i_inDataIN： 输入原文，二进制数据流先编码。出参说明无返回值输出已编码后密文。4.1.1.19 SymmDecrypt功效介绍用指定产生对称密钥KEY来解密密文数据。接口名称BSTR SymmDecrypt(long i_symmAlgo,BSTR i_symmkey,BSTR i_indata);参数说明入参说明i_symmAlgoIN： 对称算法标识。 比如： CALG_RC4 = 26625CALG_3DES = 26115CALG_33 = 9i_symmKeyIN： 对称密钥，已编码。i_inDataIN： 输入密文，已编码。出参说明无返回值输出解密后原文，如是二进制数据则已编码。4.1.1.20 GetCertFromLDAP功效介绍从LDAP服务器查询和获取用户证书。接口名称BSTR GetCertFromLDAP(long i_searchType, long i_certType, BSTR i_searchValue);参数说明入参说明i_searchTypeIN： 查找类型 取值范围为 1 按用户ID查询 2 按用户邮件地址查询 3 按证书ID查询i_certTypeIN： 证书类型 取值范围为 1 加密证书 2 署名证书 此参数对于按证书ID查询无效i_searchValueIN： 查询字符串信息 当searchType取值为1时,此参数为用户ID字符串 当searchType取值为2时,此参数为用户邮件字符串当searchType取值为3时,此参数为证书ID字符串出参说明无返回值输出已编码后证书信息。4.1.1.21 GetAndSaveCRL功效介绍从LDAP服务器获取CRL列表信息，并保留在当地。写入文件路径在注册表中指定。HKEY_LOCAL_MACHINESOFTWAREwellhopesettingCRLSettingCRLData=C:WINNTSystem32CRLDATA.crl接口名称BOOL GetAndSaveCRL();参数说明入参说明无出参说明无返回值TRUE：成功FALSE：失败4.1.1.22 ReadFromFile功效介绍从当地读取文件内容。接口名称BSTR ReadFromFile(BSTR fileName);参数说明入参说明fileNameIN： 要读取文件全路径名。假如为”空，则弹出文件选择对话框。出参说明无返回值输出已编码过文件数据信息4.1.1.23 WriteToFile功效介绍将数据写入到当地文件。接口名称BOOL WriteToFile(BSTR fileNameBSTR writeData);参数说明入参说明fileNameIN： 要保留文件名称writeDataIN： 要写入文件数据，已编码。出参说明无返回值TRUE：成功FALSE：失败4.1.1.24 GetStamp功效介绍对输入数据加盖时间戳。接口名称BSTR GetStamp(BSTR inData);参数说明入参说明inDataIN： 要加盖时间戳数据，如是二进制数据则已编码。出参说明无返回值返回已编码盖戳数据。4.1.1.25 VerifyStamp功效介绍验证时间戳，假如成功返回盖戳时间。接口名称BSTR VerifyStamp(BSTR inData,BSTR inStampData)参数说明入参说明inDataIN： 加盖时间戳原文数据，如是二进制数据则已编码。inStampDataIN： 时间戳署名数据出参说明无返回值返回盖戳时间字符串。日期格式：03 09 02 17 27 30 年 月 日时 分 秒4.1.1.26 GetAlgoFromPA功效介绍经过策略解析器从PA获取通信双方对应策略证书，并加以匹配，确定通信过程中使用具体算法。接口名称long GetAlgoFromPA(BSTR ownerCert,BSTR otherCert,int algoKind,int priorityKind);参数说明入参说明ownerCertIN：自己证书otherCertIN：对方证书algoKindIN：要获取密码算法种类1 表示非对称算法2 表示对称算法3 表示摘要算法以后能够扩充priorityKindIN：通信双方所属机构在通信中算法集匹配时优先等级0对方优先级高0优先级相等0自已优先级高出参说明无返回值具体算法对应值9表示CALG_3326625表示CALG_RC426115表示CALG_3DES32772表示ALGO_SHA1 32771表示ALGO_MD5 100表示ALGO_RSA 101表示ALGO_ECC0表示没有匹配算法，无法进行对应通信4.1.1.27 Base64Encode功效介绍对输入数据进行编码接口名称BSTR Base64Encode(BSTR inData)参数说明入参说明inData IN：要编码数据出参说明无返回值返回编码值4.1.1.28 Base64Decode功效介绍对输入数据进行解码。接口名称BSTR Base64Decode(BSTR inData)参数说明入参说明inData IN：要解码数据出参说明无返回值返回解码后原文4.1.1.29 GetParamValue功效介绍从配置文件（C:ConfigClient.conf）中获取相关配置信息。接口名称BSTR GetParamValue(BSTR paramKey);参数说明入参说明paramKeyIN：要查找键名出参说明无返回值返回对应键键值4.2 服务端描述4.2.1 APP应用服务器端JAVA接口4.2.1.1 release 功效介绍进行开发包函数库调用完成后内部存放区清除工作。接口名称boolean release();参数说明入参说明无出参说明无返回值成功：true失败：false4.2.1.2GetCurStatus功效介绍得到目前状态代码。接口名称int GetCurStatus();参数说明入参说明无出参说明无返回值返回目前状态代码。4.2.1.3AdvBase64Encode功效介绍对二进制数据进行BASE64编码。接口名称String AdvBase64Encode(byte i_inData);参数说明入参说明i_inDataIN： 要编码二进制数据出参说明无返回值输出已编码数据。4.2.1.4 AdvBase64Decode功效介绍对BASE64编码数据解码。接口名称byte AdvBase64Decode(String i_inData);参数说明入参说明i_inDataIN：要解码BASE64编码数据出参说明无返回值输出解码后二进制数据。4.2.1.5AdvGetCert功效介绍依据证书标签和证书类型读取服务器证书。证书标签写在配置文件中，见前面Client.conf配置文件。接口名称String AdvGetCert(int certType);参数说明入参说明certTypeIN：证书类型 1 - 加密证书 2 - 署名证书出参说明无返回值返回编码后证书信息。4.2.1.6AdvCheckCert功效介绍验证证书有效性。在验证过程中经过当地CRL列表进行证书验证。接口名称boolean AdvCheckCert(String i_inCert);参数说明入参说明i_inCertIN：待验证证书，已编码。出参说明无返回值成功：true失败：false4.2.1.7AdvGetCertInfo功效介绍解析证书信息，并以XML字符串格式返回接口名称String AdvGetCertInfo(String i_inCert);参数说明入参说明i_inCertIN：待解析证书，已编码。出参说明无返回值返回