Safe Browsing Update API (v4)

概览

借助 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"]
    }
  }]
}

客户信息

clientID 和 clientVersion 字段应该唯一标识客户端实现，而不是单个用户。（客户端日志记录用于客户端信息。您可以为客户端 ID 选择任何名称，但我们建议您选择一个代表客户端真实身份的名称，例如，您的公司名称将以一个全小写字母表示的单词。）

安全浏览列表

系统会合并 threatType、platformType 和 threatEntryType 字段以标识（安全浏览）安全浏览列表。该示例标识了一个列表：MALWARE/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=="}
    ]
  }
}

客户信息

clientID 和 clientVersion 字段应该唯一标识客户端实现，而不是单个用户。（客户端日志记录用于客户端信息。您可以为客户端 ID 选择任何名称，但我们建议您选择一个代表客户端真实身份的名称，例如，您的公司名称将以一个全小写字母表示的单词。）

所有客户端状态

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

安全浏览列表

threatTypes、platformTypes 和 threatEntryTypes 字段相结合可标识（命名）安全浏览列表。此示例中列出了两个列表：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 字段是可选字段，它提供关于威胁匹配的更多信息。目前，MALWARE/WINDOWS/网址 安全浏览列表提供了元数据（请参阅元数据）。

缓存时长

cacheDuration 和 negativeCacheDuration 字段指示哈希必须被视为不安全或安全的时间（请参阅缓存）。

最短等待时长

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