UKey认证接口描述
安全认证网关UKey认证旁路模式接口描述
1. 旁路模式拓扑图
2. 旁路模式时序图
3. 流程描述
1. 浏览器和证书运行环境做UKey和Pin码检查
1.1浏览器和证书环境交互获得UKey中所有证书用户列表，以下拉列表框的形式让用户选择。
1.2 用户在登录页面中选择用户名(证书的Subject CN)
1.3 用户输入PIN码，点击提交。浏览器将pin码发送给证书环境。如果用户名与PIN码不一致，返回错误。
2. 浏览器获取随机数
2.1浏览器向客户认证中心发起请求，申请用于签名的随机数。
2.2客户认证中心向SRP发起请求，申请随机数。
2.3 SRP向客户认证中心返回响应，携带随机数。
2.4客户认证中心向用户浏览器返回响应，携带随机数。
3. 浏览器从证书运行环境获取随机数签名
3.1浏览器向证书环境发送用户名(Subject CN)与随机数，获取根据用户私钥对随机数的签名。
4. 浏览器提交认证请求
4.1用户浏览器向证书环境发送用户名(Subject CN)，获取用户的公钥证书。
4.2用户浏览器携带用户的公钥证书、签名用的随机数与对随机数的签名，向客户认证中心发起认证请求。
4.3客户认证中心向SRP发起认证请求。
4.4 SRP向客户认证中心返回响应，客户认证中心根据认证结果，做后续相应处理。
4. 客户认证中心与SRP的API描述
对于旁路模式，此API为客户认证中心与SRP交互的接口，而非用户浏览器与客户认证中心的接口。用户浏览器与客户认证中心的接口可由客户自主定义。
4.1. 获取随机数
² URL
https://<IP of SRP Proxy>/--auth-pre--/aaa/cert/random
² Method
GET
² 返回数据
类型：application/json
参数：
|
参数 |
必须 |
说明 |
|
Random |
是 |
随机数。长度为24字节 |
4.2. 用户认证
² URL
https://<IP of SRP Proxy>/--auth-pre--/aaa/cert/login
² Method
POST
² 请求body
类型：application/json
参数
|
参数 |
必须 |
说明 |
|
|
Cert |
是 |
用户证书 |
|
|
Random |
是 |
随机数 |
|
|
Sign |
是 |
对随机数的签名 |
|
² 返回数据
类型：application/json
参数：
|
参数 |
必须 |
说明 |
|
error |
是 |
错误码 |
|
errormsg |
是 |
错误信息 |
|
data |
是 |
主路模式下，认证成功后的重定向URL。旁路模式下，返回用户名，客户认证中心可据此进行后续用户授权。 |
4.3. 常见错误码
|
值 |
说明 |
|
1 |
逻辑错误，如：随机数非法、证书链校验失败、校验签名失败等 |
|
2 |
SRP当前代理服务不支持UKey认证 |
|
5 |
报文参数格式非法 |
|
9 |
内部错误 |
|
10 |
数据库错误 |
|
15 |
用户被冻结 |
|
20 |
报文源IP未注册（旁路模式可禁用IP注册功能） |
|
22 |
SRP license不支持UKey认证 |
|
23 |
用户授权失败（旁路模式应禁用授权功能） |
5. 客户端(浏览器)与证书环境的API描述
包含脚本（路径请根据代码结构自行定义）：
<script src='XTXSAB.js'></script>
5.1. 初始化
² 函数
init(function() { ... }, function() { ... })
² 参数
|
参数 |
必须 |
说明 |
|
function() { ... } |
是 |
初始化成功后，执行的回调函数。 |
|
function() { ... } |
是 |
初始化失败后，执行的回调函数。 |
5.2. 获取UKey中所有证书用户列表
² 函数
SOF_GetUserList(function(ret) { ... })
² 参数
|
参数 |
必须 |
说明 |
|
function(ret) { ... } |
是 |
获取证书用户列表后，执行的回调函数。 ret.retVal包含证书ID。 ret.retVal字符串格式为： Username1||CertID1&&&Username2||CertID2&&&... 在登录页面向用户展示的应该是填充Username的下拉列表。 后续API调用，需要使用CertID作为证书标识。 |
5.3. 校验用户名与PIN码
² 函数
SOF_Login(CertID, PIN, function (ret) { ... }）
² 参数
|
参数 |
必须 |
说明 |
|
CertID |
是 |
证书ID，从证书用户列表中选中的用户名对应的CertID。 |
|
PIN |
是 |
PIN码，用户输入。 |
|
function(ret) { ... } |
是 |
校验完成后的回调函数。 ret.retVal为true，表示校验成功。 ret.retVal为false，表示校验失败。 |
5.4. 对随机数进行签名
² 函数
SOF_SignData(CertID, random, function (ret) { ... })
² 参数
|
参数 |
必须 |
说明 |
|
CertID |
是 |
证书ID，从证书用户列表中选中的用户名对应的CertID。 |
|
random |
是 |
从SRP获取的一次性随机数。 |
|
function(ret) { ... } |
是 |
校验完成后的回调函数。 ret.retVal为""，表示签名失败；否则为返回的签名值。 |
5.5. 导出用户证书
² 函数
SOF_ExportUserCert(CertID, function (ret) { ... })
² 参数
|
参数 |
必须 |
说明 |
|
CertID |
是 |
证书ID，从证书用户列表中选中的用户名对应的CertID。 |
|
function(ret) { ... } |
是 |
校验完成后的回调函数。 ret.retVal为""，表示签名失败；否则为返回的BASE64编码格式的用户证书。 |
5.6. 代码示例
语言：Javascript + Vue.js (为了兼容更多浏览器，语法并未采用ES6)
