接口说明.docx

接口说明.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