基础文档
新手指南
平台概述
- 平台提供发证业务
产品介绍
- 证书业务: 主要提供证书签发、注销、变更、延期、证书重发等操作。
基础概念解释
1、公共参数: 公共请求参数是指每个接口都需要使用到的请求参数,与业务无关;
2、业务参数: 根据调用API服务接口的需求所传递的参数;
3、签名算法: 签名算法是指数字签名的算法。数字签名(又称公钥数字签名、电子签章)是一种类似写在纸上的普通的物理签名,但是使用了公钥加密领域的技术实现,用于鉴别数字信息的方法。一套数字签名通常定义两种互补的运算,一个用于签名,另一个用于验证。
4、表单: 在网页中主要负责数据采集功能。一个表单有三个基本组成部分: 表单标签:这里面包含了处理表单数据所用CGI程序的URL以及数据提交到服务器的方法。 表单域:包含了文本框、密码框、隐藏域、多行文本框、复选框、单选框、下拉选择框和文件上传框等。 表单按钮:包括提交按钮、复位按钮和一般按钮;用于将数据传送到服务器上的CGI脚本或者取消输入,还可以用表单按钮来控制其他定义了处理脚本的处理工作。
API签名算法
认证平台的 API 是基于 HTTP(S) 协议来调用的,开发者可以直接使用我们提供的SDK(包含了请求的封装,签名加密,响应解释等)来调用, 以下主要是针对自行封装 HTTP(S) 请求进行API调用的签名算法进行详细解说。API调用除了必须包含公共参数外,API本身业务级的参数
,每个API的业务级参数请参考API文档说明。
签名算法原理
为了防止 API 调用过程中被恶意篡改,调用任何一个 API 都需要携带签名,服务端会根据请求参数,对签名进行验证,签名不合法的请求将会被拒绝。目前支持的签名算法:HMAC-SHA256(signMethod=HMAC-SHA256),签名大体过程如下:
1、对所有 API 请求参数(包括公共参数和业务参数
,但除去sign参数),根据参数名称的ASCII码表的顺序排序,将排序好的参数名和参数值拼接在一起。
2、拼接好的字符串和密钥分别按照UTF-8编码,用编码后的密钥字符流结合HmacSHA256算法对编码后的参数字符流进行摘要。
3、将摘要后的字符流转换为十六进制大写字符串,即得到签名值。
JAVA 签名示例代码
签名例子:
请求示例:
import javax.crypto.Mac; |
详细示例代码请参见 SDK 源代码。
调用示例
1、设置参数值
- format = “JSON”
- version = “1”
- appKey = “1111111”
- signMethod = “HMAC-SHA256”
- signVersion = “1”
- method = “realid.idcard.verify”
- timestamp = “2018-02-07 02:50:21”
- nonce = “随机数”
- realname = “张三”
- idcard = “111111111111111111”
2、排序
- appKey = “1111111”
- format = “JSON”
- idcard = “111111111111111111”
- method = “realid.idcard.verify”
- nonce =”随机数”
- realname = “张三”
- signMethod = “HMAC-SHA256”
- signVersion = “1”
- timestamp = “2018-02-07 02:50:21”
- version = “1”
3、拼接参数名与参数值
appKey1111111formatJSONidcard111111111111111111methodrealid.idcard.verifynonce1111111 realname 张三 signMethodHMAC-SHA256signVersion1timestamp2018-02-07 02:50:21version1
4、生成签名 假设 secretKey 为 111111,则签名结果为:
E41E6FDA4D24B27AE78281F6D71D790F55097CD558BB377A3F9343F07ADED112
API 调用协议
接口支持 HTTP,HTTPS GET/POST 请求,所有接口需在请求中加入公共参数,请求及返回结果都使用 UTF-8 字符集进行编码。
组装 HTTP(S) 请求
将所有参数名和参数值采用 UTF-8 进行 URL 编码(参数顺序可随意,但必须要包括签名参数),然后通过GET
或POST
发起请求,如:
注意事项
1、所有的请求和响应数据编码皆为 UTF-8 格式,URL 里的所有参数名和参数值请做 URL 编码。如果请求的 Content-Type 是 application/x-www-form-urlencoded,则 HTTP Body 体里的所有参数值也做 URL 编码;如果是 multipart/form-data 格式,每个表单字段的参数值无需编码, 但每个表单字段的 charset 部分需要指定为 UTF-8。
2、参数名与参数值拼装起来的 URL 长度小于 1024 个字符时,可以用 GET 发起请求;参数类型含 byte[] 类型或拼装好的请求 URL 过长时,必须用 POST 发起请求。所有 API 都可以用 POST 发起请求。
公共参数
公共请求参数是指每个接口都需要使用到的请求参数
名称 | 类型 | 是否必须 | 描述 |
---|---|---|---|
appKey | String | 是 | 身份标识,注册后获得 |
sign | String | 是 | 签名结果串,请参看 API 签名机制 |
signMethod | String | 是 | 签名算法,默认HMAC-SHA256 |
signVersion | String | 是 | 签名算法版本,目前是1 |
method | String | 是 | 服务方法/API 接口名称 |
format | String | 是 | 返回值的类型,默认JSON |
timestamp | String | 是 | 时间戳,日期格式按照 ISO8601 标准表示,并需要使用 UTC 时间。格式为 yyyy-MM-dd HH:mm:ss |
nonce | String | 是 | 唯一随机数,同样的值,10 分钟内只能被使用一次 |
version | String | 是 | API 版本号,目前版本是1 |
请求示例:
http或https://222.190.151.234:2016/具体接口地址? &appKey=XXX &sign=XXX |
响应参数
调用 API 服务后返回数据采用统一格式,code 为 0 ,请求成功,其他为失败,这时没有 data 结果信息
名称 | 类型 | 描述 |
---|---|---|
code | Integer | 状态码,0 请求成功,其他为失败 |
requestId | String | 唯一标识 |
message | String | 状态码的描述 |
data | Object | code 为 0 时出现,结果信息,具体看各个接口说明 |
成功示例
JSON示例
{ |
失败示例
JSON示例
{ |
参数加解密
调用API请求,可以开启参数加解密功能。
- 开启参数加解密后,请求参数中新增两个参数
名称 | 类型 | 是否必须 | 描述 |
---|---|---|---|
encryptionEnable | String | 是 | 是否开启参数加解密 |
encMethod | String | 是 | 参数加解密方法(AES或者SM4) |
开启参数加解密后,请求URL变为:
SDK开启参数加密后,请求API时,在服务端进行解密后进行相应业务操作,服务端返回加密响应结果,需要对响应结果进行解密。
加密方法中的加密密钥是根据appSecret生成。
Api 错误码说明
错误码解释
错误码 | 错误说明 |
---|---|
30201000 | 系统错误 |
30201001 | 服务异常,请联系客服 |
30201002 | 远程服务错误 |
30201003 | 请求参数错误(XX)XX,请参考API文档 |
30201004 | 请求参数无效, 请参考API文档 |
30201005 | 不支持的签名算法XX |
30201006 | APP错误 |
30201007 | 验签失败 |
30201008 | 重复请求 |
30201009 | 请求过期 |
30201010 | 无法访问当前接口 |
30201011 | 请求的IP(XX) 不在允许访问接口的白名单中 |
30201012 | 请求超时 |
30201013 | APP已禁用 |
30201014 | 服务限流 |
30201015 | 你的(XX)不支持密钥算法(XX) |
30201016 | 你的(XX)没有权限使用此密钥算法(XX) |
30201017 | 需要更新的证书(XX)不存在 |
30201018 | 需要注销的证书(XX)不存在 |
30201019 | 密钥对业务索引大于密钥对索引总数 |
30201020 | 当前应用可用密钥对数量为空 |
30201021 | 缺少交易账号 |
30201022 | 证书操作校验失败:(XX) |
30201023 | 缺少请求参数:appkey |
30201024 | 缺少交易密码 |
30201025 | 缺少扩展信息 |
30201026 | App可用密钥对数已用完 |
30201027 | 流量达到上限 |
公共请求参数
公共请求参数详情及示例
公共请求参数是指每个接口都需要使用到的请求参数
名称 | 类型 | 是否必须 | 描述 |
---|---|---|---|
appKey | String | 是 | 身份标识,注册后获得 |
sign | String | 是 | 签名结果串,请参看 API 签名机制 |
signMethod | String | 是 | 签名算法,默认HMAC-SHA256 |
signVersion | String | 是 | 签名算法版本,目前是1 |
method | String | 是 | 服务方法/API 接口名称 |
format | String | 是 | 返回值的类型,默认JSON |
timestamp | String | 是 | 时间戳,日期格式按照 ISO8601 标准表示,并需要使用 UTC 时间。格式为yyyy-MM-dd HH:mm:ss |
nonce | String | 是 | 唯一随机数,同样的值,10 分钟内只能被使用一次 |
version | String | 是 | API 版本号,目前版本是 1 |
证书业务辅助工具类
证书 SDK 相关操作的辅助工具类,以供开发者参考.
P10Util
P10 操作工具类
根据主题项生成 P10
|
AdapteBaseCertificate
证书信息读取工具类
根据证书base64字符串读取证书信息
|
申请随机数工具类
GetRandom
申请随机数工具类
申请随机数
一、请求说明
请求方式:POST
请求参数以表单形式提交,Content-Type 值为: application/x-www-form-urlencoded;charset=utf-8
二、请求参数(请求方式为 post)
名称 | 类型 | 是否必须 | 描述 |
---|---|---|---|
appKey | String | 是 | 身份标识,注册后获得 |
signMethod | String | 是 | 签名算法,默认HMAC-SHA256 |
signVersion | String | 是 | 签名算法版本,目前是1 |
method | String | 是 | 服务方法/API 接口名称 |
format | String | 是 | 返回值的类型,默认JSON |
timestamp | String | 是 | 时间戳,日期格式按照 ISO8601 标准表示,并需要使用 UTC 时间。格式为 yyyy-MM-dd HH:mm:ss |
nonce | String | 是 | 唯一随机数,同样的值,10 分钟内只能被使用一次 |
version | String | 是 | API 版本号,目前版本是1 |
sign | String | 是 | 签名结果串,请参看 API 签名机制 |
nLength | String | 是 | 随机数长度 |
x-request-id | String | 是 | 请求标识 |
注意:在postman中,除了x-request-id需要放在Headers中,其余参数均在Body中以application/x-www-form-urlencoded方式提交
代码实例
/** |
三、响应参数
- 返回结构说明
字段名称 | 描述 |
---|---|
code | 此次请求的结果 0-此次请求成功 其他-此次请求异常 |
message | 此次请求结果的描述,success-成功 其他-异常参见异常码 |
requestId | 此次请求的全局唯一标识 |
data | 此次请求响应的负载,接口的响应信息主体 |
success | 请求结果,true为成功,其余失败 |
- 返回值data说明
字段名称 | 描述 |
---|---|
incorrect | 随机数结果响应码 |
dataHexStr | 随机数-byte数组的字符串 |
四、成功示例
JSON示例
{ |
五、失败示例
JSON示例
{ |
对称加解密工具类
AES加解密工具类
AES加解密工具类
import javax.crypto.*; |
SM4加解密工具类
SM4加解密工具类
import cn.unitid.easypki.crypto.CipherException; |