腾讯云安全API开发手册

时间: 2014-09-02 10:55:09 分类: 服务器租用托管阅读量:
分享到:

1 综述

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 编码之后可能会增加
表1:公共参数说明


 

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 服务器内部错误
表2: 返回错误码说明

 

安全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
表3: 接口限制说明



 

7 验证码服务

验证码服务提供两个HTTP 接口,分别是拉取JavaScript API 代码和校验票据。开发的基本流程为:开发商在需要使用验证码的页面中嵌入拉取JavaScript API 代码的URL,即可在相应的页面中调用具体的JavaScript API 进行验证码的初始化、刷新和验证用户输入操作。在用户输入正确之后会返回对应的票据,开发商在获取票据之后通过校验票据接口校验票据是否合法,在收到安全API 正常返回之后即完成整个验证码的流程。
开发商在使用验证码的时候需要防范以下的风险:
    1)关于数据的签名和验签必须在开发商服务器上进行,不能在客户端进行,否则有泄漏密钥的风险。
    2)开发商在收到票据之后必须再次到安全API 进行票据校验,以确保票据的确是由安全API提供的,如果不进行校验则有被绕过的风险。

 

7.1 验证码交互流程

anquanAPIjieru_01.png

图1: 验证码时序图



 

7.2 验证码类型说明

目前验证码服务支持以下8 种类型的验证码,在拉取和校验的接口中需要根据情况选择对应的类型。

限制维度 每分钟最大访问次数 超过限制errorCode值
1 anquanAPIjieru_02.png 清晰4 位字母
2 anquanAPIjieru_03.png 清晰5 位字母
3 anquanAPIjieru_04.png 清晰6 位字母
4   清晰随机4~6 位字母
5 anquanAPIjieru_05.png 干扰4 位字母
6 anquanAPIjieru_06.png 干扰5 位字母
7 anquanAPIjieru_07.png 干扰6 位字母
8   干扰随机4~6 位字母
表4: 验证码类型



 

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数据。
表5: 验证码query 接口补充参数说明


 

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个字符  
表6: verify 接口JSON 补充说明

 

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 转换成字符串 可选 一个业务有多个场景的情况。主要用作报表统计。
表7: 验证码check 接口补充参数说明


 

完整的验证码流程需要调用query和check两个接口,同时其中的uid userip buid sceneid captype参数必须一致。
7.5.2 HTTP BODY

7.5.3 返回JSON 补充说明

errprCode errorMessage 说明
0 No Error 票据校验成功
1~20000   票据校验失败
表8: 验证码check 接口错误码说明


 

参数 说明 类型 备注
cs-nonce 随机数 uint_32转换成字符串 该随机数等于开发商调用此接口提供的随机数
cs-sig 返回数据的签名 28个字符 用于对返回的JSON 进行校验
表9: 验证码check 接口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="}

未经允许不得转载:帅东科技网站建设