腾讯云安全API开发手册
2014-09-02 10:55:09

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="}