接口说明.docx

1、接口说明UniTrust SafeEngine API接口说明上海市电子商务安全证书管理中心有限公司文档说明：SafeEngine API的接口说明版本信息：当前版本 2.3版权信息：SHECA是上海市电子商务安全证书管理中心有限公司的注册商标和缩写。UCA 是上海市电子商务安全证书管理中心有限公司研究开发的通用证书系统的商标和缩写。本文的版权属于上海市电子商务安全证书管理中心有限公司，未经许可，任何个人和团体不得转载、粘贴或发布本文，也不得部分的转载、粘贴或发布本文，更不得更改本文的部分词汇进行转贴。未经许可不得拷贝，影印。Copyright 2000 上海市电子商务安全证书管理中心有限公司

2、一SafeEngine API函数的目的 5二SafeEngine API函数说明 5三安装说明 5四版本说明 5五开发注意事项 6六SafeEngine API 函数定义 7初始化环境 7初始化环境 8清除环境 8数字签名 9签名 9摘要 9验证签名 10数字信封 11数字信封扩展 12证书 13从介质中获取证书 13从网络获取证书 14通过黑名单验证证书 15通过OCSP验证证书 15更改密码 16证书解码 17获取证书结构 17获取证书细目 17获取证书唯一标识 19获取证书级别 20根据oid获取证书扩展项信息 20获取证书剩余有效天数 21获取证书用途 22PEM 编码/解码 23P

3、EM 编码 23PEM解码 23加密/解密 24产生随机密钥 24对称加密 24对称解密 25对称加密扩展 26对称解密扩展 27配置参数 27PKCS12接口 28Pkcs12编码（现只提供windows版） 28获取设备列表 29获取设备信息 30获取设备类型 31获取API版本信息 32介质辅助（仅支持Windows版） 33自动识别设备号 33获取端口信息 33获取设备剩余锁定次数 34七错误代码表 35八简单实例 37九常见问题 39一SafeEngine API函数的目的该接口是为所有应用程序开发者提供安全平台接口，提供程序开发人员1024/128位强度的加密算法，可以与任何使用U

4、CA证书的应用软件集成，所有的安全机制有该接口实现（包括证书验证，黑名单查询等等）。二SafeEngine API函数说明本接口提供以下版本：win9x/NT, solaris，aix，sco，unixware，linux，hpux，freebsd。接口提供以下功能：数字信封，数字签名，验证签名，摘要，对称加解密，PEM编解码。从磁盘，IC卡等介质中读取证书，私钥，证书验证（包括CRL，OCSP验证），证书解码。为了保护用户的私钥，使开发人员不能取得用户私钥，API接口不提供获取明文私钥的函数。所有私钥都在接口内部保存，使用。由于API支持各种常用平台，建议在服务器端开发时使用SafeEngi

5、ne API。在客户端使用UniTrust证书管理器API，方便用户使用。关于多线程的说明：SafeEngine本身支持多线程。但有的设备在读写，内部运算时是不支持多线程的。如果用到了这些设备，需要应用来处理解决多线程的冲突问题。建议使用多线程接口。单线程接口在以后的版本中将不再支持。三安装说明在Windows下需要安装UniTrust 证书管理器V2.26或以上版本，所有需要的库将随证书管理器一起安装。安装需要使用的设备的驱动包。在Unix下，将所有库文件拷贝到/usr/lib目录下，将UniTrustCMBConfig.ini文件拷贝到/ect目录下。程序执行时要求/etc目录有读权限。四

6、版本说明本文档对应SafeEngine V2.3.6.0版。2.3.6.0版更新：增加了设备错误的返回代码定义。增加了设备检测相关辅助函数。2.3版更新：修正了软件生成随机数重复的问题。2.2版更新：对设备类型编号做了新的定义，从short类型(16bits)改为long类型(32bits)。详细说明请参考设备类型说明文档。支持同一介质中多对密钥的使用。兼容新旧版UniTrust介质规范。下载黑名单支持标准LDAP URL。2.1版更新：为了增加对SSF33算法的支持，新增了带加密算法标识的对称加解密函数，数字信封函数SE(H)_EncryptDataEx，SE(H)_DecryptDataE

7、x，SE(H)_EnvelopeEx。支持内置算法的设备，如明华ekey等。提供获取设备信息的接口SEH_GetDeviceInfo，可以得到设备是否有内置算法，支持的读卡器类型等信息。2.0版更新：增加从内存读入私钥，根证书的接口SE_InitialSessionEx，SEH_InitialSessionEx新增以下函数：获取API版本信息SE_ShowVersion，SEH_ShowVersion获取证书标识SE_GetCertUniqueID，SEH_GetCertUniqueID获取证书级别SE_GertCertClass，SHE_GetCertClass根据oid获取证书扩展项信息S

8、E_GetCertInfoByOID，SEH_GetCertInfoByOID获取证书剩余有效天数SE_GetCertValidDate，SEH_GetCertValidDate更新SE_VefifyCertificate， SEH_VerifyCertificate，SE_VerifyCertificateOnline，SEH_VerifyCertificateOnline支持多级证书验证，交叉认证证书验证。支持OCSP方式验证证书。所有从网络下载的证书，CRL，证书链都支持本地存储，并提供可替换的本地存储接口。新增支持Sheca读卡器。新增支持设备ekey。所有返回值重新定义。五开发注意事

9、项使用多线程版本的API时应注意需要在每个线程中做初始化，并使用本线程的hSE操作，在线程结束前清除环境。不能在主线程里初始化，多个子线程共享hSE。由于用到了较多的栈资源，创建线程时需要自己定义栈的大小，设成200K以上。六SafeEngine API 函数定义初始化环境long SEH_InitialSession(HSE *hSE, unsigned long privatekeydevicetype, char *privatekeydeviceparameter, char *privatekeypassword, unsigned long privatekeytimeout, u

10、nsigned long certchaindevicetype, char *certchaindeviceparameter, char *certchainpassword )功能：初始化环境. 从设备中读取私钥, 根证书. 在调用以下函数前必须先调用初始化函数初始化.参数：参数名含义In/out参数选项hSE函数句柄#define void* HSEOutPrivatekeydevicetype存储私钥的设备类型In见最新的设备类型说明文档Privatekeydeviceparameter存储私钥设备的参数In见最新的设备类型说明文档若不需要私钥, 可设为空字符串 “”,表示不取私钥P

11、rivatekeypassword私钥密码InPrivatekeytimeout私钥超时时间. 秒为单位In若 = 0，则私钥永久有效。certchaindevicetype存储证书链的设备类型In见最新的设备类型说明文档certchaindeviceparameter存储根证书设备的参数In见最新的设备类型说明文档若不需要根证书, 可设为空字符串 “”,表示不取根证书certchainpassword根证书密码In返回：SE_SUCCESS正常返回,SE_ERROR_LOAD_LIBRARY装载动态库出错SE_ERROR_PRIVATE_KEY_DEV读写私钥设备失败SE_ERROR_PRI

12、VATE_KEY_PASSWORD私钥密码错误SE_ERROR_CERT_CHAIN_DEV读写证书链设备失败SE_ERROR_CERT_CHAIN_PASSWORD证书链密码错误SE_ERROR_INITIAL_SESSION初始化错误SE_ERROR_MEMORY内存分配错误SE_ERROR_READ_CONFIG读配置文件错误SE_ERROR_PRIVATE_KEY_PASSWORD_LEN私钥密码密码长度错误。最长8位。SE_ERROR_DEVICE_PORT端口号错误SE_ERROR_NO_DEVICE未找到设备SE_ERROR_DEVICE_DRIVER设备驱动未正确安装SE_ER

13、ROR_CONNECT连接设备错误SE_ERROR_DEVICE_LOCKED设备已锁定Example:/私钥, 证书在IC卡上. Com1 口, 不设超时.HSE hSE;SEH_InitialSession(&hSE, 0x0202, com1, password, 0, 0x0202, com1, password);初始化环境long SEH_InitialSessionEx(HSE *hSE, unsigned char * privatekey, unsigned short privatekeylen, char *privatekeypassword, unsigned cha

14、r *certchain, unsigned short certchainlen);功能：初始化环境. 从内存中读取私钥, 根证书. 在调用以下函数前必须先调用初始化函数初始化.参数：参数名含义In/out参数选项HSE函数句柄#define void* HSEOutprivatekey加密的私钥Inprivatekeylen私钥长度Inprivatekeypassword私钥密码In如privatekeypassword为”，可以装入明文的私钥rootcert证书链Inrootcertlen证书链长度In返回：SE_SUCCESS正常返回,SE_ERROR_LOAD_LIBRARY装载动态

15、库出错SE_ERROR_PRIVATE_KEY_PASSWORD私钥密码错误SE_ERROR_INITIAL_SESSION初始化错误SE_ERROR_MEMORY内存分配错误SE_ERROR_PRIVATE_KEY_PASSWORD_LEN私钥密码密码长度错误。最长8位。清除环境long SEH_ClearSession(HSE hSE)功能: 清除环境变量. 在程序结束前应调用此函数.参数：参数名含义In/out参数选项HSE函数句柄in返回：SE_SUCCESS正常返回,SE_ERROR_INITIAL_SESSION没有初始化SE_ERROR_LOAD_LIBRARY装载动态库出错SE

16、_ERROR_CLEAR_SESSION清除环境错误Example:SEH_ClearSession(hSE);数字签名签名long SEH_SignData（HSE hSE, unsigned char *origindata, unsigned long length, unsigned short signmethod, unsigned char *signeddata, unsigned long *signedlength）功能：数字签名。注意：因MD5已发现漏洞，摘要算法推荐使用SHA1。参数：参数名含义In/out参数选项HSE函数句柄InOrigindata原始数据块InLe

17、ngth原始数据库长度InSignmethod摘要算法In3: SHA1Signeddata处理后数据块OutSignedlength处理后数据库长度Out返回：SE_SUCCESS正常返回,SE_ERROR_INITIAL_SESSION没有初始化SE_ERROR_LOAD_LIBRARY装载动态库出错SE_ERROR_SIGN签名错误SE_ERROR_PRIVATE_KEY_TIME_OUT超时, 私钥密码错误.Example:Unsigned char databuf=”test signature”;Unsigned char signdata200;Unsigned long sig

18、nlen;SEH_SignData(hSE, databuf, strlen(databuf), 3, signdata, &signlen);摘要long SEH_Digest(HSE hSE, unsigned char *data, unsigned long length , unsigned short method, unsigned char *digest, unsigned long *digestlength)功能：摘要注意：因MD5已发现漏洞，摘要算法推荐使用SHA1。参数：参数名含义In/out参数选项HSE函数句柄InData原始数据块InLength原始数据库长度I

19、nMethod摘要方法In3: SHA1Digest处理后数据块OutDigestlength处理后数据长度Out返回：SE_SUCCESS正常返回,SE_ERROR_INITIAL_SESSION没有初始化SE_ERROR_LOAD_LIBRARY装载动态库出错SE_ERROR_DIGEST摘要错误Example:Unsigned char data = “Digest test”;Unsigned char digest 50;Unsigned long digestlen;SEH_Digest(hSE, data, strlen(data), 3, digest, &digestlen)

20、验证签名long SEH_VerifySignData(HSE hSE, unsigned char *origindata, unsigned long originlength, unsigned short signmethod, unsigned char *signeddata, unsigned long signedlength, unsigned char *ceritificate, unsigned short certlength)功能：验证签名。参数：参数名含义In/out参数选项HSE函数句柄InOrigindata原始数据块InOriginlength原始数据库长度

21、InSignmethod签名类型In3: SHA1Signeddata签名数据块InSignedlength签名数据块长度InCertificate证书内容InCertlength证书长度In返回：SE_SUCCESS正常返回,SE_ERROR_INITIAL_SESSION没有初始化SE_ERROR_LOAD_LIBRARY装载动态库出错SE_ERROR_VERIFY_SIGN验证错误SE_ERROR_INVALID_CERT证书错误SE_ERROR_MEMORY内存分配错误Example:unsigned char databuf=”test signature”;unsigned cha

22、r signdata200;unsigned long signlen;unsigned char cert2048;unsigned short certlen;certlen=2048;SEH_GetSelfCertificate(hSE, 0x0202, com1, password, cert, &certlen);SEH_SignData(hSE, databuf, strlen(databuf), 3, signdata, &signlen);SEH_VerifySignData(hSE, databuf, strlen(databuf), 3, signdata, signlen

23、, cert, certlen);数字信封long SEH_Envelope(HSE hSE, unsigned short envolpetype, unsigned char *indata, unsigned long inlength, unsigned char * outdata, unsigned long *outlength, unsigned char *certificate, unsigned short certlength)功能：数字信封打包或拆解参数：参数名含义In/out参数选项HSE函数句柄Inenveloptype信封类型In1组成数字信封2拆解数字信封In

24、data原始数据块InInlength原始数据库长度InOutdata处理后数据块Out由外部分配Outlength处理后数据库长度OutCertificate证书内容In在解数字信封时不起作用Certlength证书长度In在解数字信封时不起作用返回：SE_SUCCESS正常返回,SE_ERROR_INITIAL_SESSION没有初始化SE_ERROR_LOAD_LIBRARY装载动态库出错SE_ERROR_ENVEKOP数字信封错误SE_ERROR_PRIVATE_KEY_TIME_OUT超时, 私钥密码错误.SE_ERROR_INVALID_CERT证书无效.SE_ERROR_MEMO

25、RY内存分配错误Example:unsigned char data=”Envelop test”;unsigned char envelope;unsigned long envelopelen;unsigned char cert2048;unsigned short certlen;unsigned char outdata100;unsigned long outlen;int rtn_codecertlen=2048;SEH_GetSelfCertificate(hSE, 0x0202, com1, password, cert, &certlen);/组成SEH_Envelope(

26、hSE, 1, data, strlen(data), envelope, &envelopelen, cert, certlen);/拆解rtn_code=SEH_Envelope(hSE, 2, envelope, envelopelen, outdata, &outlen, “”, 0);数字信封扩展long SEH_EnvelopeEx(HSE hSE, unsigned short envolpetype, unsigned char *indata, unsigned long inlength, unsigned char * outdata, unsigned long *ou

27、tlength, unsigned char *certificate, unsigned short certlength, int AlgID)功能：数字信封打包或拆解参数：参数名含义In/out参数选项HSE函数句柄Inenveloptype信封类型In1组成数字信封2拆解数字信封Indata原始数据块InInlength原始数据库长度InOutdata处理后数据块Out由外部分配Outlength处理后数据库长度OutCertificate证书内容In在解数字信封时不起作用Certlength证书长度In在解数字信封时不起作用AlgID对称加密算法标识In请参考最新的设备类型说明文档返

28、回：SE_SUCCESS正常返回,SE_ERROR_INITIAL_SESSION没有初始化SE_ERROR_LOAD_LIBRARY装载动态库出错SE_ERROR_ENVEKOP数字信封错误SE_ERROR_PRIVATE_KEY_TIME_OUT超时, 私钥密码错误.SE_ERROR_INVALID_CERT证书无效.SE_ERROR_MEMORY内存分配错误注：打包和拆解时的加密算法标识必须相同。Example:unsigned char data=”Envelop test”;unsigned char envelope;unsigned long envelopelen;unsigned char outdata100;unsigned long outlen;int rtn_code/组成，用SSF33算法SEH_EnvelopeEx(hSE, 1, data, strlen(data), envelope, &envelopelen, cert, certlen, 7);/拆解，用SSF33算法rtn_code=SEH_EnvelopeEx(hSE, 2, envelope, envelopelen, outdata, &outlen, “”, 0, 7);证书从介质中获取证书long SEH_GetSelfCertificate(HSE hSE