Overview

注意：本文档目前仍在开发中。我们预计在不久的将来会进行改进。

Google 安全浏览 v5 是 Google 安全浏览 v4 的演变版本。v5 中做出的两项重大变更是数据新鲜度和 IP 隐私性。此外，API Surface 也得到了改进，以提高灵活性和效率，并减少冗余代码。此外，Google 安全浏览 v5 旨在简化从 v4 迁移。

目前，Google 同时提供 v4 和 v5，这两种版本都已可用于生产环境。您可以使用 v4 或 v5。我们尚未宣布弃用 v4 的日期；如果宣布，则会至少提前一年通知。本页将介绍 v5 以及从 v4 迁移到 v5 的指南；完整的 v4 文档仍可用。

数据新鲜度

在 v5 中，我们引入了一种称为“实时保护”的操作模式。这样可以规避上述数据过时问题。在 v4 中，客户端应下载并维护本地数据库，针对本地下载的威胁列表执行检查，然后在存在部分前缀匹配时，执行请求以下载完整哈希。在 v5 中，虽然客户端应继续下载和维护威胁列表的本地数据库，但现在还应下载可能无害的网站列表（称为“全局缓存”），同时对此全局缓存执行本地检查和本地威胁列表检查，最后，如果威胁列表存在部分前缀匹配或全局缓存中不匹配，则执行下载完整哈希的请求。（如需详细了解客户要求的本地处理，请参阅下方提供的流程。）这意味着从默认允许变为默认检查，这有助于提高保护力度，因为网络上的威胁传播速度更快。换句话说，这是一种旨在提供近乎实时保护的协议：我们的目标是让客户能够获享更新鲜的 Google 安全浏览数据。

IP 隐私保护

Google 安全浏览 (v4 或 v5) 在处理请求期间不会处理与用户身份相关的任何信息。系统会忽略发送的 Cookie。Google 知道请求的来源 IP 地址，但 Google 仅将这些 IP 地址用于基本网络需求（例如发送响应）和防范拒绝服务攻击 (DoS) 目的。

与 v5 同时，我们还引入了名为 Safe Browsing Oblivious HTTP Gateway API 的配套 API。这项功能使用 Oblivious HTTP 技术，可隐藏最终用户的 IP 地址，使 Google 无法看到这些地址。其运作方式是，让不存在串谋行为的第三方处理用户请求的加密版本，然后将其转发给 Google。因此，第三方只能访问 IP 地址，Google 只能访问请求内容。第三方运营 Oblivious HTTP 中继（例如 Fastly 提供的这项服务），Google 运营 Oblivious HTTP 网关。这是可选的随播广告 API。与 Google 安全浏览功能搭配使用时，系统不会再将最终用户的 IP 地址发送给 Google。

操作模式

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

实时模式

当客户端选择在实时模式下使用 Google 安全浏览 v5 时，客户端将在其本地数据库中维护：(i) 可能为良性网站的全球缓存，格式为主机后缀/路径前缀网址表达式的 SHA256 哈希值；(ii) 一组威胁列表，格式为主机后缀/路径前缀网址表达式的 SHA256 哈希前缀。大致思路是，每当客户端想要检查特定网址时，都会使用全局缓存执行本地检查。如果该检查通过，系统会执行本地威胁列表检查。否则，客户端会继续进行实时哈希检查，如下所述。

除了本地数据库之外，客户端还会维护一个本地缓存。此类本地缓存不必位于永久性存储空间中，并且在出现内存压力时可以清除。

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

本地列表模式

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

与上述情况一样，客户端还会维护一个本地缓存，该缓存无需位于永久性存储空间中。

无存储空间实时模式

当客户端选择在无存储空间的实时模式下使用 Google 安全浏览 v5 时，客户端无需维护任何永久性本地数据库。不过，客户端仍应维护本地缓存。此类本地缓存不必位于永久性存储空间中，并且在出现内存压力时可以清除。

每当客户端想要检查特定网址时，都必须连接到服务器以执行检查。此模式类似于 v4 Lookup API 的客户端可能实现的模式。

与实时模式相比，此模式可能会使用更多网络带宽，但如果客户端不方便维护永久性本地状态，则此模式可能更适合。

实时网址检查流程

当客户端选择实时操作模式时，系统会使用此过程。

此过程接受单个网址 u，并返回 SAFE、UNSAFE 或 UNSURE。如果返回 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.search 将 expressionHashPrefixes 发送到 Google 安全浏览 v5 服务器。如果发生错误（包括网络错误、HTTP 错误等），请返回 UNSURE。否则，将 response 设为从 SB 服务器收到的 response，它是一个包含完整哈希的列表，以及一些辅助信息，用于识别威胁的性质（社会工程学、恶意软件等）以及缓存到期时间 expiration。
  7. 对于 response 的每个 fullHash：
    1. 将 fullHash 与 expiration 一起插入本地缓存。
  8. 对于 response 的每个 fullHash：
    1. 设 isFound 为在 expressionHashes 中查找 fullHash 的结果。
    2. 如果 isFound 为 False，则继续循环。
    3. 如果 isFound 为 True，则返回 UNSAFE。
  9. 返回 SAFE。

虽然此协议指定了客户端向服务器发送 expressionHashPrefixes 的时间，但该协议有意不明确指定发送方式。例如，客户端可以通过单个请求发送所有 expressionHashPrefixes，也可以通过单独的请求（可能并行进行）将 expressionHashPrefixes 中的每个前缀发送到服务器。客户端也可以将不相关或随机生成的哈希前缀与 expressionHashPrefixes 中的哈希前缀一起发送，前提是单个请求中发送的哈希前缀数量不超过 30 个。

LocalThreat 列表网址检查流程

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

此过程接受单个网址 u，并返回 SAFE 或 UNSAFE。

  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.search 将 expressionHashPrefixes 发送到 Google 安全浏览 v5 服务器。如果发生错误（包括网络错误、HTTP 错误等），请返回 SAFE。否则，将 response 设为从 SB 服务器收到的 response，它是一个完整哈希列表，以及一些辅助信息，用于标识威胁的性质（社会工程学、恶意软件等）以及缓存到期时间 expiration。
  7. 对于 response 的每个 fullHash：
    1. 将 fullHash 与 expiration 一起插入本地缓存。
  8. 对于 response 的每个 fullHash：
    1. 设 isFound 为在 expressionHashes 中查找 fullHash 的结果。
    2. 如果 isFound 为 False，则继续循环。
    3. 如果 isFound 为 True，则返回 UNSAFE。
  9. 返回 SAFE。

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

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

此过程接受单个网址 u，并返回 SAFE 或 UNSAFE。

  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.search 将 expressionHashPrefixes 发送到 Google 安全浏览 v5 服务器。如果发生错误（包括网络错误、HTTP 错误等），请返回 SAFE。否则，将 response 设为从 SB 服务器收到的 response，它是一个包含完整哈希的列表，以及一些辅助信息，用于识别威胁的性质（社会工程学、恶意软件等）以及缓存到期时间 expiration。
  6. 对于 response 的每个 fullHash：
    1. 将 fullHash 与 expiration 一起插入本地缓存。
  7. 对于 response 的每个 fullHash：
    1. 设 isFound 为在 expressionHashes 中查找 fullHash 的结果。
    2. 如果 isFound 为 False，则继续循环。
    3. 如果 isFound 为 True，则返回 UNSAFE。
  8. 返回 SAFE。

与实时网址检查流程一样，此流程并未明确指定将哈希前缀发送到服务器的方式。例如，客户端可以通过单个请求发送所有 expressionHashPrefixes，也可以通过单独的请求（可能并行进行）将 expressionHashPrefixes 中的每个前缀发送到服务器。客户端也可以将不相关或随机生成的哈希前缀与 expressionHashPrefixes 中的哈希前缀一起发送，前提是单个请求中发送的哈希前缀数量不超过 30 个。

示例请求

本部分记录了直接使用 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-4b

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