1 综述
安全API是腾讯云安全为开发商提供的业务安全类服务,致力于将腾讯在业务安全方面积累的技术和经验分享给开发商。安全API通过打造一个简单开放的接口,让您快速获得专业的安全能力。
2 接入方式
目前安全API 提供的接入方式为:HTTP+JSON。
安全API 域名:http://api.guard.qcloud.com/
3 接入说明
开发商需要根据不同的接口说明组装成不同的URL 进行访问,同时必须对URL 中的信息进行HMAC-SHA1签名,签名中需要使用密钥。密钥是开发商调用安全API 的唯一凭证,信息较为敏感,请勿泄漏。登录腾讯云安全,进入安全服务详情->安全API服务->密钥管理获取密钥,具体流程可以参考安全API接入步骤。
URL生成说明:
1)URL中的参数必须依据各个接的参数说明提供,包括参数的取值范围,都必须符合要求,安全API 会对各个URL 进行严格的控制。
2)每次对安全API 的访问都需要对请求数据进行签名,并将签名的数据作为cs-sig 的值置于URL 的末尾。签名算法为:cs-sig=Base64(HMAC-SHA1(secretkey,plaintext))。其中plaintext 为原文。
3)原文由三个部分组成:body,method,url。其中url 是从接口名开始到“&cs-sig” 之前的所有字符(完成URL 编码之后)。plaintext=“body=&method=&url=”。具体示例请参考各接口中的示例。
4)URL 中的所有参数值都需要进行URL 编码包括cs-sig。
5)如果一个交易过程中涉及到多个接口,那么接口中相同参数的值必须一致,除时间戳、随机数和签名除外。
6)URL 的最大长度为2048byte。
4 公共参数说明
安全API所有接口都必须包括下表中的公共参数,并且针对不同的接口会补充对应的参数,详见各个接口说明。
参数 | 说明 | 类型 | 备注 |
---|---|---|---|
cs-secretid | 开发商申请的ID,每个ID 对应一个KEY | 36 个字符 | |
cs-nonce | 随机数,用于放置重放攻击,注意避免重复 | uint_32 转换成字符串 | |
cs-timestamp | 发起请求时的Unix 时间 | uint_32 转换成字符串 | 请求方的时间与安全API服务器的时间差不超过2个小时 |
cs-sig | 使用KEY 对原文签名 | 签名后长度为28 个字符,进行URL 编码之后可能会增加 |
5 公共返回说明
安全API的返回格式为:JSON。JSON中至少包括errorCode和errorMessage字段,errorCode为整形,errorMessage为字符串。对于不同的接口可能会包含其他的字段,具体的补充字段见各个接口的说明。如果接口的请求方为开发商,并且errorCode为0~20000(指具体业务的错误码),则安全API会对返回的信息利用开发商cs-secretid对应的KEY进行签名和BASE64编码,字段名为cs-sig,包含在JSON报文体中。 除"cs-sig"外的所有字段按字典升序排列。
带签名的返回JSON 示例:
返回JSON
{"cs-nonce":10582,"errorCode":0,"errorMessage":"No Error","cs-sig":"bkWWo87saUEXw1XeKk8m+ooxUbY="}
签名
bkWWo87saUEXw1XeKk8m+ooxUbY=
原文
{"cs-nonce":10582,"errorCode":0,"errorMessage":"No Error"}
errorCode | errorMessage | 说明 |
---|---|---|
0 | No Error | |
1~20000 | 业务相关的错误具体的原因参考各接口说明 | |
40000 | Bad Request:Bad URI | URI 格式错误:比如参数值没有进行URI编码 |
40001 | Bad Request:Bad Pararment | 参数错误:比如缺少必要的参数 |
40002 | Bad Request:Version Error | 版本错误:比如不支持此版本接口 |
40003 | Frequency Overrun:APPID-URI-UID | 访问频率超限,维度不同参考表3 |
40004 | Frequency Overrun:APPID-URI-USERIP | 访问频率超限,维度不同参考表3 |
40005 | Frequency Overrun:APPID-URI-USERIP-UID | 访问频率超限,维度不同参考表3 |
40006 | cs-secretid Does Not Exist | cs-secretid 不存在 |
40007 | Sign Failed | 验签失败 |
40008 | Forbidden | 重放攻击 |
40009 | Interface Does Not Exist | 接口不存在 |
40010 | Bad Request Method | 错误的请求方法 |
40010 | Bad Request Method | 错误的请求方法 |
40011 | Request-URI Is Too Long | Request-URI 太长 |
40012 | Expired Timestamp | 时间戳过期 |
50000 | Internal Server Error | 服务器内部错误 |
安全API 的调用方可能是开发商的用户或者是开发商本身,如果调用方是开发商的用户,那么安全API 需要在调用接口之后将响应的信息返回给开发商。目前主要方式有两种JavaScript API和Iframe 内嵌页面,安全API 暂时只提供JavaScript 方式,具体的示例可参考相应的接口说明。
6 接口限制说明
出于安全考虑,安全API 对接口做调用次数限制,参考参数有:
a) APPID 开发商ID,安全API 会根据开发商的secretid 找到对应的ID。
b) URI 具体的接口。
c) UID 开发商的用户ID。
d) USERIP 用户调用者的IP。
通过以上四个参数组成三个维度,如果某个维度调用接口的次数超过限制,该维度的接口调用会被禁止调用直到被解锁,具体返回的错误码见表2。具体限制如下表:
限制维度 | 每分钟最大访问次数 | 超过限制errorCode值 | 锁定时长(分钟) |
---|---|---|---|
APPID + URI + UID | 120 | 40003 | 10 |
APPID + URI + USERIP | 3600 | 40004 | 10 |
APPID + URI + USERIP + UID | 60 | 40005 | 10 |
7 验证码服务
验证码服务提供两个HTTP 接口,分别是拉取JavaScript API 代码和校验票据。开发的基本流程为:开发商在需要使用验证码的页面中嵌入拉取JavaScript API 代码的URL,即可在相应的页面中调用具体的JavaScript API 进行验证码的初始化、刷新和验证用户输入操作。在用户输入正确之后会返回对应的票据,开发商在获取票据之后通过校验票据接口校验票据是否合法,在收到安全API 正常返回之后即完成整个验证码的流程。
开发商在使用验证码的时候需要防范以下的风险:
1)关于数据的签名和验签必须在开发商服务器上进行,不能在客户端进行,否则有泄漏密钥的风险。
2)开发商在收到票据之后必须再次到安全API 进行票据校验,以确保票据的确是由安全API提供的,如果不进行校验则有被绕过的风险。
7.1 验证码交互流程
7.2 验证码类型说明
目前验证码服务支持以下8 种类型的验证码,在拉取和校验的接口中需要根据情况选择对应的类型。
限制维度 | 每分钟最大访问次数 | 超过限制errorCode值 |
---|---|---|
1 | 清晰4 位字母 | |
2 | 清晰5 位字母 | |
3 | 清晰6 位字母 | |
4 | 清晰随机4~6 位字母 | |
5 | 干扰4 位字母 | |
6 | 干扰5 位字母 | |
7 | 干扰6 位字母 | |
8 | 干扰随机4~6 位字母 |
7.3 拉取验证码服务的JavaScript API
开发商在需要使用验证码的页面中嵌入拉取验证码服务的URL,如果正确调用,则接口会返回验证码服务JavaScript API,开发商可以在页面中调用相应的API 接口实现图片的显示、用户输入校验等功能;如果错误调用将会返回JSON 数据,开发商可以通过接口参数callback 或burl 设置回跳方式。
接口:/v1/captcha/query
方法:GET
7.3.1 URL 补充参数说明
参数 | 说明 | 类型 | 属性 | 备注 |
---|---|---|---|---|
userip | 开发商的用户IP | 必选 | ||
buid | 业务id | uint_32 转换成字符串 | 必选 | 用于支持开发商的多种业务。主要用作报表统计。 |
captype | 验证码类型 | uint_16 转换成字符串 | 必选 | 拉取验证码和校验验证码的验证码类型必须一致,取值范围见表4 |
uid | 开发商的用户ID | uint_32 转换成字符串 | 可选 | uid>0 |
sceneid | 场景ID | uint_32 转换成字符串 | 可选 | 一个业务有多个场景的情况。主要用作报表统计。 |
callback | query 接口执行失败的情况下JavaScript 回调函数 | 可选 | 如果参数值为空,则失败情况下安全API 直接返回JSON数据。如果非空返回数据为函数名加JSON数据。 |
7.3.2 HTTP BODY
无
7.3.3 返回JSON 补充说明
在正确调用query 接口的情况下,会返回验证码服务的JavaScript API;错误调用情况下会返回公共JSON 数据,参考表1。
7.3.4 示例信息
请求URL
http://api.guard.qcloud.com/v1/captcha/query?cs-secretid=AKIDjgc41LLRFaNdKVBP3EqxYdCIrYAEoyYb&cs-uid=3&cs-nonce=3716&cs-timestamp=1407901116&buid=1&sceneid=1&captype=2&userip=121.14.96.121&callback=callback&cs-sig=13RViFo7jEoaF9Wxs1xN7%2FXkFhk%3D
签名原文
“body=&method=GET&url=/v1/captcha/query?cs-secretid=AKIDjgc41LLRFaNdKVBP3EqxYdCIrYAEoyYb&cs-uid=3&cs-nonce=3716&cs-timestamp=1407901116&buid=1&sceneid=1&captype=2&userip=121.14.96.121&callback=callback”
错误调用返回示例
callback({"errorCode":40001,"errorMessage":"Bad Request:Bad Pararment"})
7.4 验证码服务的JavaScript API 说明
开发商在页面上嵌入query 接口的URL 加载验证码的JavaScript API;然后调用JavaScript API 进行初始化、显示图片、验证输入的操作。
7.4.1 初始化
TSOCapObj.init(imgid)
说明:初始化
参数:imgid 显示验证码图片的img 元素id
7.4.2 更新图片
TSOCapObj.refresh()
7.4.3 验证用户输入
TSOCapObj.verify(ans, reCallFun)
说明:验证用户填写的验证码答案
参数:ans 用户输入的答案
参数:reCallFun 验证完后回调的函数。
验证用户输入之后会调用reCallFun 函数,其参数为JSON 数据,JSON 数据中包括公共返回参数,如果用户输入正确则包括票据,如果用户输入错误则没有票据。开发商可以在reCallFun 函数中判断errorCode,如果errorCode==0,则表示用户输入正确,开发商拿到票据之后做进一步操作。如果返回为errorCode!=0,建议直接提示用户。
参数 | 说明 | 类型 | 备注 |
---|---|---|---|
ticket | 用户输入正确验证码后的返回票据 | 64个字符 |
7.4.4 JavaScript API 使用DEMO
<html> <head> <script type="text/javascript" src="http://api.guard.qcloud.com/v1/captcha/query?cs-secretid=AKIDjgc41LLRFaNdKVBP3EqxYdCIrYAEoyYb &cs-uid=3&cs-nonce=3716&cs-timestamp=1407901116&buid=1&sceneid=1&captype=2 &userip=121.14.96.121&callback=callback&cs-sig=13RViFo7jEoaF9Wxs1xN7%2FXkFhk%3D"></script> </head> <body> <form action="action.php" method="post" id="login"> <!--验证码显示--> <input type="text" value="" name="vcode" id="tc_vcode_input"/> <input type="hidden" value="" name="ticket" id="ticket"/> <img src="" id="tc_vcode_img"/> <a href="javascript:TSOCapObj.refresh();">换一张</a><br/> <input type=button onclick="verify()" value=提交> </form> </body> <script> window.onload=function() { //初始化,参数传入显示验证码的img元素id TSOCapObj.init("tc_vcode_img"); //刷新拉取验证码图片 TSOCapObj.refresh(); } //验证验证码答案 function verify() { //获取用户输入 var ans = document.getElementById("tc_vcode_input").value; //验证答案,验证完成后会回调第二个参数传入的函数 TSOCapObj.verify(ans, OnVerifyVCode); } function OnVerifyVCode(ret_json) { //返回的json数据格式{errorCode:XXX, ticket:XXX, errorMessage:XXX} if(ret_json.errorCode!=0) { var obj = document.getElementById("tc_vcode_input"); obj.value = ""; TSOCapObj.refresh(); } else { //验证码验证通过,继续业务处理 var obj = document.getElementById("ticket"); obj.value = ret_json.ticket;<br> document.getElementById("login").submit(); } } </script> </html>
7.5 验证票据
开发商在用户输入正确之后会获取安全API 返回的票据,开发商必须将此票据通过本接口进行校验,以确认票据是从安全API 返回的,否则将可能导致验证码功能被绕过。
接口:/v1/captcha/check
方法:GET
7.5.1 URL 补充参数说明
参数 | 说明 | 类型 | 属性 | 备注 |
---|---|---|---|---|
userip | 开发商的用户IP | 必选 | ||
buid | 业务id | uint_32 转换成字符串 | 必选 | 用于支持开发商的多种业务。主要用作报表统计。 |
captype | 验证码类型 | uint_16 转换成字符串 | 必选 | |
ticket | 用户输入正确验证码之后的票据 | 必选 | ||
uid | 开发商的用户ID | uint_32 转换成字符串 | 可选 | uid>0 |
sceneid | 场景ID | uint_32 转换成字符串 | 可选 | 一个业务有多个场景的情况。主要用作报表统计。 |
完整的验证码流程需要调用query和check两个接口,同时其中的uid userip buid sceneid captype参数必须一致。
7.5.2 HTTP BODY
无
7.5.3 返回JSON 补充说明
errprCode | errorMessage | 说明 |
---|---|---|
0 | No Error | 票据校验成功 |
1~20000 | 票据校验失败 |
参数 | 说明 | 类型 | 备注 |
---|---|---|---|
cs-nonce | 随机数 | uint_32转换成字符串 | 该随机数等于开发商调用此接口提供的随机数 |
cs-sig | 返回数据的签名 | 28个字符 | 用于对返回的JSON 进行校验 |
7.5.4 示例信息
请求URL
http://api.guard.qcloud.com/v1/captcha/check?cs-secretid=AKIDjgc41LLRFaNdKVBP3EqxYdCIrYAEoyYb&cs-uid=3&cs-nonce=27366&cs-timestamp=1407901347&buid=1&sceneid=1&captype=2&ticket=0NgMMxgZnJKKL1_HKuaNGdnhgYag6faZFSfpcJ4QEO2cQWEwyoshU6R-kKrJAemI&userip=121.14.96.121&cs-sig=JtwPu1y52BAP8T24PJhRyj7mSmI%3D
签名原文
"body=&method=GET&url=/v1/captcha/check?cs-secretid=AKIDjgc41LLRFaNdKVBP3EqxYdCIrYAEoyYb&cs-uid=3&cs-nonce=27366&cs-timestamp=1407901347&buid=1&sceneid=1&captype=2&ticket=0NgMMxgZnJKKL1_HKuaNGdnhgYag6faZFSfpcJ4QEO2cQWEwyoshU6R-kKrJAemI&userip=121.14.96.121"
成功信息返回
{"cs-nonce":27366,"errorCode":0,"errorMessage":"No Error","cs-sig":"bkWWo87cdefew1XeKk8m+ooxUbY="}
失败信息返回
{"cs-nonce":27366,"errorCode":10,"errorMessage":"Bad Captype","cs-sig":"bkWWo87cdefew1XeKk8m+ooxUbY="}