Overview

简介

请注意:此文档目前仍处于开发阶段。预计不久后会有改进。

Google 安全浏览 v5 是 Google 安全浏览 v4 的进阶版。v5 中的两项主要变更是数据新鲜度和 IP 隐私。此外,我们改进了 API Surface,以提高灵活性、效率并减少膨胀。而且,Google 安全浏览 v5 可以使从 v4 轻松进行迁移。

目前,Google 同时提供 v4 和 v5,且都被视为已做好正式发布准备。您可以使用 v4 或 v5。我们尚未宣布停用 v4 的日期;如果停用,我们会至少提前一年发出通知。本页面将介绍 v5 以及从 v4 到 v5 的迁移指南;完整的 v4 文档仍然可用

数据新鲜度

Google 安全浏览 v5 相对于 v4(具体而言就是 v4 Update API)的一项重大改进是数据新鲜度和覆盖范围。由于保护功能在很大程度上依赖于客户端维护的本地数据库,因此本地数据库更新的延迟和大小是导致保护缺失的主要原因。在 v4 中,典型的客户端需要 20 到 50 分钟来获取最新版本的威胁列表。遗憾的是,网络钓鱼攻击迅速蔓延:截至 2021 年,60% 的提供攻击的网站的存留时间不到 10 分钟。我们的分析表明,大约 25-30% 的钓鱼式攻击防护功能都是由于数据过时造成的。此外,部分设备无法管理完整的 Google 安全浏览威胁列表,而且该列表的数量还在不断增大。

在 v5 中,我们引入了一种称为实时保护的操作模式。这样可以规避上述数据过时问题。在 v4 中,客户端应下载并维护本地数据库,对本地下载的威胁列表执行检查,然后在部分前缀匹配时执行下载完整哈希的请求。在 v5 中,虽然客户端应继续下载并维护威胁列表的本地数据库,但客户端现在还需要下载可能良性的站点列表(称为全局缓存),对该全局缓存执行本地检查以及本地威胁列表检查,最后,当威胁列表存在部分前缀匹配时,在全局缓存中执行完全匹配具有不匹配的情况时,执行下载。(如需详细了解客户端所需的本地处理,请参阅以下提供的过程。)这表示从“默认允许”改为“默认检查”,随着网络威胁迅速传播,这可以加强防护。换言之,该协议旨在提供近乎实时的保护:我们的目标是让客户从最新的 Google 安全浏览数据中受益。

IP 隐私

Google 安全浏览功能(v4 或 v5)在处理请求时不会处理与用户身份相关的信息。Cookie 发送后会被忽略。Google 可以知道请求的来源 IP 地址,但 Google 只会将这些 IP 地址用于基本的网络需求(即发送响应)和防 DoS 任务。

在 v5 中,我们引入了名为 Safe Browsing Oblivious HTTP Gateway API 的配套 API。此机制使用 Oblivious HTTP 向 Google 隐藏最终用户的 IP 地址。它的工作原理是让非合作第三方处理用户请求的加密版本,然后将其转发给 Google。因此,第三方只能访问 IP 地址,而 Google 只能访问请求的内容。第三方运营 Oblivious HTTP Relay(例如 Fastly 的这项服务),而 Google 运营 Oblivious HTTP Gateway。这是一个可选的配套 API。当该功能与 Google 安全浏览功能结合使用时,系统不会再将最终用户的 IP 地址发送给 Google。

适当用法

允许的使用情形

Safe Browsing API 只能用于非商业用途(即“并非用于销售或创收”)。如果您需要用于商业目的的解决方案,请参阅 Web Risk

价格

所有 Google Safe Browsing API 均免费。

配额

开发者启用 Safe Browsing API 后,系统会为其分配默认的用量配额。您可以在 Google Developer Console 中查看当前的分配和用量。如果您预计使用的配额会超过当前分配的配额,您可以通过 Play 管理中心的“配额”界面申请更多配额。我们会审核这些要求,并在申请增加配额时需要联系人,以确保我们的服务可用性满足所有用户的需求。

适当的网址

Google 安全浏览功能旨在对会显示在浏览器地址栏中的网址执行操作。而不是用于检查子资源(例如,HTML 文件引用的 JavaScript 或图片,或由 JavaScript 启动的 WebSocket 网址)。不应对 Google 安全浏览功能检查此类子资源网址。

如果访问某个网址时发生了重定向(例如 HTTP 301),Google 安全浏览功能会对该重定向的网址进行检查。客户端网址操纵(例如 History.pushState不会让 Google 安全浏览功能检查新网址。

用户警告

如果您使用 Google 安全浏览功能针对特定网页向用户发出警告,则需遵循以下准则。

这些准则会明确说明网页并非 100% 确定是否为不安全的网络资源,并且这些警告仅指明可能的风险,从而帮助您和 Google 避免误解。

  • 在用户可见的警告中,您不得引导用户相信相关网页毫无疑问是不安全的网络资源。在提及被识别的网页或它可能给用户带来的潜在风险时,您必须使用以下字词限定警告:疑似、有可能、很可能。
  • 您的警告必须让用户能够通过查看 Google 对各种威胁的定义了解详情。建议使用以下链接:
  • 当您针对被安全浏览服务认定为存在风险的网页显示警告时,必须添加“Google 提供的警告”行以及指向安全浏览警告的链接,注明内容来自 Google。如果您的商品还根据其他来源显示警告,则不得在源自非 Google 数据的警告中包含 Google 提供方说明。
  • 您必须在产品文档中提供通知,告知用户 Google 安全浏览提供的保护功能并不完美。必须告知他们,可能出现误报(标记为有风险的安全网站)和假负例(未标记有风险的网站)。我们建议您使用以下语言:

    Google 致力于提供有关不安全网络资源的最准确和最新信息。不过,Google 无法保证其信息全面且没有错误:一些有风险的网站可能未被识别,而一些安全网站可能会被错误地识别。

操作模式

Google 安全浏览 v5 允许客户端从三种操作模式中进行选择。

实时模式

当客户端选择以实时模式使用 Google 安全浏览 v5 时,客户端将在其本地数据库中维护以下资源:(i) 一个包含可能良性的网站的全局缓存,采用主机后缀/路径前缀网址表达式的 SHA256 哈希格式;(ii) 一组威胁列表,采用主机后缀/路径前缀网址表达式的 SHA256 哈希前缀格式。概括来讲,每当客户端想要检查特定网址时,都会使用全局缓存执行本地检查。如果该检查通过,则会执行本地威胁列表检查。否则,客户端会继续进行实时哈希检查,如下所述。

除本地数据库外,客户端还会维护一个本地缓存。此类本地缓存无需存储在永久性存储空间中,可在内存紧张时被清除。

下面提供了详细的流程规范。

本地列表模式

当客户端选择在此模式下使用 Google 安全浏览 v5 时,客户端行为与 v4 Update API 类似,只不过使用的 API Surface 经过改进 v5。客户端将在其本地数据库中维护一组威胁列表,其格式为主机后缀/路径前缀网址表达式的 SHA256 哈希前缀。只要客户端希望检查特定网址,就会使用本地威胁列表执行检查。当且仅当存在匹配项时,客户端才会连接到服务器以继续检查。

与上述情况一样,客户端还将维护一个无需存储在永久性存储空间中的本地缓存。

“无存储空间”实时模式

当客户端选择在无存储空间实时模式下使用 Google 安全浏览 v5 时,无需维护任何本地数据库。每当客户端想要检查特定网址时,客户端都会连接到服务器以执行检查。此模式类似于 v4 Lookup API 的客户端可能实现的模式。

检查网址

本部分包含有关客户端检查网址的详细规范。

网址规范化

在检查任何网址之前,客户端应该对该网址执行某种规范化。

首先,我们假设客户端已根据 RFC 2396 解析网址并使其有效。如果网址使用国际化域名 (IDN),客户端应将网址转换为 ASCII Punycode 表示法。网址必须包含路径组成部分;也就是说,域名后面必须至少有一条斜杠(http://google.com/ 而不是 http://google.com)。

首先,从网址中移除制表符 (0x09)、CR (0x0d) 和 LF (0x0a) 字符。请勿移除这些字符的转义序列(例如 %0a)。

其次,如果网址以片段结尾,请移除片段。例如,将 http://google.com/#frag 缩短为 http://google.com/

第三,反复对网址执行百分号取消转义,直到网址不再有百分号转义。(这可能会导致网址无效。)

如需将主机名规范化,请执行以下操作

从网址中提取主机名,然后:

  1. 移除所有前导和尾随的点。
  2. 用单点替换连续的点。
  3. 如果主机名可以解析为 IPv4 地址,请将其标准化为 4 个以点分隔的小数值。客户端应处理所有合法的 IP 地址编码,包括八进制、十六进制以及少于四个组成部分。
  4. 如果主机名可以解析为带括号的 IPv6 地址,请对其进行标准化,方法是移除组成部分中不必要的前导零,并使用双冒号语法合并零组成部分。例如,[2001:0db8:0000::1] 应转换为 [2001:db8::1]。如果主机名是以下两种特殊 IPv6 地址类型之一,请将其转换为 IPv4:
    • IPv4 映射的 IPv6 地址(例如 [::ffff:1.2.3.4]),它应转换为 1.2.3.4
    • 使用众所周知的前缀 64:ff9b::/96(例如 [64:ff9b::1.2.3.4])的 NAT64 地址,应将其转换为 1.2.3.4
  5. 将整个字符串小写。

如需对路径进行规范化,请执行以下操作

  1. 通过将 /./ 替换为 /,并移除 /../ 以及前面的路径组成部分,解析路径中的序列 /..//./
  2. 将连续斜杠替换成单个斜杠字符。

请勿将这些路径规范化应用于查询参数。

在网址中,对所有 <= ASCII 32、>= 127、#% 的字符进行百分号转义。转义字符应使用大写的十六进制字符。

主机后缀路径前缀表达式

网址规范化后,下一步是创建后缀/前缀表达式。每个后缀/前缀表达式均由主机后缀(或完整主机)和路径前缀(或完整路径)组成。

客户端最多可构成 30 个不同的主机后缀和路径前缀组合。这些组合仅使用网址的主机和路径组成部分。方案、用户名、密码和端口会被舍弃。如果网址包含查询参数,则至少有一个组合将包含完整路径和查询参数。

对于主机,客户端最多可尝试 5 个不同的字符串。它们是:

  • 如果主机名不是 IPv4 或 IPv6 字面量,则以 eTLD+1 网域开头并添加连续的前导组件,形成最多 4 个主机名。应根据公共后缀列表来确定 eTLD+1。例如,使用 a.b.example.com 会导致 eTLD+1 网域为 example.com,以及具有一个额外主机组件 b.example.com 的主机。
  • 网址中的确切主机名。按照前面的示例,系统会检查 a.b.example.com

对于路径,客户端最多可尝试 6 个不同的字符串。他们分别是:

  • 网址的确切路径包括查询参数。
  • 网址的确切路径不包含查询参数。
  • 从根部 (/) 开始并连续附加路径组成部分(包括尾随斜杠)形成的四个路径。

以下示例演示了检查行为:

对于网址 http://a.b.com/1/2.html?param=1,客户端将尝试以下可能的字符串:

a.b.com/1/2.html?param=1
a.b.com/1/2.html
a.b.com/
a.b.com/1/
b.com/1/2.html?param=1
b.com/1/2.html
b.com/
b.com/1/

对于网址 http://a.b.c.d.e.f.com/1.html,客户端将尝试以下可能的字符串:

a.b.c.d.e.f.com/1.html
a.b.c.d.e.f.com/
c.d.e.f.com/1.html
c.d.e.f.com/
d.e.f.com/1.html
d.e.f.com/
e.f.com/1.html
e.f.com/
f.com/1.html
f.com/

(注意:请跳过 b.c.d.e.f.com,因为我们只获取最后五个主机名的组成部分以及完整的主机名。)

对于网址 http://1.2.3.4/1/,客户端将尝试以下可能的字符串:

1.2.3.4/1/
1.2.3.4/

对于网址 http://example.co.uk/1,客户端将尝试以下可能的字符串:

example.co.uk/1
example.co.uk/

哈希技术

Google 安全浏览功能仅使用 SHA256 作为哈希函数。应对上述表达式应用此哈希函数。

根据具体情况,完整的 32 字节哈希会被截断为 4 字节、8 字节或 16 字节:

  • 使用 hashes.search 方法时,我们目前要求将请求中的哈希值截断为正好 4 个字节。在此请求中发送额外的字节将会侵犯用户隐私。

  • 使用 hashList.get 方法hashLists.batchGet 方法 下载本地数据库的列表时,服务器发送的哈希值的长度会受到列表性质以及客户端对哈希值长度的偏好(通过 desired_hash_length 参数传达)的影响。

实时网址检查过程

当客户端选择实时操作模式时,就会用到此过程。

此过程接受单个网址 u 并返回 SAFEUNSAFEUNSURE。如果它返回 SAFE,则 Google 安全浏览功能会认为该网址是安全的。如果网址返回 UNSAFE,Google 安全浏览功能会认为该网址可能不安全,并应采取适当的措施,例如向最终用户显示警告、将收到的邮件移至“垃圾邮件”文件夹,或要求用户进行额外的确认才能继续操作。如果它返回 UNSURE,则应在之后使用以下本地检查过程。

  1. expressions 成为网址 u 生成的后缀/前缀表达式列表。
  2. expressionHashes 为列表,其中元素是 expressions 中每个表达式的 SHA256 哈希值。
  3. 对于 expressionHashes 的每个 hash
    1. 如果可以在全局缓存中找到 hash,则返回 UNSURE
  4. expressionHashPrefixes 是一个列表,其中元素是 expressionHashes 中每个哈希值的前 4 个字节。
  5. 对于 expressionHashPrefixes 的每个 expressionHashPrefix
    1. 在本地缓存中查找 expressionHashPrefix
    2. 如果找到缓存条目:
      1. 确定当前时间是否晚于其到期时间。
      2. 如果数值较大,请执行以下操作:
        1. 从本地缓存中移除找到的已缓存条目。
        2. 继续循环。
      3. 如果小于等于,请执行以下操作:
        1. expressionHashPrefixes 中移除此特定 expressionHashPrefix
        2. 检查是否在缓存条目中找到了 expressionHashes 中对应的完整哈希。
        3. 如果找到,则返回 UNSAFE
        4. 如果找不到,请继续循环。
    3. 如果未找到缓存条目,请继续循环。
  6. 使用 RPC SearchHashes 或 REST 方法 hashes.searchexpressionHashPrefixes 发送到 Google 安全浏览 v5 服务器。如果发生错误(包括网络连接错误、HTTP 错误等),则返回 UNSURE。否则,让响应是从 SB 服务器收到的 response,这是一个完整哈希列表,其中包含一些用于识别威胁性质(社会工程学、恶意软件等)的辅助信息,以及缓存到期时间 expiration
  7. 对于 response 的每个 fullHash
    1. fullHashexpiration 一起插入本地缓存。
  8. 对于 response 的每个 fullHash
    1. isFound 是在 expressionHashes 中发现 fullHash 的结果。
    2. 如果 isFound 为 False,则继续循环。
    3. 如果 isFound 为 True,则返回 UNSAFE
  9. 返回 SAFE

LocalThreat 列表网址检查过程

当客户端选择本地列表操作模式时,将使用此过程。当上述 RealTimeCheck 过程的客户端返回 UNSURE 的值时,也会用到它。

此过程接受单个网址 u 并返回 SAFEUNSAFE

  1. expressions 成为网址 u 生成的后缀/前缀表达式列表。
  2. expressionHashes 为列表,其中元素是 expressions 中每个表达式的 SHA256 哈希值。
  3. expressionHashPrefixes 是一个列表,其中元素是 expressionHashes 中每个哈希值的前 4 个字节。
  4. 对于 expressionHashPrefixes 的每个 expressionHashPrefix
    1. 在本地缓存中查找 expressionHashPrefix
    2. 如果找到缓存条目:
      1. 确定当前时间是否晚于其到期时间。
      2. 如果数值较大,请执行以下操作:
        1. 从本地缓存中移除找到的已缓存条目。
        2. 继续循环。
      3. 如果小于等于,请执行以下操作:
        1. expressionHashPrefixes 中移除此特定 expressionHashPrefix
        2. 检查是否在缓存条目中找到了 expressionHashes 中对应的完整哈希。
        3. 如果找到,则返回 UNSAFE
        4. 如果找不到,请继续循环。
    3. 如果未找到缓存条目,请继续循环。
  5. 对于 expressionHashPrefixes 的每个 expressionHashPrefix
    1. 在本地威胁列表数据库中查找 expressionHashPrefix
    2. 如果在本地威胁列表数据库中找不到 expressionHashPrefix,请将其从 expressionHashPrefixes 中移除。
  6. 使用 RPC SearchHashes 或 REST 方法 hashes.searchexpressionHashPrefixes 发送到 Google 安全浏览 v5 服务器。如果发生错误(包括网络连接错误、HTTP 错误等),则返回 SAFE。否则,让响应是从 SB 服务器收到的 response,这是一个完整哈希列表,其中包含一些用于识别威胁性质(社会工程学、恶意软件等)的辅助信息,以及缓存到期时间 expiration
  7. 对于 response 的每个 fullHash
    1. fullHashexpiration 一起插入本地缓存。
  8. 对于 response 的每个 fullHash
    1. isFound 是在 expressionHashes 中发现 fullHash 的结果。
    2. 如果 isFound 为 False,则继续循环。
    3. 如果 isFound 为 True,则返回 UNSAFE
  9. 返回 SAFE

不使用本地数据库的实时 网址 检查过程

当客户端选择无存储空间的实时操作模式时,会用到此过程。

此过程接受单个网址 u 并返回 SAFEUNSAFE

  1. expressions 成为网址 u 生成的后缀/前缀表达式列表。
  2. expressionHashes 为列表,其中元素是 expressions 中每个表达式的 SHA256 哈希值。
  3. expressionHashPrefixes 是一个列表,其中元素是 expressionHashes 中每个哈希值的前 4 个字节。
  4. 对于 expressionHashPrefixes 的每个 expressionHashPrefix
    1. 在本地缓存中查找 expressionHashPrefix
    2. 如果找到缓存条目:
      1. 确定当前时间是否晚于其到期时间。
      2. 如果数值较大,请执行以下操作:
        1. 从本地缓存中移除找到的已缓存条目。
        2. 继续循环。
      3. 如果小于等于,请执行以下操作:
        1. expressionHashPrefixes 中移除此特定 expressionHashPrefix
        2. 检查是否在缓存条目中找到了 expressionHashes 中对应的完整哈希。
        3. 如果找到,则返回 UNSAFE
        4. 如果找不到,请继续循环。
    3. 如果未找到缓存条目,请继续循环。
  5. 使用 RPC SearchHashes 或 REST 方法 hashes.searchexpressionHashPrefixes 发送到 Google 安全浏览 v5 服务器。如果发生错误(包括网络连接错误、HTTP 错误等),则返回 SAFE。否则,让响应是从 SB 服务器收到的 response,这是一个完整哈希列表,其中包含一些用于识别威胁性质(社会工程学、恶意软件等)的辅助信息,以及缓存到期时间 expiration
  6. 对于 response 的每个 fullHash
    1. fullHashexpiration 一起插入本地缓存。
  7. 对于 response 的每个 fullHash
    1. isFound 是在 expressionHashes 中发现 fullHash 的结果。
    2. 如果 isFound 为 False,则继续循环。
    3. 如果 isFound 为 True,则返回 UNSAFE
  8. 返回 SAFE

本地数据库维护

Google 安全浏览 v5 要求客户端保留一个本地数据库,除非客户端选择“无存储”实时模式。此本地数据库的格式和存储取决于客户端。从概念上来讲,这个本地数据库的内容可以视为一个文件夹,内含各种列表作为文件,这些文件的内容是 SHA256 哈希值或哈希前缀。

数据库更新

客户端将定期调用 hashList.get 方法hashLists.batchGet 方法 以更新数据库。由于典型的客户端希望一次更新多个列表,因此建议使用 hashLists.batchGet 方法

列表通过其不同的名称进行标识。名称是长度为几个字符的简短 ASCII 字符串。

与 V4 不同,在 V4 中,列表通过威胁类型、平台类型、威胁条目类型的元组进行标识,而在 v5 中,列表仅通过名称进行标识。当多个 v5 列表可能共享同一种威胁类型时,这可提供灵活性。v5 中移除了平台类型和威胁条目类型。

一旦为列表选择了名称,就永远不会重命名。此外,列表一旦显示,就永远不会移除(如果列表不再有用,它会变为空列表,但将继续存在)。因此,我们建议在 Google 安全浏览客户端代码中将这些名称硬编码为安全代码。

hashList.get 方法hashLists.batchGet 方法 均支持增量更新。使用增量更新可节省带宽并提升性能。增量更新的工作方式是在客户端的列表版本与列表的最新版本之间提供增量。(如果客户端是新部署的,但没有任何可用版本,则可获得完整更新。)增量更新包含移除索引和新增内容。客户端首先应从本地数据库中移除指定索引处的条目,然后再应用添加内容。

最后,为防止损坏,客户端应根据服务器提供的校验和检查存储的数据。只要校验和不匹配,客户端就应执行完全更新。

解码列表内容

所有列表均使用特殊编码来缩减大小。这种编码的工作原理是识别 Google 安全浏览列表从概念上来讲包含一组哈希或哈希前缀,而这些前缀在统计学上不会与随机整数区分。如果我们对这些整数进行排序,并选取其相邻差值,从某种意义上说,此类相邻差值应该很“小”。然后,Golomb-Rice 编码就利用了这种较小的结构。

Google 安全浏览 v5 提供了四种不同的类型,分别用于处理 4 字节数据、8 字节数据、16 字节数据和 32 字节数据。下面我们来看一个示例,在该示例中,三个数字连续的 4 字节整数经过了编码。让大米参数(以 k 表示)为 3。编码的商部分就是相邻差值右移 k 位。由于给定整数是连续的,因此它们的相邻差为 1,在移动 3 位后,商部分为零。最低有效 k 位是 001。零商被编码为单个 0 位。余数为 1,并编码为 100。系统会再次重复此操作,以形成比特流 01000100。生成的比特流使用小端字节序编码为 00100010。因此,它对应于以下数据:

rice_parameter: 3
entries_count: 2
encoded_data: "\x22"

在对 32 位整数进行上述解码步骤之后,结果可直接用作移除索引或加法运算。与 v4 不同,使用 v4 后无需执行字节交换。

可用列表

建议在 v5alpha1 中使用以下列表:

列表名称 对应的 v4 ThreatType 枚举 说明
gc 收不到任何通知 此列表为全局缓存列表。这是一个仅用于实时操作模式的特殊列表。
se SOCIAL_ENGINEERING 此列表包含 SOCIAL_ENGINEERING 威胁类型的威胁。
mw MALWARE 此列表包含适用于桌面平台的“恶意软件”威胁类型的威胁。
uws UNWANTED_SOFTWARE 此列表包含桌面平台的 UNWANTED_SOFTWARE 威胁类型的威胁。
uwsa UNWANTED_SOFTWARE 此列表包含 Android 平台中 UNWANTED_SOFTWARE 威胁类型的威胁。
pha POTENTIALLY_HARMFUL_APPLICATION 此列表包含 Android 平台的 POTENTIALLY_HARMFUL_APPLICATION 威胁类型的威胁。

我们日后会提供其他名单,届时上述表格也会随之扩展。

更新频率

客户端应检查 minimum_wait_duration 字段内服务器返回的值,并使用该值安排数据库的下一次更新。此值可能为零,在这种情况下,客户端应立即执行另一更新。

示例请求

本部分记录了一些直接使用 HTTP API 访问 Google 安全浏览功能的示例。通常建议使用生成的语言绑定,因为它会自动方便地处理编码和解码。请参阅有关该绑定的文档。

下面是一个使用 hashes.search 方法的 HTTP 请求示例:

GET https://safebrowsing.googleapis.com/v5/hashes:search?key=INSERT_YOUR_API_KEY_HERE&hashPrefixes=WwuJdQ

响应正文是协议缓冲区格式的载荷,您可以对其进行解码。

下面是一个使用 hashLists.batchGet 方法 的 HTTP 请求示例:

GET https://safebrowsing.googleapis.com/v5alpha1/hashLists:batchGet?key=INSERT_YOUR_API_KEY_HERE&names=se&names=mw

响应正文同样是协议缓冲区格式的载荷,您可以随后对其进行解码。

迁移指南

如果您目前使用的是 v4 Update API,则可以从 v4 顺利迁移到 v5,而不必重置或清空本地数据库。本部分介绍了如何执行此操作。

转换列表更新

在 v4 中,可使用 threatListUpdates.fetch 方法下载列表。在 v5 中,可以改为使用 hashLists.batchGet 方法

应对请求进行以下更改:

  1. 完全移除 v4 ClientInfo 对象。只需使用众所周知的 User-Agent 标头,而无需使用专用字段提供客户端的身份信息。虽然没有规定在此标头中提供客户端标识的格式,但我们建议您直接添加原始客户端 ID 和客户端版本,以空格或斜杠字符分隔。
  2. 对于每个 v4 ListUpdateRequest 对象
    • 在上表中查找相应的 v5 列表名称,并在 v5 请求中提供该名称。
    • 移除不需要的字段,例如 threat_entry_typeplatform_type
    • v4 中的 state 字段与 v5 versions 字段直接兼容。本应通过 v4 中的 state 字段发送到服务器的相同字节字符串也可在 v5 中使用 versions 字段直接发送。
    • 对于 v4 限制条件,v5 使用名为 SizeConstraints 的简化版本。应舍弃 region 等其他字段。

应对该响应进行以下更改:

  1. v4 枚举 ResponseType 只是被一个名为 partial_update 的布尔值字段替换。
  2. minimum_wait_duration 字段现在可以为零或省略。如果是,则请求客户端立即发出另一个请求。仅当客户端在 SizeConstraints 中指定的更新大小上限小于数据库大小上限时,才会发生这种情况。
  3. 需要调整用于 32 位整数的大米解码算法。不同之处在于编码数据以不同的字节序编码。在 v4 和 v5 中,32 位哈希前缀均按字典顺序排序。但在 v4 中,排序时这些前缀被视为小端字节,而在 v5 中,这些前缀排序时则被视为大端序。这意味着客户端不需要进行任何排序,因为字典顺序排序与使用大端序的数字排序完全相同。点击此处可查看在 Chromium v4 实现中的此类示例。此类排序可以移除。
  4. 大米解码算法需要针对其他哈希长度实现。

转换哈希搜索

在 v4 中,可以使用 fullHashes.find 方法 获取完整哈希。v5 中的等效方法是 hash.search 方法

应对请求进行以下更改:

  1. 设计代码结构,以便仅发送长度正好为 4 个字节的哈希前缀。
  2. 完全移除 v4 ClientInfo 对象。只需使用众所周知的 User-Agent 标头,而无需使用专用字段提供客户端的身份信息。虽然没有规定在此标头中提供客户端标识的格式,但我们建议您直接添加原始客户端 ID 和客户端版本,以空格或斜杠字符分隔。
  3. 移除 client_states 字段。不再需要此函数。
  4. 不再需要包含 threat_types 和类似字段。

应对该响应进行以下更改:

  1. minimum_wait_duration 字段已移除。客户端始终可以根据需要发出新的请求。
  2. v4 ThreatMatch 对象已简化为 FullHash 对象。
  3. 缓存已简化为单一缓存持续时间。请参阅上述与缓存交互的过程。