接口说明.docx
《接口说明.docx》由会员分享，可在线阅读，更多相关《接口说明.docx（63页珍藏版）》请在冰豆网上搜索。
接口说明
UniTrust®SafeEngineAPI
接口说明
上海市电子商务安全证书管理中心有限公司
文档说明：
SafeEngineAPI的接口说明
版本信息：
当前版本2.3
版权信息：
SHECA是上海市电子商务安全证书管理中心有限公司的注册商标和缩写。
UCA是上海市电子商务安全证书管理中心有限公司研究开发的通用证书系统的商标和缩写。
本文的版权属于上海市电子商务安全证书管理中心有限公司，未经许可，任何个人和团体不得转载、粘贴或发布本文，也不得部分的转载、粘贴或发布本文，更不得更改本文的部分词汇进行转贴。
未经许可不得拷贝，影印。
Copyright@2000上海市电子商务安全证书管理中心有限公司
一．SafeEngineAPI函数的目的5
二．SafeEngineAPI函数说明5
三．安装说明5
四．版本说明5
五．开发注意事项6
六．SafeEngineAPI函数定义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
获取证书用途22
PEM编码/解码23
PEM编码23
PEM解码23
加密/解密24
产生随机密钥24
对称加密24
对称解密25
对称加密扩展26
对称解密扩展27
配置参数27
PKCS12接口28
Pkcs12编码（现只提供windows版）28
获取设备列表29
获取设备信息30
获取设备类型31
获取API版本信息32
介质辅助（仅支持Windows版）33
自动识别设备号33
获取端口信息33
获取设备剩余锁定次数34
七．错误代码表35
八．简单实例37
九．常见问题39
一．SafeEngineAPI函数的目的
该接口是为所有应用程序开发者提供安全平台接口，提供程序开发人员1024/128位强度的加密算法，可以与任何使用UCA证书的应用软件集成，所有的安全机制有该接口实现（包括证书验证，黑名单查询等等）。
二．SafeEngineAPI函数说明
本接口提供以下版本：
win9x/NT,solaris，aix，sco，unixware，linux，hpux，freebsd。
接口提供以下功能：
数字信封，数字签名，验证签名，摘要，对称加解密，PEM编解码。
从磁盘，IC卡等介质中读取证书，私钥，证书验证（包括CRL，OCSP验证），证书解码。
为了保护用户的私钥，使开发人员不能取得用户私钥，API接口不提供获取明文私钥的函数。
所有私钥都在接口内部保存，使用。
由于API支持各种常用平台，建议在服务器端开发时使用SafeEngineAPI。
在客户端使用UniTrust证书管理器API，方便用户使用。
关于多线程的说明：
SafeEngine本身支持多线程。
但有的设备在读写，内部运算时是不支持多线程的。
如果用到了这些设备，需要应用来处理解决多线程的冲突问题。
建议使用多线程接口。
单线程接口在以后的版本中将不再支持。
三．安装说明
在Windows下需要安装UniTrust证书管理器V2.26或以上版本，所有需要的库将随证书管理器一起安装。
安装需要使用的设备的驱动包。
在Unix下，将所有库文件拷贝到/usr/lib目录下，将UniTrustCMBConfig.ini文件拷贝到/ect目录下。
程序执行时要求/etc目录有读权限。
四．版本说明
本文档对应SafeEngineV2.3.6.0版。
2.3.6.0版更新：
增加了设备错误的返回代码定义。
增加了设备检测相关辅助函数。
2.3版更新：
修正了软件生成随机数重复的问题。
2.2版更新：
对设备类型编号做了新的定义，从short类型（16bits）改为long类型（32bits）。
详细说明请参考《设备类型说明》文档。
支持同一介质中多对密钥的使用。
兼容新旧版UniTrust介质规范。
下载黑名单支持标准LDAPURL。
2.1版更新：
为了增加对SSF33算法的支持，新增了带加密算法标识的对称加解密函数，数字信封函数SE（H）_EncryptDataEx，SE（H）_DecryptDataEx，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获取证书扩展项信息SE_GetCertInfoByOID，SEH_GetCertInfoByOID
获取证书剩余有效天数SE_GetCertValidDate，SEH_GetCertValidDate
更新SE_VefifyCertificate，SEH_VerifyCertificate，SE_VerifyCertificateOnline，SEH_VerifyCertificateOnline支持多级证书验证，交叉认证证书验证。
支持OCSP方式验证证书。
所有从网络下载的证书，CRL，证书链都支持本地存储，并提供可替换的本地存储接口。
新增支持Sheca读卡器。
新增支持设备ekey。
所有返回值重新定义。
五．开发注意事项
使用多线程版本的API时应注意需要在每个线程中做初始化，并使用本线程的hSE操作，在线程结束前清除环境。
不能在主线程里初始化，多个子线程共享hSE。
由于用到了较多的栈资源，创建线程时需要自己定义栈的大小，设成200K以上。
六．SafeEngineAPI函数定义
初始化环境
longSEH_InitialSession（HSE*hSE,unsignedlongprivatekeydevicetype,char*privatekeydeviceparameter,char*privatekeypassword,unsignedlongprivatekeytimeout,unsignedlongcertchaindevicetype,char*certchaindeviceparameter,char*certchainpassword）
功能：
初始化环境.从设备中读取私钥,根证书.
在调用以下函数前必须先调用初始化函数初始化.
参数：
参数名
含义
In/out
参数选项
hSE
函数句柄
#definevoid*HSE
Out
Privatekeydevicetype
存储私钥的设备类型
In
见最新的设备类型说明文档
Privatekeydeviceparameter
存储私钥设备的参数
In
见最新的设备类型说明文档
若不需要私钥,可设为空字符串“”,表示不取私钥
Privatekeypassword
私钥密码
In
Privatekeytimeout
私钥超时时间.秒为单位
In
若=0，则私钥永久有效。
certchaindevicetype
存储证书链的设备类型
In
见最新的设备类型说明文档
certchaindeviceparameter
存储根证书设备的参数
In
见最新的设备类型说明文档
若不需要根证书,可设为空字符串“”,表示不取根证书
certchainpassword
根证书密码
In
返回：
SE_SUCCESS
正常返回,
SE_ERROR_LOAD_LIBRARY
装载动态库出错
SE_ERROR_PRIVATE_KEY_DEV
读写私钥设备失败
SE_ERROR_PRIVATE_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_ERROR_CONNECT
连接设备错误
SE_ERROR_DEVICE_LOCKED
设备已锁定
Example:
//私钥,证书在IC卡上.Com1口,不设超时.
HSEhSE;
SEH_InitialSession（&hSE,0x0202,"com1","password",0,0x0202,"com1","password"）;
初始化环境
longSEH_InitialSessionEx（HSE*hSE,unsignedchar*privatekey,unsignedshortprivatekeylen,char*privatekeypassword,unsignedchar*certchain,unsignedshortcertchainlen）;
功能：
初始化环境.从内存中读取私钥,根证书.
在调用以下函数前必须先调用初始化函数初始化.
参数：
参数名
含义
In/out
参数选项
HSE
函数句柄
#definevoid*HSE
Out
privatekey
加密的私钥
In
privatekeylen
私钥长度
In
privatekeypassword
私钥密码
In
如privatekeypassword为””，可以装入明文的私钥
rootcert
证书链
In
rootcertlen
证书链长度
In
返回：
SE_SUCCESS
正常返回,
SE_ERROR_LOAD_LIBRARY
装载动态库出错
SE_ERROR_PRIVATE_KEY_PASSWORD
私钥密码错误
SE_ERROR_INITIAL_SESSION
初始化错误
SE_ERROR_MEMORY
内存分配错误
SE_ERROR_PRIVATE_KEY_PASSWORD_LEN
私钥密码密码长度错误。
最长8位。
清除环境
longSEH_ClearSession（HSEhSE）
功能:
清除环境变量.
在程序结束前应调用此函数.
参数：
参数名
含义
In/out
参数选项
HSE
函数句柄
in
返回：
SE_SUCCESS
正常返回,
SE_ERROR_INITIAL_SESSION
没有初始化
SE_ERROR_LOAD_LIBRARY
装载动态库出错
SE_ERROR_CLEAR_SESSION
清除环境错误
Example:
SEH_ClearSession（hSE）;
数字签名
签名
longSEH_SignData（HSEhSE,unsignedchar*origindata,unsignedlonglength,unsignedshortsignmethod,unsignedchar*signeddata,unsignedlong*signedlength）
功能：
数字签名。
注意：
因MD5已发现漏洞，摘要算法推荐使用SHA1。
参数：
参数名
含义
In/out
参数选项
HSE
函数句柄
In
Origindata
原始数据块
In
Length
原始数据库长度
In
Signmethod
摘要算法
In
3:
SHA1
Signeddata
处理后数据块
Out
Signedlength
处理后数据库长度
Out
返回：
SE_SUCCESS
正常返回,
SE_ERROR_INITIAL_SESSION
没有初始化
SE_ERROR_LOAD_LIBRARY
装载动态库出错
SE_ERROR_SIGN
签名错误
SE_ERROR_PRIVATE_KEY_TIME_OUT
超时,私钥密码错误.
Example:
Unsignedchardatabuf[]=”testsignature”;
Unsignedcharsigndata[200];
Unsignedlongsignlen;
SEH_SignData（hSE,databuf,strlen（databuf）,3,signdata,&signlen）;
摘要
longSEH_Digest（HSEhSE,unsignedchar*data,unsignedlonglength,unsignedshortmethod,unsignedchar*digest,unsignedlong*digestlength）
功能：
摘要
注意：
因MD5已发现漏洞，摘要算法推荐使用SHA1。
参数：
参数名
含义
In/out
参数选项
HSE
函数句柄
In
Data
原始数据块
In
Length
原始数据库长度
In
Method
摘要方法
In
3:
SHA1
Digest
处理后数据块
Out
Digestlength
处理后数据长度
Out
返回：
SE_SUCCESS
正常返回,
SE_ERROR_INITIAL_SESSION
没有初始化
SE_ERROR_LOAD_LIBRARY
装载动态库出错
SE_ERROR_DIGEST
摘要错误
Example:
Unsignedchardata[]=“Digesttest”;
Unsignedchardigest[50];
Unsignedlongdigestlen;
SEH_Digest（hSE,data,strlen（data）,3,digest,&digestlen）
验证签名
longSEH_VerifySignData（HSEhSE,unsignedchar*origindata,unsignedlongoriginlength,unsignedshortsignmethod,unsignedchar*signeddata,unsignedlongsignedlength,unsignedchar*ceritificate,unsignedshortcertlength）
功能：
验证签名。
参数：
参数名
含义
In/out
参数选项
HSE
函数句柄
In
Origindata
原始数据块
In
Originlength
原始数据库长度
In
Signmethod
签名类型
In
3:
SHA1
Signeddata
签名数据块
In
Signedlength
签名数据块长度
In
Certificate
证书内容
In
Certlength
证书长度
In
返回：
SE_SUCCESS
正常返回,
SE_ERROR_INITIAL_SESSION
没有初始化
SE_ERROR_LOAD_LIBRARY
装载动态库出错
SE_ERROR_VERIFY_SIGN
验证错误
SE_ERROR_INVALID_CERT
证书错误
SE_ERROR_MEMORY
内存分配错误
Example:
unsignedchardatabuf[]=”testsignature”;
unsignedcharsigndata[200];
unsignedlongsignlen;
unsignedcharcert[2048];
unsignedshortcertlen;
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,cert,certlen）;
数字信封
longSEH_Envelope（HSEhSE,unsignedshortenvolpetype,unsignedchar*indata,unsignedlonginlength,unsignedchar*outdata,unsignedlong*outlength,unsignedchar*certificate,unsignedshortcertlength）
功能：
数字信封打包或拆解
参数：
参数名
含义
In/out
参数选项
HSE
函数句柄
In
enveloptype
信封类型
In
1组成数字信封
2拆解数字信封
Indata
原始数据块
In
Inlength
原始数据库长度
In
Outdata
处理后数据块
Out
由外部分配
Outlength
处理后数据库长度
Out
Certificate
证书内容
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_MEMORY
内存分配错误
Example:
unsignedchardata[]=”Enveloptest”;
unsignedcharenvelope;
unsignedlongenvelopelen;
unsignedcharcert[2048];
unsignedshortcertlen;
unsignedcharoutdata[100];
unsignedlongoutlen;
intrtn_code
certlen=2048;
SEH_GetSelfCertificate（hSE,0x0202,"com1","password",cert,&certlen）;
//组成
SEH_Envelope（hSE,1,data,strlen（data）,envelope,&envelopelen,cert,certlen）;
//拆解
rtn_code=SEH_Envelope（hSE,2,envelope,envelopelen,outdata,&outlen,“”,0）;
数字信封扩展
longSEH_EnvelopeEx（HSEhSE,unsignedshortenvolpetype,unsignedchar*indata,unsignedlonginlength,unsignedchar*outdata,unsignedlong*outlength,unsignedchar*certificate,unsignedshortcertlength,intAlgID）
功能：
数字信封打包或拆解
参数：
参数名
含义
In/out
参数选项
HSE
函数句柄
In
enveloptype
信封类型
In
1组成数字信封
2拆解数字信封
Indata
原始数据块
In
Inlength
原始数据库长度
In
Outdata
处理后数据块
Out
由外部分配
Outlength
处理后数据库长度
Out
Certificate
证书内容
In
在解数字信封时不起作用
Certlength
证书长度
In
在解数字信封时不起作用
AlgID
对称加密算法标识
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_MEMORY
内存分配错误
注：
打包和拆解时的加密算法标识必须相同。
Example:
unsignedchardata[]=”Enveloptest”;
unsignedcharenvelope;
unsignedlongenvelopelen;
unsignedcharoutdata[100];
unsignedlongoutlen;
intrtn_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）;
证书
从介质中获取证书
longSEH_GetSelfCertificate（HSEhSE
升级会员 