SOF 本地服务接口说明
SOF 本地服务接口说明
版权所有：西部 CA 北京分公司
SOF 本地服务接口说明
修订记录：

修订日期	人员	版本	修订内容
2021/8/25	李牧卿	V1.0

版权所有：西部 CA 北京分公司
SOF 本地服务接口说明
1.引言
1.1 概述
该文档用于程序员跨浏览器调用 USBKey，本插件基于标准 SKF 库（GMT 0016-2012）开发，通过发送插件发送 post 请求完成和 USBKey 的交互，可以兼容多厂商的 USBKey。接口采用 SOF 标准库进行设计，本款插件可以满足常规 PKI 证书应用需求，有 着良好的兼容性和可移植性。
1.2 接口支持平台/浏览器
支持平台：
windows
支持浏览器：
Chrome，Firefox，IE（5,6,7+）
1.3 通信协议
通信协议采用 https，在通信过程中，为了统一字符集，交易报文采用 UTF-8 格式传送。
版权所有：西部 CA 北京分公司
SOF 本地服务接口说明
2.函数列表

函数接口	功能描述	备注
SOF_GetVersion	获取版本号
SOF_EnumDevice	枚举设备
SOF_LoadLibrary	加载 SKF 库
SOF_GetDeviceInstance	加载设备应用
SOF_GetDeviceInfo	获取设备信息
SOF_Login	登录
SOF_ChangePassWd	修改密码
SOF_GetPinRetryCount	获取 PIN 码剩余尝试次数
SOF_EnumCertContainer	枚举容器
SOF_ExportUserCert	获取用户证书
SOF_GetUserList	获取用户列表
SOF_GetCertInfo	获取证书信息
SOF_SetDigestMethod	设置摘要算法
SOF_DigestData	摘要计算
SOF_SignData	签名计算
SOF_GenRandom	随机数生成
SOF_VerifySignedData	验证签名

版权所有：西部 CA 北京分公司
SOF 本地服务接口说明

SOF_DeleteContainer	删除容器
SOF_EncryptData	数据加密（数字信封）
SOF_DecryptData	数据解密（数字信封）
SOF_GenerateP10Request	产生 P10 请求
SOF_ImportCert	导入签名证书
SOF_GetTempPublicKey	获取临时公钥
SOF_ImportCryptoCertAndKey	导入加密证书

版权所有：西部 CA 北京分公司
SOF 本地服务接口说明
3.接口说明
3.1 获取版本号
3.1.1 函数原型
SOF_GetVersion();
3.1.2 输入项
无
3.1.3 返回值
version 版本号
3.1.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_GetVersion"}
Response 接收	{"version" : "V1.0.0.0"}

3.2 加载 SKF 库
3.2.1 函数原型
SOF_LoadLibrary(BSTR libname)
3.2.2 输入项
libname SKF 库名称
3.2.3 返回值
status 0 为成功，其他为错误码
3.2.4 函数示例

JSON 数据实例

版权所有：西部 CA 北京分公司
SOF 本地服务接口说明

POST 发送	"function":"SOF_LoadLibrary","libname":dll_name}
Response 接收	{"status" : 0}

3.3 枚举设备
3.3.1 函数原型
SOF_EnumDevice()
3.3.2 输入项
无
3.3.3 返回值
DeviceNameList 设备列表
3.3.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_EnumDevice"}
Response 接收	{"DeviceNameList" : "AB5278C3B8A6245BC509C0B28DBA45D"}

3.4 加载设备应用
3.4.1 函数原型
SOF_GetDeviceInstance(BSTR DeviceName, BSTR Application)
3.4.2 输入项
DeviceName 设备标识
Application 应用名称（NULL 则默认打开第一个应用）
版权所有：西部 CA 北京分公司
SOF 本地服务接口说明
3.4.3 返回值
status 0 为成功，其他为错误码
3.4.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_GetDeviceInstance","DeviceName":devicename, "Application":"NULL"}
Response 接收	{"status" : 0}

3.5 获取设备信息
3.5.1 函数原型
SOF_GetDeviceInfo(BSTR ulType)
3.5.2 输入项
ulType 设备信息标识（详情见附录）
3.5.3 返回值
DeviceInfo 设备信息
3.5.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_GetDeviceInfo","ulType":"DEVICE_FREE_SAPCE"}
Response 接收	{"DeviceInfo" : "124032"}

版权所有：西部 CA 北京分公司
SOF 本地服务接口说明
3.6 登录
3.6.1 函数原型
SOF_Login(BSTR PassWd)
3.6.2 输入项
PassWd Pin 码
3.6.3 返回值
status 0 为成功，其他为错误码
3.6.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_Login","PassWd":pwd}
Response 接收	{"status" : 0}

3.7 修改密码
3.7.1 函数原型
SOF_ChangePassWd(BSTR OldPassWd, BSTR NewPassWd)
3.7.2 输入项
OldPassWd 旧 Pin 码
NewPassWd 新 Pin 码
3.7.3 返回值
status 0 为成功，其他为错误码
版权所有：西部 CA 北京分公司
SOF 本地服务接口说明
3.7.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_ChangePassWd","OldPassWd":pwd,"NewPassWd":newpwd}
Response 接收	{"status" : 0}

3.8 获取 PIN 码剩余尝试次数
3.8.1 函数原型
SOF_GetPinRetryCount()
3.8.2 输入项
无
3.8.3 返回值
RetryNum 剩余尝试次数
3.8.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_GetPinRetryCount"}
Response 接收	{"RetryNum" : "10"}

3.9 枚举容器
3.9.1 函数原型
SOF_EnumCertContainer()
版权所有：西部 CA 北京分公司
SOF 本地服务接口说明
3.9.2 输入项
无
3.9.3 返回值
ContainerList 容器列表
3.9.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_EnumCertContainer"}
Response 接收	{"ContainerList" : "1C97C699F8"}

3.10 获取用户证书
3.10.1 函数原型
SOF_ExportUserCert(BSTR ContainerName, BSTR CertType)
3.10.2 输入项
ContainerName 容器名称
CertType 证书类型（1 为签名证书，0 为加密证书）
3.10.3 返回值
Cert BASE64 编码的证书
3.10.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_ExportUserCert","ContainerName":con_name, "CertType":cert_type}

版权所有：西部 CA 北京分公司
SOF 本地服务接口说明

Response 接收

{"Cert" : ":BASE64CERT"}

3.11 获取用户列表
3.11.1 函数原型
SOF_GetUserList()
3.11.2 输入项
无
3.11.3 返回值
UserList 用户列表
3.11.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_GetUserList"}
Response 接收	{"UserList" : "test||1C97C699F8"}

3.12 获取证书信息
3.12.1 函数原型
SOF_GetCertInfo(BSTR Base64EncodeCert, BSTR Type )
3.12.2 输入项
Base64EncodeCert BASE64 编码的证书
Type 证书信息标识（详情见附录）
版权所有：西部 CA 北京分公司
SOF 本地服务接口说明
3.12.3 返回值
CertInfo 证书信息
3.12.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_GetCertInfo","Base64EncodeCert":cert_base64,"Type":type} type 为 int 型
Response 接收	{ "CertInfo" : "V3"}

3.13 设置摘要算法
3.13.1 函数原型
SOF_SetDigestMethod(int DigestMethod)
3.13.2 输入项
DigestMethod 算法标识（1：SM3，2：SHA1，4：SHA256）
3.13.3 返回值
status 0 为成功，其他为错误码
3.13.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_SetDigestMethod","DigestMethod":type}; type 为 int 型
Response 接收	{"status" : 0}

版权所有：西部 CA 北京分公司
SOF 本地服务接口说明
3.14 摘要计算
3.14.1 函数原型
SOF_DigestData(BSTR InData, BSTR ContainerName)
3.14.2 输入项
InData Base64 编码的原文
ContainerName 容器名称
3.14.3 返回值
DigestData 摘要数据
3.14.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_DigestData","InData":"YWJj","ContainerName":con_name}
Response 接收	{"DigestData" : "qZk+NkcGgWq6PiVxeFDCbJzQ2J0="}

3.15 签名计算
3.15.1 函数原型
SOF_SignData(BSTR InData, BSTR ContainerName)
3.15.2 输入项
InData Base64 编码的原文
ContainerName 容器名称
3.15.3 返回值
SignData BASE64 编码的签名数据
版权所有：西部 CA 北京分公司
SOF 本地服务接口说明
3.15.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_SignData","InData":indata,"ContainerName":con_name}
Response 接收	{ "SignData" : " BASE64 SIGN "}

3.16 验证签名
3.16.1 函数原型
SOF_VerifySignedData(BSTR Base64EncodeCert, BSTR InData, BSTR SignValue)
3.16.2 输入项
Base64EncodeCert BASE64 编码的签名证书
InData BASE64 编码的原文
SignValue BASE64 编码的签名值
3.16.3 返回值
status 0 为验证通过，其他为错误码
3.16.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_VerifySignedData","Base64EncodeCert":cert_base64, "InData":SOF_Sign_InData_Base64,"SignValue":sign_data}
Response 接收	{"status" : 0}

版权所有：西部 CA 北京分公司
SOF 本地服务接口说明
3.17 随机数生成
3.17.1 函数原型
SOF_GenRandom(int RandomLen)
3.17.2 输入项
RandomLen 随机数长度(字节)
3.17.3 返回值
RamdomBase64 BASE64 编码的随机数
3.17.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_GenRandom","RandomLen":3}
Response 接收	{ "RamdomBase64" : "0YZg"}

3.18 删除容器
3.18.1 函数原型
SOF_DeleteContainer(BSTR ContainerName)
3.18.2 输入项
ContainerName 容器名称
3.18.3 返回值
status 0 为成功，其他为错误码
3.18.4 函数示例

JSON 数据实例

版权所有：西部 CA 北京分公司
SOF 本地服务接口说明

POST 发送	{"function":"SOF_DeleteContainer","ContainerName":con_name}
Response 接收	{"status" : 0}

3.19 数据加密（数字信封）
3.19.1 函数原型
SOF_EncryptData(BSTR InData, BSTR CertBase64)
3.19.2 输入项
InData 原文
CertBase64 BASE64 编码的加密证书
3.19.3 返回值
EncryptData BASE64 编码的数字信封
3.19.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_EncryptData","InData":indata,"CertBase64":cert_base64}
Response 接收	{ "EncryptData" : "BASE64 EncryptData"}

3.20 数字解密（数字信封）
3.20.1 函数原型
SOF_DecryptData(BSTR InData, BSTR ContainerName)
3.20.2 输入项
InData 数字信封
版权所有：西部 CA 北京分公司
SOF 本地服务接口说明
ContainerName 容器名称
3.20.3 返回值
DecryptData 加密原文
3.20.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_DecryptData","InData":Encrypt_Data, "ContainerName":con_name}
Response 接收	{ "DecryptData" : "abc"}

3.21 产生 P10 请求
3.21.1 函数原型
SOF_GenerateP10Request(BSTR DN, BSTR Pin, BSTR Alg, BSTR KeyLen)
3.21.2 输入项
DN DN 项
Pin PIN 码
Alg 秘钥标识（RSA 或者 SM2）
KeyLen 秘钥长度
3.21.3 返回值
P10Base64 P10 请求
ContainerName 容器名称
3.21.4 函数示例

JSON 数据实例

版权所有：西部 CA 北京分公司
SOF 本地服务接口说明

POST 发送	{"function":"SOF_GenerateP10Request","DN":DN_str,"Pin":pin_str, "Alg":Alg_str,"KeyLen":KeyLen}
Response 接收	{ "ContainerName" : "285E58CA51", "P10Base64" : "BASE P10"}

3.22 导入签名证书
3.22.1 函数原型
SOF_ImportCert(BSTR SignCertBase64, BSTR ContainerName)
3.22.2 输入项
SignCertBase64 BASE64 编码的签名证书
ContainerName 容器名称
3.22.3 返回值
status 0 为成功，其他为错误码
3.22.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_ImportCert","SignCertBase64":cert,"ContainerName":con_name}
Response 接收	{"status" : 0}

3.23 获取临时公钥
3.23.1 函数原型
SOF_GetTempPublicKey()
版权所有：西部 CA 北京分公司
SOF 本地服务接口说明
3.23.2 输入项
无
3.23.3 返回值
TempPublicKey BASE64 编码的临时公钥
3.23.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_GetTempPublicKey"}
Response 接收	{ "TempPublicKey" : " "}

3.24 导入加密证书
3.24.1 函数原型
SOF_ImportCryptoCertAndKey(BSTR CryptoCert,
BSTR EncryptedPrivateKey,
BSTR sessionkey,
BSTR ContainerName)
3.24.2 输入项
CryptoCert 加密证书
EncryptedPrivateKey 会话秘钥保护的私钥
Sessionkey 临时公钥保护的会话秘钥
ContainerName 容器名称
3.24.3 返回值
status 0 为成功，其他为错误码
版权所有：西部 CA 北京分公司
SOF 本地服务接口说明
3.24.4 函数示例

	JSON 数据实例
POST 发送	{"function":"SOF_ImportCryptoCertAndKey","CryptoCert":cert, "EncryptedPrivateKey":privatekey,"EncryptedSessionKey":sessionkey, "ContainerName":con_name}
Response 接收	{"status" : 0}

版权所有：西部 CA 北京分公司
SOF 本地服务接口说明
4.调用示例
4.1 插件安装
双击安装 AisinoCertSrv
AisinoCert
4.2 浏览器发送/接收请求

function mTokenPluginCreate_POST(json) { if(_xmlhttp == null) { if (window.XMLHttpRequest) // code for IE7+, Firefox, Chrome, Opera, Safari { _xmlhttp = new XMLHttpRequest(); } else // code for IE6, IE5 { _xmlhttp = new ActiveXObject("Microsoft.XMLHTTP"); } } _xmlhttp.onreadystatechange=callback;

版权所有：西部 CA 北京分公司
SOF 本地服务接口说明

_xmlhttp.open("POST", _url, true); _xmlhttp.setRequestHeader("Content-type", "application/x-www-form-urlencoded"); _xmlhttp.send(json); } function callback() { //接收响应数据 www.2cto.com //判断对象状态是否交互完成，如果为 4 则交互完成 if(_xmlhttp.readyState == 4) { //判断对象状态是否交互成功,如果成功则为 200 if(_xmlhttp.status == 200) { //接收数据,得到服务器输出的纯文本数据 var response_POST = _xmlhttp.responseText; //SOF_JSON document.getElementById("SOF_JSON").value = response_POST; var obj = JSON.parse(response_POST); } else if(_xmlhttp.status == 490) { alert(_xmlhttp.statusText); }

版权所有：西部 CA 北京分公司
SOF 本地服务接口说明

else { alert(_xmlhttp.statusText); } } }

版权所有：西部 CA 北京分公司