接口说明Word下载.docx
- 文档编号:8130634
- 上传时间:2023-05-10
- 格式:DOCX
- 页数:63
- 大小:37.07KB
接口说明Word下载.docx
《接口说明Word下载.docx》由会员分享,可在线阅读,更多相关《接口说明Word下载.docx(63页珍藏版)》请在冰点文库上搜索。
通过黑名单验证证书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
存储私钥设备的参数
若不需要私钥,可设为空字符串“”,表示不取私钥
Privatekeypassword
私钥密码
Privatekeytimeout
私钥超时时间.秒为单位
若=0,则私钥永久有效。
certchaindevicetype
存储证书链的设备类型
certchaindeviceparameter
存储根证书设备的参数
若不需要根证书,可设为空字符串“”,表示不取根证书
certchainpassword
根证书密码
返回:
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,"
);
longSEH_InitialSessionEx(HSE*hSE,unsignedchar*privatekey,unsignedshortprivatekeylen,char*privatekeypassword,unsignedchar*certchain,unsignedshortcertchainlen);
初始化环境.从内存中读取私钥,根证书.
HSE
privatekey
加密的私钥
privatekeylen
私钥长度
privatekeypassword
如privatekeypassword为””,可以装入明文的私钥
rootcert
证书链
rootcertlen
证书链长度
清除环境
longSEH_ClearSession(HSEhSE)
功能:
清除环境变量.
在程序结束前应调用此函数.
in
没有初始化
SE_ERROR_CLEAR_SESSION
清除环境错误
SEH_ClearSession(hSE);
数字签名
签名
longSEH_SignData(HSEhSE,unsignedchar*origindata,unsignedlonglength,unsignedshortsignmethod,unsignedchar*signeddata,unsignedlong*signedlength)
数字签名。
注意:
因MD5已发现漏洞,摘要算法推荐使用SHA1。
Origindata
原始数据块
Length
原始数据库长度
Signmethod
摘要算法
3:
SHA1
Signeddata
处理后数据块
Signedlength
处理后数据库长度
SE_ERROR_SIGN
签名错误
SE_ERROR_PRIVATE_KEY_TIME_OUT
超时,私钥密码错误.
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)
Data
Method
摘要方法
Digest
Digestlength
处理后数据长度
SE_ERROR_DIGEST
摘要错误
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)
验证签名。
Originlength
签名类型
签名数据块
签名数据块长度
Certificate
证书内容
Certlength
证书长度
SE_ERROR_VERIFY_SIGN
验证错误
SE_ERROR_INVALID_CERT
证书错误
unsignedchardatabuf[]=”testsignature”;
unsignedcharsigndata[200];
unsignedlongsignlen;
unsignedcharcert[2048];
unsignedshortcertlen;
certlen=2048;
SEH_GetSelfCertificate(hSE,0x0202,"
cert,&
certlen);
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)
数字信封打包或拆解
enveloptype
信封类型
1组成数字信封
2拆解数字信封
Indata
Inlength
Outdata
由外部分配
Outlength
在解数字信封时不起作用
SE_ERROR_ENVEKOP
数字信封错误
证书无效.
unsignedchardata[]=”Enveloptest”;
unsignedcharenvelope;
unsignedlongenvelopelen;
unsignedcharoutdata[100];
unsignedlongoutlen;
intrtn_code
//组成
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)
AlgID
对称加密算法标识
请参考最新的设备类型说明文档
注:
打包和拆解时的加密算法标识必须相同。
//组成,用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
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 接口 说明