Safe Browsing Update API (v4)

概览

借助 Update API,您的客户端应用可以下载安全浏览列表的哈希版本,以便存储在本地数据库中。然后,可以在本地检查网址。仅当在本地数据库中找到匹配项时,客户端才需要向安全浏览服务器发送请求,以验证相应网址是否包含在安全浏览列表中。

在使用 Update API 之前,您需要设置一个本地数据库。安全浏览功能提供了一个 Go 软件包,可让您顺利上手。如需了解详情,请参阅本地数据库下的“数据库设置”部分。

更新本地数据库

为了随时掌握最新动态,客户端必须定期更新其本地数据库中的安全浏览列表。为了节省带宽,客户端会下载网址的哈希前缀(而不是原始网址)。例如,如果“www.badurl.com/”位于安全浏览列表中,客户端会下载该网址的 SHA256 哈希前缀,而不是网址本身。在大多数情况下,哈希前缀的长度为 4 个字节,这意味着下载单个列表条目的平均带宽成本在压缩前为 4 个字节。

如需更新本地数据库中的安全浏览列表,请向 threatListUpdates.fetch 方法发送 HTTP POST 请求:

  • HTTP POST 请求包含要更新的列表的名称以及各种客户端限制,以考虑内存和带宽限制。
  • HTTP POST 响应会返回完整更新或部分更新。响应可以返回最短等待时长。

示例:threatListUpdates.fetch

HTTP POST 请求

在以下示例中,请求了对单个安全浏览列表的更新。

请求标头

请求标头包含请求网址和内容类型。请务必用您的 API 密钥替换网址中的 API_KEY

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1
Content-Type: application/json

请求正文

请求正文包含客户端信息(ID 和版本)和更新信息(列表名称、列表状态和客户端限制条件)。如需了解详情,请参阅 threatListUpdates.fetch 请求正文以及代码示例后面的说明。

{
  "client": {
    "clientId":       "yourcompanyname",
    "clientVersion":  "1.5.2"
  },
  "listUpdateRequests": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "state":           "Gg4IBBADIgYQgBAiAQEoAQ==",
    "constraints": {
      "maxUpdateEntries":      2048,
      "maxDatabaseEntries":    4096,
      "region":                "US",
      "supportedCompressions": ["RAW"]
    }
  }]
}
客户端信息

clientIDclientVersion 字段应唯一标识客户端实现,而不是单个用户。(在服务器端的日志记录中使用客户端信息。您可以为客户端 ID 选择任何名称,但我们建议您选择一个能代表客户真实身份的名称,例如您的公司名称,该名称以一个单词的形式显示,且全部采用小写字母。)

安全浏览列表

我们将 threatTypeplatformTypethreatEntryType 字段组合在一起,以标识安全浏览列表(名称)。在此示例中,识别出了一个列表:恶意软件/WINDOWS/网址。在发送请求之前,请确保您指定的类型组合有效(请参阅安全浏览列表)。

客户端状态

state 字段包含安全浏览列表的当前客户端状态。 (threatListUpdates.fetch 响应newClientState 字段中会返回客户端状态。)对于初始更新,请将 state 字段留空。

尺寸限制

maxUpdateEntries 字段指定客户端可以管理的更新总数(在示例中为 2048 个)。maxDatabaseEntries 字段指定本地数据库可以管理的条目总数(在示例中为 4096 个)。客户端应设置大小限制,以保护内存和带宽限制,并防止名单增长。如需了解详情,请参阅更新限制条件

支持压缩

supportedCompressions 字段会列出客户端支持的压缩类型。在该示例中,客户端仅支持未压缩的原始数据。不过,“安全浏览”功能支持其他压缩类型(请参阅压缩)。

HTTP POST 响应

在此示例中,响应会使用请求的压缩类型返回对安全浏览列表的部分更新。

响应标头

响应标头包含 HTTP 状态代码和内容类型。收到非 HTTP/200 状态代码的客户端必须进入退避模式(请参阅请求频率)。

HTTP/1.1 200 OK
Content-Type: application/json

响应正文

响应正文包含更新信息(列表名称、响应类型、要应用于本地数据库的添加和移除操作、新客户端状态,以及校验和)。在该示例中,响应还包含最短等待时长。如需了解详情,请参阅 threatListUpdates.fetch 响应正文以及代码示例后面的说明。

{
  "listUpdateResponses": [{
    "threatType":      "MALWARE",
    "threatEntryType": "URL",
    "platformType":    "WINDOWS",
    "responseType" :   "PARTIAL_UPDATE",
    "additions": [{
      "compressionType": "RAW",
      "rawHashes": {
        "prefixSize": 4,
        "rawHashes":  "rnGLoQ=="
      }
    }],
    "removals": [{
      "compressionType": "RAW",
      "rawIndices": {
        "indices": [0, 2, 4]
      }
    }],
    "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
    "checksum": {
      "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
    }
  }],
  "minimumWaitDuration": "593.440s"
}
数据库更新

responseType 字段将指示部分或完全更新。该示例中返回了部分更新,因此响应同时包含添加和移除操作。您可以添加多组内容,但只能添加一组移除内容(请参阅数据库更新)。

新客户端状态

newClientState 字段包含最近更新的安全浏览列表的新客户端状态。 客户端必须保存新的客户端状态以用于后续更新请求(threatListUpdates.fetch 请求中的 state 字段或 fullHashes.find 请求中的 clientStates 字段)。

校验和

校验和可让客户端验证本地数据库没有损坏。如果校验和不匹配,客户端必须清除数据库并重新发出带有空 state 字段的更新。不过,在这种情况下,客户端仍必须遵守相应时间间隔进行更新(请参阅请求频率)。

最短等待时长

minimumWaitDuration 字段指示客户端必须等待 593.44 秒(9.89 分钟)才能发送另一个更新请求。请注意,响应中不一定包含等待期(请参阅请求频率)。

检查网址

如需检查某个网址是否在安全浏览列表中,客户端必须先计算网址的哈希值和哈希值前缀(请参阅网址和哈希处理)。然后,客户端会查询本地数据库以确定是否有匹配项。如果本地数据库中不存在哈希前缀,则相应网址会被视为安全网址(不在安全浏览列表中)。

如果本地数据库中存在哈希前缀(哈希前缀冲突),则客户端必须将哈希前缀发送到安全浏览服务器进行验证。 服务器将返回包含给定哈希前缀的所有完整长度 SHA 256 哈希。 如果其中某个完整长度的哈希值与相关网址的完整哈希值匹配,系统就会将该网址视为不安全。如果所有完整长度的哈希值与相关网址的完整哈希值都不匹配,则该网址会被视为安全网址。

Google 绝不会了解您正在检查的网址。Google 确实会了解网址的哈希前缀,但哈希前缀并不会提供有关实际网址的很多信息。

如需检查某个网址是否在安全浏览列表中,请向 fullHashes.find 方法发送 HTTP POST 请求:

  • HTTP POST 请求最多可包含 500 个威胁条目。
  • HTTP POST 请求包含要检查的网址的哈希前缀。我们建议客户端在单个请求中批量处理多个威胁条目,以降低带宽使用量。
  • HTTP POST 响应会返回匹配的完整长度哈希以及正缓存时长和负缓存时长。响应还可以返回最短等待时长。

示例:fullHashes.find

HTTP POST 请求

在以下示例中,系统会发送两个安全浏览列表的名称和三个哈希前缀,以进行比较和验证。

请求标头

请求标头包含请求网址和内容类型。请务必将您的 API 密钥替换为网址中的 API_KEY

POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1
Content-Type: application/json

请求正文

请求正文包含客户端信息(ID 和版本)、客户端状态和威胁信息(列表名称和哈希前缀)。对于 JSON 请求,必须以 base64 编码形式发送哈希前缀。 如需了解详情,请参阅 fullHashes.find 请求正文及代码示例后面的说明。

{
  "client": {
    "clientId":      "yourcompanyname",
    "clientVersion": "1.5.2"
  },
  "clientStates": [
    "ChAIARABGAEiAzAwMSiAEDABEAE=",
    "ChAIAhABGAEiAzAwMSiAEDABEOgH"
  ],
  "threatInfo": {
    "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes":    ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"hash": "WwuJdQ=="},
      {"hash": "771MOg=="},
      {"hash": "5eOrwQ=="}
    ]
  }
}
客户端信息

clientIDclientVersion 字段应唯一标识客户端实现,而不是单个用户。(在服务器端的日志记录中使用客户端信息。您可以为客户端 ID 选择任何名称,但建议您选择一个能代表客户真实身份的名称,例如您的公司名称,该名称以一个单词的形式显示,且全部采用小写字母。)

所有客户端状态

clientStates 字段包含客户端本地数据库中所有安全浏览列表的客户端状态。(threatListUpdates.fetch 响应newClientState 字段中会返回客户端状态。)

安全浏览列表

threatTypesplatformTypesthreatEntryTypes 字段会组合起来标识(名称)安全浏览列表。在该示例中,标识了两个列表:MALWARE/WINDOWS/网址 和 SOCIAL_ENGINEERING/WINDOWS/网址。在发送请求之前,请确保您指定的类型组合有效(请参阅安全浏览列表)。

威胁哈希前缀

threatEntries 数组包含您要检查的网址的哈希前缀。 hash 字段包含的哈希前缀必须与本地数据库中存在的确切哈希前缀完全一致。例如,如果本地哈希前缀的长度为 4 个字节,则威胁条目的长度必须为 4 个字节。如果本地哈希前缀延长至 7 个字节,则威胁条目的长度必须为 7 个字节。

在此示例中,请求包含三个哈希前缀。系统会将所有这三个前缀与每个安全浏览列表进行对比,以确定是否存在匹配的完整长度哈希。

注意:Update API 和 fullHashes.find 方法应始终使用 hash 字段,而非 URL 字段(请参阅 ThreatEntry)。

HTTP POST 响应

在以下示例中,响应会返回按安全浏览列表整理的匹配数据,以及缓存和等待时长。

响应标头

响应标头包含 HTTP 状态代码和内容类型。收到非 HTTP/200 状态代码的客户端必须退避(请参阅请求频率)。

HTTP/1.1 200 OK
Content-Type: application/json

响应正文

响应正文包含匹配信息(列表名称和完整长度哈希、元数据(如果有)以及缓存时长)。在本示例中,响应正文还包含最短等待时长。如需了解详情,请参阅 fullHashes.find 响应正文和代码示例后面的说明。

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
    },
    "threatEntryMetadata": {
      "entries": [{
        "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==",  // base64-encoded "malware_threat_type"
        "value": "TEFORElORw=="  // base64-encoded "LANDING"
       }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "SOCIAL_ENGINEERING",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
    },
    "threatEntryMetadata": {
      "entries": []
    },
    "cacheDuration": "300.000s"
  }],
  "minimumWaitDuration": "300.000s",
  "negativeCacheDuration": "300.000s"
}
匹配项

匹配对象会返回两个哈希前缀的匹配完整长度哈希。与这些哈希值对应的网址被视为不安全网址。找不到第三个哈希前缀的匹配项,因此不会返回任何内容;与此哈希前缀对应的网址被视为安全网址。

请注意,此示例将一个完整长度的哈希与一个哈希前缀匹配;但是,可能会有多个完整哈希映射到同一哈希前缀。

元数据

threatEntryMetadata 字段为可选字段,用于提供有关威胁匹配的额外信息。目前,可在恶意软件/WINDOWS/网址安全浏览列表中找到元数据(请参阅元数据)。

缓存时长

cacheDurationnegativeCacheDuration 字段用于指明必须将哈希视为不安全或安全的多长时间(请参阅缓存)。

最短等待时长

minimumWaitDuration 字段指示客户端必须等待 300 秒(5 分钟)才能发送另一个 fullHashes 请求。请注意,响应中不一定包含等待期(请参阅请求频率)。