SafeEngine API - 上海市数字证书认证中心.doc

UniTrust? SafeEngine API 接口说明 上海市电子商务安全证书管理中心有限公司 文档说明： SafeEngine API的接口说明 版本信息： 当前版本 2.3 版权信息： SHECA是上海市电子商务安全证书管理中心有限公司的注册商标和缩写。 UCA 是上海市电子商务安全证书管理中心有限公司研究开发的通用证书系统的商标和缩写。 本文的版权属于上海市电子商务安全证书管理中心有限公司，未经许可，任何个人和团体不得转载、粘贴或发布本文，也不得部分的转载、粘贴或发布本文，更不得更改本文的部分词汇进行转贴。 未经许可不得拷贝，影印。 Copyright @2000 上海市电子商务安全证书管理中心有限公司 一．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 获取证书用途 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 一．SafeEngine API函数的目的 该接口是为所有应用程序开发者提供安全平台接口，提供程序开发人员1024/128位强度的加密算法，可以与任何使用UCA证书的应用软件集成，所有的安全机制有该接口实现（包括证书验证，黑名单查询等等）。 二．SafeEngine API函数说明 本接口提供以下版本：win9x/NT, solaris，aix，sco，unixware，linux，hpux，freebsd。 接口提供以下功能： 数字信封，数字签名，验证签名，摘要，对称加解密，PEM编解码。 从磁盘，IC卡等介质中读取证书，私钥，证书验证（包括CRL，OCSP验证），证书解码。 为了保护用户的私钥，使开发人员不能取得用户私钥，API接口不提供获取明文私钥的函数。所有私钥都在接口内部保存，使用。 由于API支持各种常用平台，建议在服务器端开发时使用SafeEngine API。在客户端使用UniTrust证书管理器API，方便用户使用。 ?关于多线程的说明：SafeEngine本身支持多线程。但有的设备在读写，内部运算时是不支持多线程的。如果用到了这些设备，需要应用来处理解决多线程的冲突问题。 建议使用多线程接口。单线程接口在以后的版本中将不再支持。 三．安装说明 在Windows下需要安装UniTrust 证书管理器V2.26或以上版本，所有需要的库将随证书管理器一起安装。 安装需要使用的设备的驱动包。 在Unix下，将所有库文件拷贝到/usr/lib目录下，将UniTrustCMBConfig.ini文件拷贝到/ect目录下。程序执行时要求/etc目录有读权限。 四．版本说明 本文档对应SafeEngine V版。 版更新： 增加了设备错误的返回代码定义。 增加了设备检测相关辅助函数。 2.3版更新： 修正了软件生成随机数重复的问题。 2.2版更新： 对设备类型编号做了新的定义，从short类型(16bits)改为long类型(32bits)。详细说明请参考《设备类型说明》文档。 支持同一介质中多对密钥的使用。 兼容新旧版UniTrust介质规范。 下载黑名单支持标准LDAP URL。 2.1版更新： 为了增加对SSF33算法的支持，新增了带加密算法标识的对称加解密函数，数字信封函数SE(H)_EncryptDataEx，SE(H)_DecryptDataEx，SE(H)_EnvelopeE