JIT应用ToolkitsAPI（Java版）程序员手册精品资料.doc

JIT应用Toolkits API（Java版）程序员手册JIT应用Toolkits API（Java版）程序员手册JIT版权所有(2001)吉 大 正 元 信 息 技 术 股 份 有 限 公 司Jilin University Information Technologies Co., Ltd.目 录1引言41.1概述41.2开发平台及编程语言41.3注意事项41.4名词解释42系统结构42.1接口说明42.2配置文件说明43数据结构53.1基于口令产生密钥的基本信息53.2初始化CRL参数53.3时间基本信息63.4证书有效期类73.5初始化证书信息74全局常量定义84.1标识常量84.1.1所用到的配置文件84.1.2文件长度及密码长度84.1.3数据类型定义;84.1.4信封类型定义84.1.5证书扩展类型定义94.1.6证书用户类型定义94.1.7证书状态定义94.1.8CRL验证证书方式94.1.9证书SN类型94.1.10证书存储方式104.1.11加密、解密、签名 等算法104.1.12标准扩展域104.2错误代码115函数说明135.1类JIT_Engine135.1.1构造函数135.1.2获取错误信息145.1.3释放引擎资源145.2类JIT_OCSP145.2.1构造方法145.2.2查询证书状态155.2.3获取错误信息165.2.4释放OCSP资源165.3类JIT_CRL165.3.1构造方法175.3.2获取CRL验证证书的方式getMode175.3.3CRL验证证书185.3.4验证CRL签名185.3.5获取错误信息195.3.6释放CRL资源195.4类JIT_Certificate195.4.1构造方法195.4.2获取证书中eMail215.4.3获取证书颁发者225.4.4获取证书序列号225.4.5获取证书主题225.4.6获取证书版本号235.4.7获取证书有效期235.4.8获取证书的应用类型235.4.9获取证书编码(二进制)245.4.10获取证书的个人身份标识码245.4.11提取所需对象标识符对应的内容255.4.12验证证书的有效性265.4.13验证证书的有效性（手工输入时间）265.4.14获取错误信息275.4.15释放Certificate资源275.4.16扩展接口285.5类JIT_Key295.5.1构造方法295.5.2产生对称密钥295.5.3基于口令产生对称密钥305.5.4包装密钥305.5.5解包装密钥315.5.6获取错误信息315.5.7释放Key资源325.6类JIT_Bin325.6.1构造方法325.6.2数据数字签名325.6.3验证数字签名335.6.4数据非对称加密345.6.5数据非对称解密355.6.6产生数据的MAC355.6.7验证数据的MAC365.6.8数据文摘375.6.9数据对称加密385.6.10数据对称解密385.6.11产生PKCS7数字信封395.6.12验证PKCS7数字信封425.6.13二进制数据转换成PEM编码445.6.14获取错误信息445.6.15释放bin资源455.7类JIT_Base64455.7.1构造方法455.7.2数据数字签名455.7.3验证数字签名465.7.4数据非对称加密475.7.5数据非对称解密485.7.6数据产生MAC485.7.7验证数据的MAC495.7.8数据文摘505.7.9数据对称加密515.7.10数据对称解密515.7.11产生PKCS7数字信封525.7.12验证PKCS7数字信封545.7.13PEM编码转换成二进制575.7.14获取错误信息575.7.15释放Base64资源575.8类JIT_EnvFile585.8.1构造方法585.8.2产生PKCS7数字信封文件585.8.3验证PKCS7数字信封文件615.8.4获取错误信息625.8.5释放EnvFile资源625.9类JIT_LDAP625.9.1构造方法625.9.2获取用户证书635.9.3释放获取的证书645.9.4获取错误信息645.9.5释放Ldap资源645.10类JIT_Random655.10.1创造随机数651 引言1.1 概述Ø JIT Toolkit_API（Java版）是以吉大正元电子证书认证系统为基础，方便用户进行二次开发，整合先进的Java技术，提供的工具包。用户利用工具包中各种接口可以作电子证书系统客户化，电子证书应用等方面的开发工作。主要功能如下：u 对客户和服务器证书的操作（包括验证和获取证书内容）u 对用户数据的操作（包括签名、加密、数字信封和他们相对应的校验工作）u 对用户文件的各种操作（包括封装数字信封和验证数字信封）u 各种辅助操作（包括对对称密钥的操作、产生随机数、）u 对Ldap、CRL、OCSP等各种辅助功能的操作1.2 开发平台及编程语言n 开发平台Windows 2000 Servern 编程语言JavaC+n 开发工具Java 2 SDK Standard Edition v1.3.1_09（Sun Microsystems, Inc.）Borland Jbuilder 7 EnterpriseMicrosoft Visual C+ 6.0 Enterprise Edition1.3 注意事项n 系统中的错误码均为负数。n 本接口不支持加密机，除windwos外不支持key使用n 除windows外不支持OCSP1.4 名词解释无2 系统结构2.1 接口说明JIT应用Toolkits API（Java版）对用户提供10个类共70个接口：n jit.toolkitsToolkits主要功能类。提供各对外接口。n jit.parameters结构。用于存放程序中各种用到的结构体。2.2 配置文件说明JIT 应用Toolkits API（JNI版）共需要5个配置文件，说明如下：n cryptodevice.ini加密设备配置文件。文件证书使用时修改DeviceCount对应软加密库ID，DeviceCount =1Key证书使用时修改DeviceCount对应Key的IDDeviceCount =2两种证书同时使用时修改DeviceCount对应Key的IDDeviceCount =2n MultiDeviceFile.ini管理员证书介质使用JPF文件时使用此配置文件。（无论那种情况该文件必须存在）n MultiDeviceCard.ini管理员证书介质使用USB Key时使用此文件。（无论那种情况该文件必须存在）n card.iniUSB Key的配置文件，通常不需要用户改动。n jitocsp.ini与OCSP服务器连接时需要的一些连接参数，用户可根据实际情况进行改动n jcaapi.ini与Ldap服务器连接时需要的一些连接参数，用户可根据实际情况进行改动3 数据结构3.1 基于口令产生密钥的基本信息类名称：JIT_PBE_PARAMS功能：存储PKCS5基于口令产生密钥的参数。声明：public class JIT_PBE_PARAMS public byte sPassword; public byte bSalt; public int lIteration;public JIT_PBE_PARAMS() 数据成员：pPassword 口令的内容。pSalt盐值的内容。（PKCS5基于口令产生密钥的协商好的附加信息）nIterationPKCS5基于口令密钥产生的循环叠代次数。3.2 初始化CRL参数类名称：JIT_CRLPARAM功能：存储初始化CRL的参数。声明：public class JIT_CRLPARAM public byte szCRLFile; public int nMode; public JIT_CRLPARAM() 数据成员：szCRLFile 用户指定的CRL文件路径。这个路径必须是绝对路径。这个路径不能为NULL。在线方式验证，这个路径是下载的CRL存储在本地的CRL文件路径。离线方式验证，这个路径是验证证书时使用的CRL文件路径。nMode通过CRL验证证书的方式。包括在线方式验证和离线方式验证。在线方式验证设置为VERIFY_MODE_ONLINE离线方式验证设置为VERIFY_MODE_OFFLINE3.3 时间基本信息类名称：JIT_Time功能：存储证书中时间的值声明： public class JIT_Timepublic long lType; public long diffGMT; public long year; public long month; public long day; public long hour; public long min; public long second;public JIT_Time() 数据成员：lType 证书中时间的编码类型。1：格林威治时间 2：本地时间diffGMT 本地时间和格林威治时间的差值。本地时间比格林威治时间早用负数表示。本地时间比格林威治时间晚用正数表示。0表示格林威治时间。year 本地时间年month本地时间月day 本地时间日hour本地时间时min 本地时间分second本地时间秒3.4 证书有效期类类名称：JIT_Valid功能：存储证书的有效期声明：public class JIT_Validpublic JIT_Time notBeforpublic JIT_Time notAfterpublic JIT_Valid() 数据成员：notBefor证书有效期开始的时间notAfter证书有效期结束的时间3.5 初始化证书信息类名称：JIT_CERTDEVPARAM（保留未用）功能：存储了从非数据流形式初始化证书时所需要的信息声明： public class JIT_CERTDEVPARAM public byte szDevInfo; public byte szPWD; public JIT_CERTDEVPARAM() 数据成员：szDevInfo 描述证书存储的描述串。描述串由两部分组成。第一部分是存储介质描述符，第二部分是证书存储路径。存储介质描述符：“file:/”表示证书的存储介质是磁盘。“usb:/”表示证书的存储介质是USB接口设备。“com1:/”表示证书的存储介质是COM接口设备。证书存储路径：表示证书存储的位置和名字例如：“file:/d:mycert.jpf”表示D盘根目录下的mycert.jpf文件“file:/d:mycert.pfx”表示D盘根目录下的mycert.pfx文件“file:/d:mycert.cer”表示D盘根目录下的mycert.cer文件“usb:/.jpf”表示USB接口中的.jpf文件“usb:/.jpf”表示USB接口中的.jpf文件szPWD 证书密码4 全局常量定义该类定义API 中的常量。在本文档中引用常量时直接引用常量名。4.1 标识常量4.1.1 所用到的配置文件 public static StringCRYPT_INI_FILE_NAME="cryptodevice.ini" public static StringOCSP_INI_FILE_NAME="jitocsp.ini" public static StringCARD_INI_FILE_NAME="card.ini" public static StringMULITYCARD_FILE_NAME="MultiDeviceCard.ini" public static StringMULITYFILE_FILE_NAME="MultiDeviceFile.ini" public static StringJCAAPI_INI_FILE_NAME ="jcaapi.ini"4.1.2 文件长度及密码长度文件长度 public static intFILE_NAME_LEN=256;密码长度 public static intPWD_LEN=128;4.1.3 数据类型定义;Base64类型 public static intDATA_TYPE_BASE64=0;Bin类型 public static intDATA_TYPE_BIN=1;4.1.4 信封类型定义签名信封 public static intENVELOP_SIGN=0;加密信封 public static intENVELOP_ENC=1;既签名又加密信封 public static intENVELOP_SIGN_ENC=2;文摘信封 public static intENVELOP_DIGEST=3;MAC信封 public static intENVELOP_MAC=4;4.1.5 证书扩展类型定义jpf管理员证书文件 public static intCERT_EXP_TYPE_JPF =0;pfx包含私钥证书文件 public static intCERT_EXP_TYPE_PFX=1;cer公钥证书文件 public static intCERT_EXP_TYPE_CER=2;4.1.6 证书用户类型定义个人单证书 public static intCERT_USE_TYPE_SINGLE =0;jpf双证书 public static intCERT_USE_TYPE_DOUBLE=1;电子邮件保护证书 public static intCERT_USE_TYPE_MAIL =2;服务器证书 public static intCERT_USE_TYPE_SERVER=3;CA证书 public static intCERT_USE_TYPE_CA =4;4.1.7 证书状态定义正常状态 public static intCERT_STATUS_NOMAL =0;证书已注销 public static intCERT_STATUS_REVOKE =1;未知状态 public static intCERT_STATUS_UNKNOWN=2;4.1.8 CRL验证证书方式在线验证证书 public static intVERIFY_MODE_ONLINE =0;离线验证证书 public static intVERIFY_MODE_OFFLINE =1;4.1.9 证书SN类型签名证书 public static intCERT_SN_TYPE_SIGN =1;加密证书 public static intCERT_SN_TYPE_ENC =2;签名加密证书 public static intCERT_SN_TYPE_SIGNENC =3;4.1.10 证书存储方式文件方式存储 public static int CERT_DEV_TYPE_FILE =0;USB Key中存储 public static int CERT_DEV_TYPE_USB =1;COM接口设备存储 public static int CERT_DEV_TYPE_COM =2;4.1.11 加密、解密、签名 等算法 RSA加密解密; public static int CT_ALGO_RSA_PKCS =0x00000001;MD2WithRSA 签名验证 public static int CT_ALGO_MD2_RSA_PKCS =0x00000004;MD5WithRSA签名验证 public static int CT_ALGO_MD5_RSA_PKCS =0x00000005;SHA1WithRSA签名验证 public static int CT_ALGO_SHA1_RSA_PKCS =0x00000006;MD2 文摘 public static int CT_ALGO_MD2 =0x00000200;MD5 文摘 public static int CT_ALGO_MD5 =0x00000210;SHA1文摘 public static int CT_ALGO_SHA_1 =0x00000220;RC2 ECB方式加密解密 public static int CT_ALGO_RC2_ECB =0x00000101;RC4加密解密 public static int CT_ALGO_RC4 =0x00000111;DES ECB方式加密解密 public static int CT_ALGO_DES_ECB =0x00000121;3DES ECB方式加密解密 public static int CT_ALGO_DES3_ECB =0x00000132;4.1.12 标准扩展域public static int CERT_EXT_OID_IDENTIFYCARD=12861171;/个人身份标识码:OID=1.2.86.11.7.1 public static int CERT_EXT_OID_INSURANCENUM=12861172;/个人社会保险号:OID=1.2.86.11.7.2 public static int CERT_EXT_OID_ORGANIZATIONCODE=12861173;/企业组织机构代码:OID=1.2.86.11.7.3 public static int CERT_EXT_OID_ICREGNUM =12861174;/企业工商注册号:OID=1.2.86.11.7.4 public static int CERT_EXT_OID_TAXNUM =12861175; /企业税号:OID=1.2.86.11.7.54.2 错误代码成功public static intCT_SUCCESS=0参数错误public static intCT_ERR_PARAM =-9000内存错误public static intCT_ERR_MEMORY=-9001内存分配少public static intCT_ERR_BUFFER_TOO_SMALL=-9090加密库初始化错误public static intCT_ERR_CRYPTODEV_INIT=-9999不能打开加密库public static intCT_ERR_CRYPTO_SESSION =-9002不能访问加密设备public static intCT_ERR_CRYPTODEV_NO_ACCESS =-9003 OCS引擎未初始化public static intCT_ERR_OCSP_ENGINE_NOT_INIT = -9004证书不完整public static intCT_ERR_CERT_NOT_INTEGRITY =-9005取证书状态失败public static intCT_ERR_GET_CERT_STATUS = -9006OCSP初始化错误public static intCT_ERR_OCSP_INIT =-9007 LDAP错误public static intCT_ERR_ACCESS_LDAP =-9008 CRL不完整public static intCT_ERR_CRL_NOT_INTEGRITY =-9009证书颁发者或主题错误public static intCT_ERR_ISSUER_OR_SUBJECT = -9010 CRL引擎未初始化public static intCT_ERR_CRL_ENGINE_NOT_INIT = -9011证书链不完整public static intCT_ERR_CERT_CHAIN_NOT_INTEGRITY=-9012证书过期public static intCT_ERR_CERT_OVER = -9013根证书无效public static intCT_ERR_ROOT_CERT_INVALID = -9014 CRL初始化错误public static intCT_ERR_CRL_INIT =-9015口令错误public static intCT_ERR_PWD =-9016打开文件错误public static intCT_ERR_FILE_OPEN =-9017文件不存在public static intCT_ERR_FILE_NO_EXIST =-9018证书不存在public static intCT_ERR_CERT_NOT_EXIST =-9019证书不匹配public static intCT_ERR_CERT_NO_MATCH =-9020私钥不存在public static intCT_ERR_PRIVATEKEY_NO_EXIST =-9021算法和密钥不匹配public static intCT_ERR_KEY_AND_ALGO_NO_MATCH =-9022密钥不存在 public static intCT_ERR_KEY_NO_EXIST =-9023不支持的算法public static intCT_ERR_ALGO_NOT_SUPPORT =-9024数据长度不匹配public static intCT_ERR_DATA_LENGTH_NO_MATCH =-9025证书和算法不匹配public static intCT_ERR_CERT_AND_ALGO_NO_MATCH =-9026 签名失败public static intCT_ERR_SIGNATURE =-9027 验证签名失败public static intCT_ERR_VERIFY_SIGNATURE =-9028加密失败public static intCT_ERR_ENCRYPT =-9029 解密失败public static intCT_ERR_DECRYPT =-9030产生MAC失败public static intCT_ERR_MAC =-9031 验证MAC失败public static intCT_ERR_VERIFY_MAC =-9032产生密钥失败public static intCT_ERR_GENERATEKEY =-9033 产生摘要失败public static intCT_ERR_DIGEST =-9034数据格式错误public static intCT_ERR_DATA_FORMAT =-9040验证模式错误public static intCT_ERR_VERIFY_MODE =-9041Email地址不存在public static intCT_ERR_NO_EMAIL_ADDRESS =-9042/cryptodevice.ini文件不存在public static intCT_ERR_NO_CRYPT_INI =-9043jitocsp.ini文件不存在public static intCT_ERR_NO_OCSP_INI =-9044jcaapi.ini文件不存在public static intCT_ERR_NO_JCAAPI_INI =-9045card.ini文件不存在public static intCT_ERR_NO_CARD_INI =-9046MultiDeviceCard.ini文件不存在public static intCT_ERR_NO_MULCARD_INI =-9047MultiDeviceFile.ini文件不存在public static intCT_ERR_NO_MULFILE_INI =-9048初始化LDAP错误public static intCT_ERR_LDAP_INIT =-9049LDAP引擎未初始化public static intCT_ERR_LDAP_ENGINE_NOT_INIT =-9050产生随机数失败public static intCT_ERR_GEN_RANDOM =-9051 没有匹配的OIDpublic static intCT_ERR_OID_NO_MATCH =-9053 证书初始化错误 public static intCT_ERR_CERT_INIT =-9081引擎初始化错误 public static intCT_ERR_ENGINE_INIT =-90805 函数说明5.1 类JIT_Engine这个类提供初始化JIT_CA30应用API引擎的功能。用户在使用JIT_CA30应用API的其它功能前，必须初始化引擎。该引擎在一个程序中只能初始化一次。它提供以下功能初始化方法。5.1.1 构造函数JIT_Engine声明：public JIT_Engine(byte bWorkpath)参数：insWorkPathJIT_CA30应用API的工作路径。该路径下存放需要的配置文件和CRL根证书等。这个路径必须是绝对路径。这个路径不能为NULL。返回值：由于构造方法无返回值，所以用户在初始化引擎后，调用getErrcode()方法返回引擎是否初始化成功。示例：byte bWorkPath = null;bWorkPath =”配置文件路径”JIT_Engine Engine = null;Engine = new JIT_Engine(bWorkPath); iRet = Engine.getErrcode();if(iRet =0)/*引擎初始化成功*/else/*引擎初始化失败，返回相应的错误码*/Engine.delete();相关主题GetLastErrDelete5.1.2 获取错误信息 getErrcode声明：public int getErrcode（）参数：无返回值：函数成功时返回0，失败时返回错误码示例：见5.1.1示例5.1.3 释放引擎资源 delete声明：public void delete();参数：无返回值：无示例：见5.1.1示例5.2 类JIT_OCSP这个类提供通过OCSP在线查询证书状态的功能。5.2.1 构造方法JIT_OCSP声明： public int JIT_OCSP( JIT_Engine pEng, JIT_Certificate pRootCert, JIT_Certificate pServerCert)参数：in pEngJIT_CA30应用API引擎。用户先构造一个JIT_Engine的实例，然后将对象传递给方法。in pRootCertCA的证书对象，必须先初始化CA证书。此参数必须非空。pServerCertOCSP服务器证书，此参数保留（置为null）。返回值：由于构造方法无返回值，调用getErrcode()方法返回错误码。注释：在参数pRootCert中指明CA的证书，是用来验证用户要在线查询的证书是否是由pRootCert参数指定的CA签发的。示例： .初始化引擎JIT_OCSP OCSP = null;JIT_Certificate cerRootCert = null; 初始化CA根证书OCSP = new JIT_OCSP(Engine, cerRootCert, null); iRet = OCSP.getErrCode(); if (0 != iRet) 初始化引擎失败 else 初始化引擎成功 OCSP.delete()；相关主题：GetLastErrJIT_CertificateDelete5.2.2 查询证书状态getCertStatus声明：public int (JIT_Certificate pCert, int iCertType)参数：in pCert输入用户要在线查询的证书对象，必须先初始化该证书。此参数必须非空。in iCertType输入用户要在线查询的证书的类型。如果参数pCert中指定的证书是双证书。则在参数nCertType中指明要查询的证书。nCertType证书类型数值CERT_SN_TYPE_SIGN签名证书1C