金山网址云安全开放API文档

一、概述

金山网址云安全开放 API 是金山网络为第三方开发人员提供的编程接口。您可以利用此 API 查询某个URL 的属性。

目前金山网址云安全 API 支持的功能包括:

查询一个 URL 是否是钓鱼/欺诈网站

查询一个下载 URL 是否属于病毒/木马/恶意软件下载链接

二、API说明

2.1. 通用说明

2.1.1 所有API中的都必选的参数

appkey、timestamp、sign，以及secret用于授权验证。请参考授权验证。

本文档的示例参数值为：

appkey= YXNkZmFzZGZqYXM

timestamp=1295430113.546

secret=6a204bd89f3c8348afd5c77c717a097a注意!:

- 此处为 示例参数

- 实用参数,请通过 云盾计划 获得!

2.1.2 关于urlsafe base64编码

我们有多个API中要求对参数进行base64编码，为了确保编码后的结果不会打断URI，我们采用urlsafe base64编码，它和普通base64编码的差别在于：将普通base64编码结果中的加号(+)替换成减号(-)，将斜杠(/)替换成下划线(_)

2.1.3 API调用错误代码说明

如果 API 调用失败,返回一个 json 字符串:{"success": 0, "errno": $errno, "msg": $msg}

$errno

$msg

说明

-1

AppKeyError

应用的key不存在或者key已经失效

-2

SignError

无效的签名

-3

$server_timestamp

无效的时间戳。$server_timestamp是服务器当前的时间戳

-4

CountLimit

超过当天查询次数限制

-5

SpeedLimit

查询过于频繁

-6

ArgFormatError

查询参数格式错误，例如某些API我们要求对参数进行base64编码，如果base64编码错误，服务器将返回此错误提示

-7

$arg

缺少必需的查询参数。$arg说明所缺少的具体参数名

-8

ServerBusyError

服务器繁忙

-9

ConflictStamp

重复的时间戳

2.1.4 请求限制

我们将限制每个开发者应用appkey的每天访问总量和每分钟访问量。

目前每个 appkey 的限制为:

每分钟访问上限为 1000 次,每天访问上限为 10 万次

2.2. 钓鱼查询API

功能

查询一个网址是否属于钓鱼/欺诈性质

URL

http://open.pc120.com/phish/

返回值格式

json

HTTP请求方式

GET

请求参数

参数名

必选

说明

q

true

需要查询的网址。需进行urlsafe base64编码

appkey

true

应用appkey(请参考授权验证)

timestamp

true

sign

true

返回值

查询成功返回值：{"success": 1, "phish":$phish}

查询失败返回值：{"success": 0, "errno": $errno, "msg": $msg}

(请参考错误代码说明)

$phish:-1 表示未知;0 表示非钓鱼;1 表示钓鱼;2 表示网站高风险,有钓鱼嫌疑

示例

查询 http://shenzhen-gzc.info/inde5.asp 是否是钓鱼网站

首先将 http://shenzhen-gzc.info/inde5.asp 进行 urlsafe base64 编码得出:

aHR0cDovL3NoZW56aGVuLWd6Yy5pbmZvL2luZGU1LmFzcA==

计算签名 sign(请参考授权验证)得出: 179a114e128ead44ebd298ebb0aadca6

那么请求参数为：

参数名

参数值

q

aHR0cDovL3NoZW56aGVuLWd6Yy5pbmZvL2luZGU1LmFzcA==

appkey

YXNkZmFzZGZqYXM

timestamp

1295430113.546

sign

179a114e128ead44ebd298ebb0aadca6

完整的API URL为：http://open.pc120.com/phish/?

q=aHR0cDovL3NoZW56aGVuLWd6Yy5pbmZvL2luZGU1LmFzcA==

&appkey=YXNkZmFzZGZqYXM&timestamp=1295430113.546

&sign=179a114e128ead44ebd298ebb0aadca6

访问此URL返回值为{"success": 1, "phish":1}

说明 http://shenzhen-gzc.info/inde5.asp 是钓鱼网站!

2.3. 下载安全查询

API

功能

查询一个网址是否属于病毒/木马/恶意软件下载链接

URL

http://open.pc120.com/download/

返回值格式

json

HTTP请求方式

GET

请求参数

参数名

必选

说明

q

true

需要查询的网址。需进行urlsafe base64编码

appkey

true

应用appkey(请参考授权验证)

timestamp

true

sign

true

返回值

查询成功返回值：{"success": 1, "down_type": $down_type }

查询失败返回值：{"success":0, "errno": $errno, "msg": $msg}

(请参考错误代码说明)

$down_type:1 表示未知,2 表示安全,3 表示危险,6 表示非 PE 文件

示例

查询 http://downfile.dload001122.info/2011_1_18/7/m111.exep 是否是钓鱼网站

首先将 http://downfile.dload001122.info/2011_1_18/7/m111.exe 进行 urlsafe base64 编码得出:

aHR0cDovL2Rvd25maWxlLmRsb2FkMDAxMTIyLmluZm8vMjAxMV8xXzE4LzcvbTExMS5leGU=

计算签名 sign(请参考授权验证)得出: 4fe9e5b5ab13549bec29aacc4174dfed

那么请求参数为：

参数名

参数值

q

aHR0cDovL2Rvd25maWxlLmRsb2FkMDAxMTIyLmluZm8vMj

AxMV8xXzE4LzcvbTExMS5leGU=

appkey

YXNkZmFzZGZqYXM

timestamp

1295430113.546

sign

7c99d5fb17033be491f4cff33b4d944b

完整的API URL为：http://open.pc120.com/download/?

q=aHR0cDovL2Rvd25maWxlLmRsb2FkMDAxMTIyLmluZm8vMjAxMV8xXzE4LzcvbTExMS5leGU=

&appkey=YXNkZmFzZGZqYXM&timestamp=1295430113.546

&sign=7c99d5fb17033be491f4cff33b4d944b

访问此URL返回值为: {"success": 1, "down_type ": 3}

说明 http://downfile.dload001122.info/2011_1_18/7/m111.exe 是一个病毒下载链接

三、授权以及授权验证过程

为了使用金山网址云安全开放API，需要为您的应用申请一个专属的appkey(如何申请appkey请参考

申请APPKEY。我们会为每个应用提供一个专属的appkey以及相对应的secret。其中appkey是应用的唯一标识，API将用此鉴别应用的身份。secret是给应用分配的密钥，开发者需要妥善保存这个密钥，这个密钥用来保证应用来源的的可靠性，防止被伪造。权限验证过程如下：

本文档的示例中用到的参数值为：

appkey = YXNkZmFzZGZqYXM

secret = 6a204bd89f3c8348afd5c77c717a097a

权限验证过程还需要一个参数timestamp。Timestamp为从格林威治时间1970年01月01日00时00分00秒起至现在的总秒数，本文当要求精确到毫秒。本文档中一个有效的timestamp必须满足两个条件：唯一，即一个timestamp只能使用一次；必须是5分钟内的timestamp

计算签名(sign)：首先需要生成签名字符基串(下文称此字符串为signature_base_string)。具体生成算法是，将HTTP查询参数包括GET和POST中的参数按照参数名进行文本排序，然后参数名和参数值用等号(=)连接，各个参数用&连接；将API的URI路径和上述排序之后的参数字符串用问号(?)连接之后形成signature_base_string。接下来把signature_base_string + secret组合成一个字符串，计算出此字符串的md5码作为签名sign

示例：

假设有一个应用需调用API：

http://open.pc120.com/phish/

假设参数列表为

参数名

参数值

q

aHR0cDovL3NoZW56aGVuLWd6Yy5pbmZv

appkey

YXNkZmFzZGZqYXM

timestamp

1295430113.546

那么signature_base_string为：

/phish/?appkey=YXNkZmFzZGZqYXM&q=aHR0cDovL3NoZW56aGVuLWd6Yy5pbmZv

&timestamp=1295430113.546

计算sign签名：

本示例: secret=6a204bd89f3c8348afd5c77c717a097a

md5(signature_base_string + secret)得出：

e8daf81268b84f0dfa8e13b032cd6ae9，此即签名sign

在调用API时，签名sign作为必选的参数之一

示例：

经过上2步，此时参数列表为

参数名

参数值

q

aHR0cDovL3NoZW56aGVuLWd6Yy5pbmZv

appkey

YXNkZmFzZGZqYXM

timestamp

1295430113.546

sign

e8daf81268b84f0dfa8e13b032cd6ae9

以HTTP GET方式调用API为例，符合权限验证规则的有效API URL为：

http://open.pc120.com/phish/?q=aHR0cDovL3NoZW56aGVuLWd6Yy5pbmZv

&appkey=YXNkZmFzZGZqYXM&timestamp=1295430113.546

&sign=e8daf81268b84f0dfa8e13b032cd6ae9

金山网址云安全服务器将验证appkey和sign的有效性。同时，还会检查timestamp的有效性：一个timestamp的存活期为5分钟；一个timestamp只能使用一次，再次查询必须重新生成timestamp

验证失败返回值说明请参考错误代码说明