businesstoolkit程序员手册_v2.00 18页

Business-ToolKit程序员手册V2.00吉大正元信息技术股份有限公司JilinUniversityInformationTechnologiesCo.,Ltd.n1引言31.1概述31.2开发平台及编程语言31.3运行环境31.4注意事项41.5名词解释42系统结构43常量定义44数据结构55接口说明65.1连接配置类（ConnConfig）75.2业务处理类(Business)85.3请求消息(Request)95.4应答消息(Response)95.5提交证书申请请求(GenReqRequest)105.6提交证书申请应答(GenReqResponse)115.7提交证书下载请求(SCertDownloadRequest)115.8提交证书下载应答(SCertDownloadResponse)125.9提交证书更新申请请求(CertUpdateAddRequest)135.10提交证书更新申请应答(CertUpdateAddResponse)145.11提交注销申请请求(CertRevokeAddRequest)145.12提交注销申请应答(CertRevokeAddResponse)155.13证书冻结申请请求(CertHoldAddRequest)165.14证书冻结申请应答(CertHoldAddResponse)165.15证书解冻申请请求(CertUnholdAddRequest)175.16证书解冻申请应答(CertUnholdAddResponse)18n1引言1.1概述Business-ToolKit作为开发工具包实现应用系统与RAServer之间的服务通信，包括对服务请求信息的封装，与RAServer建立SSL连接，解释由RAServer返回的应答消息等功能。Business-ToolKit是供嵌入到应用系统中进行证书及用户管理业务开发的API，提供基本证书管理功能和用户管理功能。该开发接口的作用范围为与RAServer交互的RA相关业务请求/应答部分，其他具体应用业务不属于此接口支持范围（需要业务以用系统本身的业务规则来规划设计）。产品形态如下：RAServer业务应用ServerBusiness-ToolKitBusiness-ToolKit功能列表：Ø证书申请Ø证书注销1.2开发平台及编程语言开发平台：WindowsXP+SP2编程语言：JAVA1.3运行环境软件运行环境：JDK1.5及其后更高版本n1.1注意事项ØAPI内部使用的所有关键标识都有相应的常量定义，请使用程序内的常量作为标识。Ø为方便错误定位和调试，API对内部发生的异常全部向上抛出。1.2名词解释JKSJavaKeyStore，JCE中普遍使用的一种JAVA存储密钥的格式，内部可以存储证书列表及对应的私钥，可以使用JDK中自带的keytool工具进行操作和管理。2系统结构Business-ToolKit开发包主要包含以下主要部分：Øcn.com.jit.ida.ra.cert.service.*;负责组织证书管理服务的请求数据包。Øcn.com.jit.ida.response.*;负责解释RAServer返回的响应数据包。Øcn.com.jit.ida.ra.btoolkit.Business;负责业务处理Øcn.com.jit.ida.ra.btoolkit.ConnConfig.;负责连接配置3常量定义常量名称值证书状态标识CERT_STATUS_USEUseCERT_STATUS_REVOKERevokeCERT_STATUS_HOLDHoldCERT_STATUS_UNDOWNUndownCERT_STATUS_UNDOWN_REVOKEUndownRevoke证书状态显示CERT_STATUS_USE_ZH使用中CERT_STATUS_REVOKE_ZH注销CERT_STATUS_HOLD_ZH冻结CERT_STATUS_UNDOWN_ZH未下载CERT_STATUS_UNDOWN_REVOKE_ZH未下载注销证书注销原因RVK_UNSPECIFIED0nRVK_KEY_COMPROMISE1RVK_CA_COMPROMISE2RVK_AFFILIATION_CHANGED3RVK_SUPERSEDED4RVK_CESSATION_OF_OPERATION5RVK_CERTIFICATE_HOLD6RVK_REMOVE_FROM_CRL8注销原因描述RVK_DES_UNSPECIFIED未指明原因RVK_DES_KEY_COMPROMISE密钥泄密RVK_DES_CA_COMPROMISECA泄密RVK_DES_AFFILIATION_CHANGED从属关系改变RVK_DES_SUPERSEDED证书被取代RVK_DES_CESSATION_OF_OPERATION操作终止RVK_DES_REMOVE_FROM_CRL从CRL删除证书申请状态标识APPLY_STATUS_NOTAUDIT1APPLY_STATUS_AUDITED2APPLY_STATUS_NOTPASS3APPLY_STATUS_CAREFUSE4APPLY_STATUS_AUDITED_WITHOUTEXE6证书申请状态显示APPLY_STATUS_NOTAUDIT_ZH未审核APPLY_STATUS_AUDITED_ZH已审核APPLY_STATUS_NOTPASS_ZH审核未通过APPLY_STATUS_CAREFUSE_ZHCA拒绝申请APPLY_STATUS_AUDITED_WITHOUTEXE_ZH已审核未执行1数据结构Request{operatorOperator;operationString;}Response{nerrString;msgString;detailArrayList;}GenReqRequest{subjectString;ctmlNameString;notBeforeString;validityString;userinfoIdString;certTypeString;organIdString;doubleFlagString;userMapProperties;}GenReqResponse{refcodeString;authcodeStirng;}CertRevokeAddRequest{certSNString;revokeReasonString;revokeDescString;}CertRevokeAddResponse{}1接口说明Business-ToolKit使用方法简介：1、构造ConnConfig类实例并为其配置与RAServer连接所需的各项参数信息；2、用已初始化好的ConnConfig实例构造Business类实例；3、构造具体的服务请求信息Request实例并设置其内部请求参数；4、调用Business实例的doBusiness(Requestrequest)方法向RAServer发出服务请求并接受响应结果(Response)；5、使用Response基类还原具体的响应数据包并解析其返回信息内容。n所有证书管理服务都有具体对应的Request和Response子类，通过这些子类构造服务请求信息和解析应答信息。使用ConnConfig配置Business-ToolKit与RAServer的连接配置信息。使用Business业务受理类发送服务处理请求并接受响应信息。服务端响应消息的头信息errorCode(错误码)和errorMsg(错误描述)标识业务受理结果，如果业务受理成功，则错误码为”0”，错误描述为”SUCCESS”，如果业务受理失败，则返回相应的错误码和错误描述，并且在detail中可能包含错误的历史信息。1.1连接配置类（ConnConfig）声明：PublicConnConfig()系统默认构造函数，对内部所有属性进行初始化功能：配置Business-ToolKit与RAServer的连接信息，设置RAServer的IP地址、服务端口以及建立SSL安全通信连接所需要的服务端证书内容和客户端私钥内容等信息。属性：serverIPRAServerIP地址serverPortRAServer服务端端口userKeyPath用户私钥文件路径(JKS格式)userKeyPassword用户私钥解密口令cfgNamecfg文件路径deviceID加密类型，加密库类型目前支持"JSOFT_LIB""JSJY05B_LIB"hardDriver加密机驱动dll路径方法：对内部所有属性提供相应的getter方法setServer(StringserverIP,intserverPort)设置RAServer地址信息setUserKeyFile_JKS(byte[]userKey,char[]userKeyPassword)设置用户私钥文件路径(JKS格式)注释：目前信任根证和用户私钥必须为JKS格式的，对其他格式暂不支持；如果是其他格式，可以手动转换成JKS格式。设置信任的根证书不需要解密口令。应用实例：//设置连接属性nConnConfigconnConfig=newConnConfig();//设置RAServer的IP地址和服务端口connConfig.setServer(“127.0.0.1”,“40625”);//设置用户私钥（用户私钥的.JKS文件中包含信任的根证书）connConfig.setUserKeyFile_JKS(“c:/userKey.jks”,“11111111”.toCharArray());……1.1业务处理类(Business)声明：PublicBusiness(ConnConfigconnConfig)通过以构造好的连接信息配置类构造业务处理服务功能：与RAServer建立SSL安全通信连接，发送客户端服务请求信息，接受RAServer返回的服务应答消息。属性：connConfig与RAServer的连接配置信息，根据此配置信息建立与RAServer的连接。方法：ResponsedoBusiness(Requestrequest);向RAServer发送服务请求信息，并返回从RAServer获得的服务应答消息。注释：doBusiness方法中的参数Request和返回值Response都是请求和应答消息的基类。通常使用方法是构造具体服务请求信息的子类，调用doBusiness方法向RAServer发送请求并获得响应Response，然后使用基类Response构造具体的服务应答消息子类并解析应答内容。应用实例：//设置证书请求信息CertReRequestcertReqRequest=newCertReqRequest();certReqRequest.setCertDN(……);……//设置证书申请信息其他内容//设置连接属性ConnConfigconnConfig=newConnConfig();connConfig.setServer(“192.168.9.145”,“30859”);connConfig.setUserKeyFile_JKS(“c:/userKey.jks”,“11111111”.toCharArray());connConfig.setDeviceID("JSOFT_LIB");connConfig.setCfgName(……);connConfig.setHardDriver(…..);//执行业务受理Businessbusiness=newBusiness(connConfig);Responseresponse=business.doBusiness(certReqRequest);n//构造具体的业务响应信息CertReqResponsecertReqResponse=newCertReqResponse(response);//获得参考码和授权码StringrefCode=certReqResponse.getRefCode();StringauthCode=certReqResponse.getAuthCode();1.1请求消息(Request)声明：publicRequest()系统默认构造函数，对内部属性进行初始化功能：Request为所有请求信息的基类。内部包含操作员，操作类型，请求体内容信息。属性：operator操作员对象operation操作类型方法：对内部所有属性提供相应的getter/setter方法注释：Request为所有具体请求信息类的基类，下面描述的所有请求信息都由此类派生。在实际应用中应使用具体的请求信息子类来申请服务。应用实例：基类对象，不实际使用1.2应答消息(Response)声明：publicResponse()系统默认构造函数，对内部所有属性进行初始化功能：Responset为所有应答信息的基类。内部包含错误码，错误描述，错误历史，应答包信息。其中当业务处理成功时错误码为0，错误描述为SUCCESS。属性：err错误码msg错误描述detail错误历史方法：对内部所有属性提供相应的getter/setter方法注释：nResponse为所有具体应答消息类的基类，下面描述的所有应答都由此类派生。在实际应用中应将获得的Response积累转换为具体的应答消息子类，从子类中获取应答信息。其中当业务处理成功时错误码为0，错误描述为SUCCESS。应用实例：基类对象，不实际参与作用1.1提交证书申请请求(GenReqRequest)声明：publicGenReqRequest()系统默认构造函数，对内部属性进行初始化功能：组织提交证书申请请求信息，如果申请证书的模板审核策略为自动审核则直接实现证书申请操作。属性：subject证书主题ctmlName模板名称notBefore证书生效时间"yyyyMMddHHmmssSSS"validity证书有效期userinfoId用户信息IDcertType证书类型，个人用户or企业用户organId机构IDuserMap用户信息方法：对内部所有属性提供相应的getter/setter方法注释：通常使用方法是由业务服务类Business获得的基类Response构造子类应答消息对象。应用实例：GenReqRequestcertAppAddReq=newGenReqRequest();certAppAddReq.setUserMap(UserMapValue);certAppAddReq.setCertType("userinfo");certAppAddReq.setSubject(certSubject);certAppAddReq.setValidate("360");certAppAddReq.setOrganID("001");ncertAppAddReq.setCtmlName("通用证书模板");……1.1提交证书申请应答(GenReqResponse)声明：publicGenReqResponse()系统默认构造函数，对内部所有属性进行初始化功能：与GenReqRequest对应的提交证书申请应答消息，解析证书申请应答消息内容属性：refcode证书参考码authcode证书授权码方法：对内部所有属性提供相应的getter/setter方法注释：通常使用方法是由业务服务类Business获得的基类Response构造子类应答消息对象应用实例：//获得服务端返回的应答消息Responseresponse=(Response)connector.doBusiness(certAppAddReq);//构造证书申请应答消息GenReqResponsecertAppAddResp=(GenReqResponse)response;//获得参考码和授权码StringrefCode=certAppAddResp.getRefcode();StringauthCode=certAppAddResp.getAuthCode();1.2提交证书下载请求(SCertDownloadRequest)声明：publicSCertDownloadRequest()系统默认构造函数，对内部属性进行初始化功能：组织证书下载请求信息。属性：authCode证书授权码refCode证书参考码p10证书P10申请书内容n方法：对内部所有属性提供相应的getter/setter方法注释：应用实例：SCertDownloadRequestcertMakeRequest=newSCertDownloadRequest();//设置授权码certMakeRequest.setAuthCode(authcode);certMakeRequest.setRefCode(certSN);certMakeRequest.setP10(P10);……1.1提交证书下载应答(SCertDownloadResponse)声明：publicSCertDownloadResponse()系统默认构造函数，对内部所有属性进行初始化功能：与SCertDownloadRequest对应的证书下载申请应答消息，解析证书下载申请应答消息内容属性：certSN证书序列号p7bp7b证书链pfxPFX私钥文件useKMC标识是否由KMC产生密钥(TRUE--由KMC产生密钥.NULL或其他--非KMC产生密钥)encryptedSessionKey被加密的对称密钥sessionKeyAlg对称密钥所使用的加密算法sessionKeyPad对称密钥加密向量encryptedPrivateKey被加密的私钥方法：对内部所有属性提供相应的getter/setter方法n注释：应用实例：SCertDownloadResponsecertMakeResponse=(SCertDownloadResponse)response;Stringp7b=certMakeResponse.getP7b();StringdoubleP7b=certMakeResponse.getDoubleP7b();StringencryptedPrivateKey=certMakeResponse.getEncryptedPrivateKey();StringencryptedSessionKey=certMakeResponse.getEncryptedSessionKey();StringpfxValue=certMakeResponse.getPfx();StringcertMakeResponse.getSessionKeyAlg();StringuseKMC=certMakeResponse.getUseKMC();……1.1提交证书更新申请请求(CertUpdateAddRequest)声明：publicCertUpdateAddRequest()系统默认构造函数，对内部属性进行初始化功能：组织提交更新申请请求信息。属性：certSN证书序列号subject证书新主题ctmlName证书模板名称notBefore证书生效时间notAfter证书失效时间validity证书有效期retainKey更新证书时是否保持原有密钥方法：对内部所有属性提供相应的getter/setter方法n注释：证书有效期策略同证书申请应用实例：CertUpdateAddRequestcertUpdateAddRequest=newCertUpdateAddRequest();//证书序列号certUpdateAddRequest.setCertSN(certSN);certUpdateAddRequest.setSubject(newDN);//取证书模板名称，用于模板BASEDN校验certUpdateAddRequest.setCtmlName(“通用证书模板”);……1.1提交证书更新申请应答(CertUpdateAddResponse)声明：publicCertUpdateAddResponse()系统默认构造函数，对内部所有属性进行初始化功能：与CertUpdateAddRequest对应的提交更新申请应答消息，解析提交更新申请应答消息内容属性：refcode证书参考码authcode证书授权码方法：对内部所有属性提供相应的getter/setter方法注释：应用实例：CertUpdateAddResponsecertUpdateAddResponse=(CertUpdateAddResponse)response;StringauthCode=certUpdateAddResponse.getAuthcode());StringrefCode=certUpdateAddResponse.getRefcode());……1.2提交注销申请请求(CertRevokeAddRequest)声明：publicCertRevokeAddRequest()系统默认构造函数，对内部属性进行初始化n功能：组织提交注销证书申请请求信息。属性：revokeReason注销原因revokeDesc注销描述certSN证书序号方法：对内部所有属性提供相应的getter/setter方法注释：应用实例：CertRevokeAddRequestcertRevAddReq=newCertRevokeAddRequest();certRevAppAddReq.setCertSN(certsn);certRevAddReq.setRevokeDesc(“注销描述”);certRevAddReq.setRevokeReason(0);……1.1提交注销申请应答(CertRevokeAddResponse)声明：publicCertRevokeAddResponse()系统默认构造函数，对内部所有属性进行初始化功能：与CertRevokeAddRequest对应的提交注销申请应答消息，解析提交注销申请应答消息内容属性：无此子类独立属性，使用RABaseResponse中属性足够方法：对内部所有属性提供相应的getter/setter方法注释：应用实例：CertRevokeAddResponsecertRevAddResp=(CertRevokeAddResponse)response;S……n1.1证书冻结申请请求(CertHoldAddRequest)声明：publicCertHoldAddRequest()系统默认构造函数，对内部属性进行初始化功能：组织提交冻结证书申请请求信息。属性：certSN证书序列号ctmlName模板名称Subject证书主题notNow是否延迟操作days延迟天数holdDESC冻结描述方法：对内部所有属性提供相应的getter/setter方法注释：应用实例：CertHoldAddRequestcertHoldAddRequest=newCertHoldAddRequest();certHoldAddRequest.setSubject(certDN);certHoldAddRequest.setCertSN(certSN);certHoldAddRequest.setCtmlName(ctmlName);certHoldAddRequest.setNotNow(false);certHoldAddRequest.setHoldDesc(“冻结描述”);……1.2证书冻结申请应答(CertHoldAddResponse)声明：publicCertHoldAddResponse()系统默认构造函数，对内部所有属性进行初始化功能：与CertHoldAddRequestn对应的提交冻结申请应答消息，解析提交冻结申请应答消息内容属性：无此子类独立属性，使用RABaseResponse中属性足够方法：对内部所有属性提供相应的getter/setter方法注释：应用实例：CertHoldAddResponsecertholdAddResp=(CertHoldAddResponse)response;Stringreqsn=certholdAddResp.getReqSN();……1.1证书解冻申请请求(CertUnholdAddRequest)声明：publicCertUnholdAddRequest()系统默认构造函数，对内部属性进行初始化功能：组织提交解冻申请请求信息。属性：certSN证书序列号ctmlName模板名称Subject证书主题notNow是否延迟操作days延迟天数方法：对内部所有属性提供相应的getter/setter方法注释：应用实例：CertUnholdAddRequestcertUnholdAddRequest=newCertUnholdAddRequest();certUnholdAddRequest.setSubject(certDN);certUnholdAddRequest.setCertSN(certSN);ncertUnholdAddRequest.setCtmlName(ctmlName);certUnholdAddRequest.setNotNow(false);……1.1证书解冻申请应答(CertUnholdAddResponse)声明：publicCertUnholdAddResponse()系统默认构造函数，对内部所有属性进行初始化功能：与CertUnholdAddRequest对应的提交解冻申请应答消息，解析提交解冻申请应答消息内容属性：无此子类独立属性，使用RABaseResponse中属性足够方法：对内部所有属性提供相应的getter/setter方法注释：应用实例：CertUnholdAddResponsecertUnholdAddResponse=(CertUnholdAddResponse)response;Stringreqsn=certUnholdAddResponse.getReqSN();……