SafeEngine Java接口说明v1_2_2.doc

SHECA 数字证书-网络因此更真实JavaSafeEngine for Windows（Also For Linux & AIX）接口说明上海市电子商务安全证书管理中心有限公司2004-1-16上海市电子商务安全证书管理中心有限公司文档说明：SafeEngine for Java的接口说明和单点登录接口。版本信息：当前Java接口版本1.2最新版本：1.22更新时间：2004年1月16日星期五版权信息：SHECA是上海市电子商务安全证书管理中心有限公司的注册商标和缩写。UCA 是上海市电子商务安全证书管理中心有限公司研究开发的通用证书系统的商标和缩写。本文的版权属于上海市电子商务安全证书管理中心有限公司，未经许可，任何个人和团体不得转载、粘贴或发布本文，也不得部分的转载、粘贴或发布本文，更不得更改本文的部分词汇进行转贴。未经许可不得拷贝，影印。Copyright 2000 上海市电子商务安全证书管理中心有限公司一SafeEngine for Java接口的目的：该接口是为所有应用程序开发者提供安全平台接口，提供程序开发人员1024/128位强度的加密算法，任何使用SHECA证书的应用软件都可以实现无痛苦的切入，所有的安全机制有该接口实现（包括证书验证，黑名单查询等等）。V1.22版：新增了对单点登录功能的支持接口，需要SafeEngineCom V2.0以上版本和UniTrust SSO Agent V1.0以上版本的支持。二SafeEngine for Java说明：本接口提供以下版本：Win9x/NT, Solaris，AIX，HP，UnixWare，Linux。接口提供以下功能：数字信封，数字签名，验证签名，摘要。从磁盘等介质中读取证书，私钥，证书验证（包括CRL，OCSP验证），证书解码。V1.22版中增加了对单点登录功能的支持接口，包含登录初始化，登录验证和登录凭证解码等功能。三版本说明：当前的JAVA版本所调用到的safeengine为2.2版本以上。1.2较之1.1版新增6部份的函数：l 初始化扩展（1函数）l 数字信封扩展（2函数）l 对称加密（4函数）l 对称加密扩展（4函数）l 生成公私要对（4函数）l 生成随机数（2函数）1.22较之1.2版新增部份：l Sheca_login类，该类包含5个主要方法。四SafeEngine for Java 方法定义：获取出错代码得到调用方法的返回值.调用返回值类型不是数字的方法后，请调用该方法判断是否调用成功。int getErrorCode()初始化环境由三个方法可以完成初始化环境功能： int shecaInitEnviroment(int intPrivateKeyType,String strPrivateKeyDeviceParameter,String strPrivateKeyPassword, int intPrivateKeyTimeout, int intRootCertDeviceType, String strRootCertDeviceParameter, String strRootCertPassword) int shecaInitEnviromentByte(int intPrivateKeyType,byte bytePrivateKeyDeviceParameter,byte bytePrivateKeyPassword, int intPrivateKeyTimeout, int intRootCertDeviceType, byte byteRootCertDeviceParameter, byte byteRootCertPassword)long shecaInitEnvironmentEx(String strPrivateKey,String strPrivateKeyPassword,String strRootCert);功能：初始化环境. 从设备中读取私钥, 根证书。 在调用以下方法前必须先调用此三个方法之一初始化.参数：参数名含义In/out参数选项intPrivateKeyType存储私钥的设备类型In2为文件其他见设备类型编码表strPrivateKeyDeviceParameter,bytePrivateKeyDeviceParameter存储私钥设备的参数In如privatekeydevicetpe=2 为文件名,其他可为”com1”, “com2”若不需要私钥, 可设为空字符串 “”,表示不取私钥strPrivateKeyPassword,bytePrivateKeyPassword私钥密码InintPrivateKeyTimeout私钥超时时间. 秒为单位InIntRootCertDeviceType存储根证书的设备类型In2为文件其他见设备类型编码表strRootCertDeviceParameter,byteRootCertDeviceParameter存储根证书设备的参数In如privatekeydevicetpe=2 为文件名,其他可为”com1”, “com2”若不需要根证书, 可设为空字符串 “”,表示不取根证书strRootCertPassword,byteRootCertPassword根证书密码In仅当rootcertdevicetype为IC卡时有效strPrivateKey私钥BASE64编码IN必须输入项strPrivateKeyPassword私钥密码IN必须输入项strRootCert根证书BASE64编码IN必须输入项返回：=0正常返回,0x82040000装载动态库出错0x82040002读写私钥设备失败0x82040003私钥密码错误0x82040004读写根证书设备失败0x82040005根证书密码错误0x8204000A初始化错误0x82040001内存分配错误其他错误0xFFFFFFF4没有正确安装Safeengine.dll0xFFFFFFF3分配系统内存异常清除环境int shecaClearEnviroment ()功能: 清除环境变量. 和初始化方法配对使用.返回：=0正常返回,0x8204000A没有初始化0x82040000装载动态库出错0x8204000B清除环境错误PEM 编码/解码PEM 编码byte shecaPEMEncode(byte indata)将二进制字符串转成可见字符串。参数：参数名含义输入？输出参数选项indata待编码的数据in返回值:0正常返回0x8204000A没有初始化0x82040024编码错误PEM解码byte shecaPEMDecode(bytepemdata)参数：参数名含义输入？输出参数选项pemdata待解码的数据in返回值:0正常返回0x8204000A没有初始化0x82040025解码错误PKCS12接口从PKCS12中获取证书String shecaGetCertFromPKCS12(String strPKCS12, String strPKCS12Password);参数：参数名含义In/out参数选项strPKCS12PKCS12数据块InstrPKCS12PasswordPKCS12数据密码IngetErrorCode()方法返回值：=0正常返回,0x8204000A没有初始化0x82040000装载动态库出错0x8204000C签名错误0x82040008超时, 私钥密码错误.-5PEM编码出错数字签名签名由两个方法可以实现签名String shecaSignData(String strOriginData, int intSignmethod)byte shecaSignData(byte byteOriginData, int intSignmethod)参数：参数名含义In/out参数选项strOriginData,byteOriginData原始数据块InintSignmethod签名类型In1: MD22: MD53: SHA1getErrorCode()方法返回值：=0正常返回,0x8204000A没有初始化0x82040000装载动态库出错0x8204000C签名错误0x82040008超时, 私钥密码错误.0x82040024PEM编码出错0x82040025PEM解码出错0x82040029公私钥不匹配0x8204002B非法的P12值0x8204002CP12解码错误摘要由两个方法可以实现摘要String shecaDigest(String strOrigindata,int intMethod)byte shecaDigestByte(byte byteOrigindata,int intMethod)参数：参数名含义In/out参数选项strOrigindata,byteOrigindata原始数据块InintMethod摘要方法In1: MD22: MD53: SHA1getErrorCode()方法返回值：=0正常返回,0x82040000装载动态库出错0x8204000A没有初始化0x8204000E摘要错误-4PEM编码出错验证签名由两个方法可以实现验证签名int shecaVerifySignData(String strOriginData, int intSignmethod, String strSignedData, String strCeritificate)int shecaVerifySignDataByte(byte byteOriginData, int intSignmethod, byte byteSignedData, byte byteCeritificate)参数：参数名含义In/out参数选项strOriginData,byteOriginData原始数据块InIntSignmethod签名类型In1: MD22: MD53: SHA1strSignedData,byteSignedData签名数据块InstrCertificate,byteCertificate证书内容In返回：=0正常返回,0x8204000A没有初始化0x82040000装载动态库出错0x8204000D验证错误0x8204000F证书错误0x82040001内存分配错误-5证书PEM解码出错-6签名数据PEM解码出错数字信封由两个方法可以实现数字信封加密String shecaEnvelope(int intEnvelopetype, String strIndata, String strCertificate );byte shecaEnvelope(int intEnvelopetype, byte byteIndata, byte byteCertificate );功能：数字信封打包或拆解参数：参数名含义In/out参数选项IntEnvelopetype信封类型In1组成数字信封2拆解数字信封strIndata,byteIndata原始数据块InstrCertificate,byteCertificate证书内容In在解数字信封时不起作用getErrorCode()方法返回值：=0正常返回,0x8204000A没有初始化0x82040000装载动态库出错0x82040010数字信封错误0x82040008超时, 私钥密码错误.0x8204000F证书无效.0x82040001内存分配错误-6证书PEM解码出错-7信封PEM编码出错-8信封PEM解码出错解数字信封时, 若私钥超时, 先重读私钥, 若密码错误,返回 3 , 此时需重新初始化.数字信封扩展由两个方法可以实现数字信封加解密扩展String shecaEnvelopeEx(int intEnvelopetype, String strIndata, String strCertificate );byte shecaEnvelopeExBytes(int intEnvelopetype, byte byteIndata, byte byteCertificate );功能：数字信封打包或拆解参数：参数名含义In/out参数选项IntEnvelopetype信封类型In1组成数字信封2拆解数字信封strIndata,byteIndata原始数据块InstrCertificate,byteCertificate证书内容In在解数字信封时不起作用getErrorCode()方法返回值：=0正常返回,0x8204000A没有初始化0x82040000装载动态库出错0x82040010数字信封错误0x82040008超时, 私钥密码错误.0x8204000F证书无效.0x82040001内存分配错误-6证书PEM解码出错-7信封PEM编码出错-8信封PEM解码出错解数字信封时, 若私钥超时, 先重读私钥, 若密码错误,返回 3 , 此时需重新初始化.对称加密由两个方法可以实现对称加密 String shecaEncryptData(byte byteIndata,String strKey); byte shecaEncryptDataBytes(byte byteIndata,byte byteKey);功能：数据对称加密参数：参数名含义In/out参数选项strIndata,byteIndata原始数据块InstrKey,byteKey对称密钥IngetErrorCode()方法返回值：=0正常返回,0x8XXXXX请查看SafeEngine的说明-1,-2,-4分配内存错-3密码长度错对称解密由两个方法可以实现对称解密 String shecaDecryptData(String strIndata,String strKey); byte shecaDecryptDataBytes(byte byteIndata,byte byteKey);功能：数据对称解密参数：参数名含义In/out参数选项strIndata,byteIndata加密数据块InstrKey,byteKey对称密钥IngetErrorCode()方法返回值：=0正常返回,0x8XXXXX请查看SafeEngine的说明-1,-2,-4,-5分配内存错-3密码长度错对称加密扩展由两个方法可以实现对称加密扩展 String shecaEncryptDataEx(byte byteIndata,String strKey,int int AlgID); native byte shecaEncryptDataExBytes(byte byteIndata,byte byteKey,int int AlgID);功能：数据对称加密扩展参数：参数名含义In/out参数选项strIndata,byteIndata原始数据块InstrKey,byteKey对称密钥InAlgID加密算法IngetErrorCode()方法返回值：=0正常返回,0x8XXXXX请查看SafeEngine的说明-1,-2,-3,-4,-5分配内存错对称解密扩展由两个方法可以实现对称解密扩展 String shecaDecryptDataEx(String strIndata,String strKey,int intAlgID); byte shecaDecryptDataExBytes(byte byteIndata,byte byteKey,int intAlgID);功能：数据对称解密扩展参数：参数名含义In/out参数选项strIndata,byteIndata加密数据块InstrKey,byteKey对称密钥InAlgID加密算法IngetErrorCode()方法返回值：=0正常返回,0x8XXXXX请查看SafeEngine的说明-1,-2,-3,-4,-5分配内存错证书从介质中获取证书由两个方法可以实现从介质中获取证书String shecaGetSelfCertificate(int intDevicetype, String strDeviceParameter, String strPassword)byte shecaGetSelfCertificate(int intDevicetype,byte byteDeviceParam,byte bytePassword)功能：从设备中读取证书，证书的来源可以是IC卡，磁盘。参数：参数名含义In/out参数选项intDevicetype设备类型in2为文件其他见设备类型编码表strDeviceParameter,byteDeviceParam设备参数In如privatekeydevicetpe=2 为文件名,其他可为”com1”, “com2”strPassword,bytePassword密码IngetErrorCode()方法返回值：=0正常返回,0x8204000A没有初始化0x82040000装载动态库出错0x82040006读证书失败0x82040009缓冲区不够长0x82040007密码错误0x82040001内存分配错误-6证书PEM编码出错从网络获取证书由两个方法可以实现从网络获取证书String shecaGetCertificate(String strSerialNo, String strUrl);byte shecaGetCertificate(byte byteSerialNo, byte byteUrl);功能：先读取本地缓冲库，然后检查CA证书库。参数：参数名含义In/out参数选项strSerialNo,byteSerialNo证书序列号InstrUrl,byteUrl证书查询urlIn格式: IP : PORTgetErrorCode()方法返回值：=0正常返回,0x8204000A没有初始化0x82040000装载动态库出错0x82040011得证书失败0x82040009缓冲区不够长0x82040001内存分配错误-6证书PEM编码出错通过黑名单验证证书由两个方法可以实现通过黑名单验证证书int shecaVerifyCertificate(byte byteCertificate)功能：验证证书有效性，先验有效期，ca签发，根据配置决定是否验证本地黑名单，ca黑名单。配置方式见SE_SetConfiguration说明。参数：参数名含义In/out参数选项strCertificate,byteCertificate证书内容In证书内容返回：=0证书有效0x8204000A没有初始化0x82040000装载动态库出错0x8204000F证书错误0x82040012有效期外0x82040015非ca签发0x82040016黑名单中0x82040017黑名单文件错误0x82040001内存分配错误-8证书PEM解码出错通过OCSP验证证书由两个方法可以实现通过OCSP验证证书int shecaVerifyCertificateOnline(String strCertificate)int shecaVerifyCertificateOnline(byte byteCertificate)功能：在线验证证书有效性，先验有效期，ca签发，本地黑名单，然后ocsp参数：参数名含义In/out参数选项strCertificate,byteCertificate证书内容In返回：=0证书有效0x8204000A没有初始化0x82040000装载动态库出错0x82040018连接失败0x8204000F证书错误0x82040012有效期外0x82040015非ca签发0x8204001AOCSP回包无效0x8204001BOCSP回包错误0x8204001COCSP回包有效期外0x8204001DOCSP回包验证签名错误0x82040016证书已废除0x8204001E证书状态不明0x82040001内存分配出错-13证书PEM解码出错更改密码由两个方法可以实现更改密码int shecaChangePassword( int intDevicetype, String strDeviceparameter, String strOldPassword, String strNewPassword)int shecaChangePassword( int intDevicetype, byte byteDeviceparameter, byte byteOldPassword, byte byteNewPassword)功能：更改存储介质的密码。参数：参数名含义In/out参数选项intDevicetype设备类型in2为文件其他见设备类型编码表strDeviceparameter,byteDeviceparameter设备参数In如privatekeydevicetpe=2 为文件名,其他可为”com1”, “com2”strOldPassword,byteOldPassword密码InstrNewPassword,byteNewPassword密码in返回：=0正常返回,密码更改成功0x8204000A没有初始化0x82040000装载动态库出错0x82040003口令检查不通过0x82040002读写设备失败0x8204001F加解密失败。0x82040001内存分配错误证书解码获取证书细目由两个方法可以实现获取证书细目String shecaGetCertDetail(String strCert, int intItemNo )byte shecaGetCertDetail(byte byteCert, int intItemNo )取待检测证书的细目。参数：参数名含义输入？输出参数选项strCert,byteCert待解码的证书的编码串的起始地址InintItemNo项目 idIn1证书版本2证书序列号3证书签名算法4证书发放者国家名5证书发放者组织名6证书发放者部门名7证书发放者省州名8证书发放者通用名9证书发放者城市名10证书发放者EMAIL地址11证书有效期起始12证书有效期截止13用户国家名14用户组织名15用户部门名16用户省州名17用户通用名18用户城市名19用户EMAIL地址20用户DER公钥值21用户证书自定义级别ItemValue解码后的项目指针Out由外部分配Itemlength项目长度In/Out输入缓冲区长度,返回解码后项目长度getErrorCode()方法返回值：=0正常返回0x8204000A没有初始化0x82040000装载动态库出错0x82040021取证书细目错误0x82040009缓冲区不够长0x82040001内存分配错误-5证书PEM解码出错配置参数int shecaSetConfiguration(int intMode);配置函数.用来设置一些参数的选项.不如验证证书时是否验证黑名单.参数：参数名含义输入？输出参数选项IntModeinBit 0 = 1:验证书有效性时检查CA的黑名单库.Bit 0 = 0: 不验证黑名单.Bit 1 Bit 31: 保留.缺省设置不检查黑名单.返回值:=0正常返回Bit0(最低位)：digitalSignature获取证书剩余有效天数由两个方法可以实现获取证书剩余有效天数long shecaGetCertValidDate(String strCert);long shecaGetCertValidDate(byte byteCert);功能：获取证书剩余的有效天数。参数：参数名含义In/out参数选项strCert,byteCertPEM编码的证书INgetErrorCode()返回0正常返回,0x8204000A没有初始化0x8204000F证书错误0x82040012证书已过期获取证书唯一标识由两个方法可以获取证书唯一标识String shecaGetCertUniqueID(String strCert);byte shecaGetCertUniqueID(byte byteCert);取证书唯一标识，如身份证号。参数：参数名含义输入？输出参数选项strCert,byteCertPEM编码的证书INgetErrorCode()返回值：0正常返回0x8204000A没有初始化0x82040000装载动态库出错0x8204000F证书解码错误0x8204002E错误的OID0x82040009缓冲区不够长获取证书级别由两个方法可以实现获取证书级别long shecaGetCertClass(String strCert);long shecaGetCertClass(byte byteCert);取证书级别。参数：参数名含义输入？输出参数选项strCert,byteCertPEM编码的证书IN返回值个人身份证书 0x00000103个人EMAIL证书 0x00000102个人代码签名证书 0x00000105单位身份证书 0x00000203单位EAIL证书 0x00000202单位代码签名证书 0x00000204服务器身份证书 0x00000304WEB服务器证书 0x00000301getErrorCode()返回值：0正常返回0x8204000A没有初始化0x82040034获取证书级别错误根据oid获取证书扩展项信息由两个方法可以实现根据oid获取证书扩展项信息String shecaGetCertInfoByOID(String strCert,String strOID);byte shecaGetCertInfoByOID(byte byteCert,byte byteOID);取证书扩展项信息。参数：参数名含义输入？输出参数选项strCert,byteCertPEM编码的证书INstrOID,byteOID扩展项的OIDIN返回值：0正常返回0x8204000A没有初始化0x82040000装载动态库出错0x8204000F证书解码错误0x8204002E错误的OID0x82040009缓冲区不够长密钥生成非对称密钥由两个方法可以生成非对称的密钥String shecaGenRSAKeyPair(String strkeyName, String strPassWord,int iModulusLen);byte shecaGenRSAKeyPairBytes(String strkeyName, String strPassWord, int iModulusLen);功能：生成非对称的密钥。参数：参数名含义In/out参数选项strkeyName密钥名称InstrPassWord,密码IniModulusLen密钥长度IngetErrorCode()方法返回值：=0正常返回,0x8XXXXX请查看SafeEngine的说明-1,-2,-3分配内存错由于该函数只返回出私钥，因此需要调用下面的函数取得对应的公钥。从私钥中取得公钥由两个方法可以取到公钥 String shecaGetPubkeyFromPrikey(String strRSAPrivateKey); byte shecaGetPubkeyFromPrikeyBytes(byte bRSAPrivateKey);功能：从私钥中取得公钥。参数：参数名含义In/out参数选项strRSAPrivateKey，bRSAPrivateKey私钥IngetErrorCode()方法返回值：=0正常返回,0x8XXXXX请查看SafeEngine的说明-1,-2,-3分配内存错生成随机数由两个方法可以取到随机数 String shecaGenRandom(int randombyteslen); byte shecaGenRandomBytes(int randombyteslen);功能：生成随机数。参数：参数名含义In/out参数选项randombyteslen随机数长度IngetErrorCode()方法返回值：=0正常返回,0x8XXXXX请查看SafeEngine的说明-1,-2分配内存错五单点登录类sheca_login的方法定义：登录初始化LoginInit(int iServerCertDevType,String strServerCertDevParam,String strServerCertPassword)功能：为用户登录生成登录凭证原始信息，并取得服务器证书。生成的登录凭证原始信息存放在sheca_login类的实例的strRandom属性中。得到的服务器证书存放在sheca_login类的实例的strServerCert属性中，如果没有服务器证书该属性为空。参数：参数名含义In/out参数选项iServerCertDevType服务器证书设备号InstrServerCertDevParam设备参数InstrServerCertPassword密码IngetErrorCode()方法返回值（或者可以直接查看实例的iError属性）：=0,10正常返回,1无服务器证书-1初始化safeengine出错-2生成随机数错getJava_SE_ErrorCode()方法返回值（或