Package google.security.safebrowsing.v5alpha1

索引

• SafeBrowsing（接口）
• BatchGetHashListsRequest（消息）
• BatchGetHashListsResponse（消息）
• FullHash（消息）
• FullHash.FullHashDetail（消息）
• GetHashListRequest（消息）
• HashList（消息）
• HashListMetadata（消息）
• HashListMetadata.HashLength（枚举）
• LikelySafeType（枚举）
• ListHashListsRequest（消息）
• ListHashListsResponse（消息）
• RiceDeltaEncoded128Bit（消息）
• RiceDeltaEncoded256Bit（消息）
• RiceDeltaEncoded32Bit（消息）
• RiceDeltaEncoded64Bit（消息）
• SearchHashesRequest（消息）
• SearchHashesResponse（消息）
• SizeConstraints（消息）
• ThreatAttribute（枚举）
• ThreatType（枚举）

SafeBrowsing

通过 Safe Browsing API，客户端可以对照 Google 持续更新的不安全网络资源列表检查网络资源（最常见的网址）。

BatchGetHashLists
rpc BatchGetHashLists(BatchGetHashListsRequest) returns (BatchGetHashListsResponse) 一次获取多个哈希列表。 客户端需要获取多个哈希列表是很常见的情况。此方法优于多次使用常规 Get 方法。 这是由 https://google.aip.dev/231 定义的标准批量 Get 方法，HTTP 方法也是 GET。

GetHashList
rpc GetHashList(GetHashListRequest) returns (HashList) 获取哈希列表的最新内容。哈希列表可能以威胁列表或非威胁列表（如 Global Cache）为依据。 这是 https://google.aip.dev/131 定义的标准 Get 方法，HTTP 方法也是 GET。

ListHashLists
rpc ListHashLists(ListHashListsRequest) returns (ListHashListsResponse) 列出哈希列表。 在 V5 API 中，Google 绝不会移除此方法曾返回的哈希列表。这样，客户端就可以跳过此方法，只需对需要的所有哈希列表进行硬编码。 这是由 https://google.aip.dev/132 定义的标准 List 方法，HTTP 方法是 GET。

SearchHashes
rpc SearchHashes(SearchHashesRequest) returns (SearchHashesResponse) 搜索与指定前缀匹配的完整哈希。 这是 https://google.aip.dev/136 定义的自定义方法（该自定义方法是指此方法具有采用 Google 通用 API 开发命名法的自定义名称，不是指使用自定义 HTTP 方法）。

BatchGetHashListsRequest

同时获取多个哈希列表的请求。

字段
names[]	string 必需。特定哈希列表的名称。该列表可以是威胁列表，也可以是全局缓存。名称不得包含重复项；如果重复，客户端会收到错误。
version[]	bytes 客户端已有的哈希列表版本。如果这是客户端首次提取哈希列表，则应将此字段留空。否则，客户端应提供之前从服务器接收的版本。客户端不得操纵这些字节。 客户端无需按照与相应列表名称相同的顺序发送版本。客户端在请求中发送的版本数量可能少于名称。但是，客户端不得发送与同一名称对应的多个版本；否则，客户端会收到错误。 历史说明：在 API 的 V4 版中，它称为 states；为清楚起见，现在已重命名为 version。
desired_hash_length	HashLength 所返回哈希的所需哈希前缀长度（以字节为单位）。然后，服务器会返回此指定长度的所有哈希前缀。 不同的哈希列表对 desired_hash_length 字段的可接受值有不同的要求。您可以在 HashListMetadata 的 supported_hash_lengths 字段中找到此信息。如果 desired_hash_length 未在 supported_hash_lengths 内指定值，则系统会向客户端返回错误。 特别是对于 BatchGetHashListsRequest，客户端无法为不同的列表指定不同的 desired_hash_length。如果需要这样做，客户端应拆分为多个 BatchGetHashListsRequest。
size_constraints	SizeConstraints 每个列表的大小限制。如果省略，则不存在任何限制条件。请注意，此处的尺寸是按列表列出的，并未汇总到所有列表中。

BatchGetHashListsResponse

包含多个哈希列表的响应。

字段
hash_lists[]	HashList 哈希列表（采用请求中指定的相同顺序）。

FullHash

用一个或多个匹配项标识的完整哈希。

字段
full_hash	bytes 匹配的完整哈希。这是 SHA256 哈希值。长度正好为 32 个字节。
full_hash_details[]	FullHashDetail 无序列表。一个重复字段，用于标识与此完整哈希相关的详细信息。

FullHashDetail

匹配的完整哈希的详细信息。

关于向前兼容性的重要说明：服务器可能随时添加新的威胁类型和威胁属性；添加的内容被视为小幅版本变更。Google 的政策不允许在 API 中公开次要版本号（请参阅 https://cloud.google.com/apis/design/versioning 了解版本控制政策），因此客户端必须准备好接收包含客户端视为无效的 ThreatType 枚举值或 ThreatAttribute 枚举值的 FullHashDetail 消息。因此，客户端应负责检查所有 ThreatType 和 ThreatAttribute 枚举值的有效性；如果任何值被视为无效，客户端必须忽略整条 FullHashDetail 消息。

字段
threat_type	ThreatType 威胁的类型。此字段一律不为空。
attributes[]	ThreatAttribute 无序列表。关于这些完整哈希的其他属性。此字段可能为空。

GetHashListRequest

获取哈希列表的请求，该列表可能是威胁列表或非威胁列表（如 Global Cache）。

V5 的新变化：为清楚起见，V4 中之前称为 states 的功能已重命名为 version。列表现已命名，平台类型和威胁条目类型已被移除。现在可以让多个列表具有相同的威胁类型，或者单个列表涉及多个威胁类型。客户端现在可以指定所需的哈希长度。这是 V4 可变长度哈希前缀（在许多客户端实现中导致问题）的一部分问题：列表中的所有哈希现在都是单一长度，从而可以更高效地进行客户端实现。简化了约束，并移除了压缩类型（始终应用压缩）。

字段
name	string 必需。此特定哈希列表的名称。它可能是威胁列表，也可能是全球缓存。
version	bytes 客户端已有的哈希列表版本。如果这是客户端首次提取哈希列表，则必须将此字段留空。否则，客户端应提供之前从服务器接收的版本。客户端不得操纵这些字节。 V5 的新变化：在 API 的 V4 版本中，它称为 states；为清楚起见，现在已重命名为 version。
desired_hash_length	HashLength 所返回哈希的所需哈希前缀长度（以字节为单位）。然后，服务器会返回此指定长度的所有哈希前缀。 不同的哈希列表对 desired_hash_length 字段的可接受值有不同的要求。您可以在 HashListMetadata 的 supported_hash_lengths 字段中找到此信息。如果 desired_hash_length 未在 supported_hash_lengths 中指定值，则会返回错误。
size_constraints	SizeConstraints 对列表的大小限制。如果省略，则不存在任何限制条件。建议为处理能力、带宽或存储空间有限的所有设备添加限制条件。

HashList

由其名称标识的哈希列表。

字段
name	string 哈希列表的名称。请注意，全局缓存也只是哈希列表，在此处可以引用。
version	bytes 哈希列表的版本。客户端不得操纵这些字节。
partial_update	bool 如果为 true，则是部分差异，其中包含根据客户端已有的内容添加和移除的内容。如果为 false，这是完整的哈希列表。 如果为 false，客户端必须删除此哈希列表的任何本地存储版本。这意味着客户端拥有的版本严重已过时或客户端数据已损坏。compressed_removals 字段将为空。 如果为 true，客户端必须先应用移除，然后再应用添加，从而应用增量更新。
compressed_removals	RiceDeltaEncoded32Bit 移除索引的 Rice-delta 编码版本。由于每个哈希列表包含的条目都少于 2^32 个，因此索引将被视为 32 位整数并进行编码。
minimum_wait_duration	Duration 客户端应等待至少此时长才能再次获取哈希列表。如果省略或为零，客户端应立即提取，因为这表明服务器有其他要发送给客户端的更新，但由于客户端指定的约束而无法发送。
metadata	HashListMetadata 关于哈希列表的元数据。它不是由 GetHashList 方法填充的，而是由 ListHashLists 方法填充。
联合字段 compressed_additions。加法的 Rice-delta 编码版本。添加到列表中的所有添加项的哈希前缀长度都是相同的。该值可以是客户端发送的 desired_hash_length，也可以是服务器选择的值（如果客户端省略了该字段）。compressed_additions 只能是下列其中一项：
additions_four_bytes	RiceDeltaEncoded32Bit 4 字节附加内容。
additions_eight_bytes	RiceDeltaEncoded64Bit 8 字节附加内容。
additions_sixteen_bytes	RiceDeltaEncoded128Bit 增加的 16 个字节。
additions_thirty_two_bytes	RiceDeltaEncoded256Bit 添加 32 个字节。
联合字段 checksum。这是应用提供的更新后，数据库中存在的所有哈希的排序列表的校验和。此字段是“oneof”字段，允许多种哈希算法。服务器也可以省略此字段（在未提供更新的情况下），以指示客户端应使用现有的校验和。checksum 只能是下列其中一项：
sha256_checksum	bytes 已排序的所有哈希列表，使用 SHA256 再次进行哈希处理。

HashListMetadata

关于特定哈希列表的元数据。

字段
threat_types[]	ThreatType 无序列表。如果不为空，则表示该哈希列表是一种威胁列表，并且枚举与此哈希列表中的哈希或哈希前缀关联的威胁类型。如果相应条目不表示威胁（即在它表示可能的安全类型时），则此字段可能为空。
likely_safe_types[]	LikelySafeType 无序列表。如果不为空，则表示哈希列表表示一个可能安全的哈希列表，并且枚举了这些哈希可能被认为安全的方式。此字段与 threat_types 字段互斥。
mobile_optimized	bool 是否针对移动设备（Android 和 iOS）优化了此列表。
description	string 关于此列表的人类可读说明。所用语言为英文。
supported_hash_lengths[]	HashLength 此哈希列表支持的哈希长度。每个哈希列表至少支持一种长度。因此，此字段不能为空。

HashLength

哈希列表中的哈希长度。

枚举
HASH_LENGTH_UNSPECIFIED	未指定长度。服务器不会在响应客户端时返回此值（在 supported_hash_lengths 字段中），但允许客户端向服务器发送此值（在 desired_hash_length 字段中），在这种情况下，服务器会自动选择一个值。客户端应允许服务器选择值。
FOUR_BYTES	每个哈希都是四字节前缀。
EIGHT_BYTES	每个哈希都是 8 字节的前缀。
SIXTEEN_BYTES	每个哈希都是 16 字节的前缀。
THIRTY_TWO_BYTES	每个哈希都是 32 字节的完整哈希。

LikelySafeType

可能安全的网站的类型。

请注意，SearchHashesResponse 有意不包含 LikelySafeType。

枚举
LIKELY_SAFE_TYPE_UNSPECIFIED	未知。
GENERAL_BROWSING	此网站可能足以进行一般浏览。这也称为全局缓存。
CSD	该网站很可能足够安全，因此无需运行客户端检测模型或密码保护检查。
DOWNLOAD	该网站很可能足够安全，因此无需检查从该网站下载内容。

ListHashListsRequest

列出可用哈希列表的请求。

字段
page_size	int32 要返回的哈希列表数量上限。服务返回的值可能小于此值。如果未指定，服务器将选择页面大小，该大小可能大于哈希列表的数量，因此无需进行分页。
page_token	string 从之前的 ListHashLists 调用接收的页面令牌。利用其进行后续页面检索。

ListHashListsResponse

包含哈希列表相关元数据的响应。

字段
hash_lists[]	HashList 按任意顺序排列的哈希列表。仅包含哈希列表的元数据，不包含内容。
next_page_token	string 可作为 page_token 发送并用于检索下一页的令牌。如果省略此字段，则不存在后续页面。

RiceDelta 编码 128 位

与 RiceDeltaEncoded32Bit 相同，不过它会对 128 位数字进行编码。

字段
first_value_hi	uint64 编码数据中第一个条目的高 64 位（哈希）。如果该字段为空，则上限 64 位全部为零。
first_value_lo	fixed64 编码数据中第一个条目的低 64 位（哈希）。如果该字段为空，则低 64 位全部为零。
rice_parameter	int32 Golomb-Rice 参数。此参数应介于 99 和 126 之间（含 99 和 126）。
entries_count	int32 编码数据中经过增量编码的条目数。如果只对一个整数进行编码，此值将为 0，并且该单个值将存储在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 编码器编码的已编码增量。

RiceDelta 编码 256 位

与 RiceDeltaEncoded32Bit 相同，不过它会对 256 位数字进行编码。

字段
first_value_first_part	uint64 编码数据中第一个条目的前 64 位（哈希）。如果该字段为空，则前 64 位全部为零。
first_value_second_part	fixed64 编码数据中第一个条目的 65 到 128 位（哈希）。如果该字段为空，则第 65 位到第 128 位都为零。
first_value_third_part	fixed64 编码数据中第一个条目的 129 到 192 位（哈希）。如果该字段为空，则第 129 位到第 192 位都为零。
first_value_fourth_part	fixed64 编码数据中第一个条目的最后 64 位（哈希）。如果该字段为空，则最后 64 位全部为零。
rice_parameter	int32 Golomb-Rice 参数。此参数应介于 227 和 254 之间（含 227 和 254）。
entries_count	int32 编码数据中经过增量编码的条目数。如果只对一个整数进行编码，此值将为 0，并且该单个值将存储在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 编码器编码的已编码增量。

RiceDeltaEncoded32 位

Rice-Golomb 编码数据。用于哈希或移除索引。可以保证此处的每个哈希或索引都具有相同的长度，并且该长度正好为 32 位。

一般来说，如果我们按字典顺序对所有条目进行排序，会发现高阶位的变化频率不会像低阶位那样频繁。这意味着，如果我们加上条目之间的相邻差值，则高阶位很有可能为零。这种方法从本质上选择了特定数量的位，从而利用了这种高的零概率；所有比该数量更高的有效位都可能为零，因此我们使用一元编码。请参阅 rice_parameter 字段。

历史说明：Rice-delta 编码首次在此 API 的 V4 中使用。在 V5 中进行了两项重大改进：首先，现在可使用超过 4 个字节的哈希前缀使用 Rice-delta 编码；其次，现在将编码数据作为大端字节序处理，以避免开销高的排序步骤。

字段
first_value	uint32 编码数据中的第一个条目（哈希或索引）；或者，如果只对单个哈希前缀或索引进行了编码，则值为该条目的值。如果该字段为空，则该条目为零。
rice_parameter	int32 Golomb-Rice 参数。此参数必须介于 3 和 30 之间（含 3 和 30）。
entries_count	int32 编码数据中经过增量编码的条目数。如果只对一个整数进行编码，此值将为 0，并且该单个值将存储在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 编码器编码的已编码增量。

RiceDeltaEncoded64 位

与 RiceDeltaEncoded32Bit 相同，不过它会对 64 位数字进行编码。

字段
first_value	uint64 编码数据中的第一个条目（哈希）或该条目的值（如果只编码了一个哈希前缀）。如果该字段为空，则该条目为零。
rice_parameter	int32 Golomb-Rice 参数。此参数必须介于 35 和 62 之间（含 35 和 62）。
entries_count	int32 编码数据中经过增量编码的条目数。如果只对一个整数进行编码，此值将为 0，并且该单个值将存储在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 编码器编码的已编码增量。

SearchHashesRequest

客户端发出的搜索特定哈希前缀的请求。

此机制只能搜索威胁列表，而不会搜索非威胁列表（如 Global Cache）。

V5 的新变化：客户端无需在其本地数据库中指定 ClientInfo 或哈希列表的状态。这样做是为了加强隐私保护。此外，客户端不需要发送他们感兴趣的威胁类型。

字段
hash_prefixes[]	bytes 必需。要查找的哈希前缀。客户端发送的哈希前缀不得超过 1000 个。不过，按照网址处理流程，客户端不需要发送超过 30 个哈希前缀。 目前，每个哈希前缀的长度必须正好为 4 个字节。将来可以放宽这一要求。
filter	string 可选。如果客户端要过滤，例如仅检索特定类型的威胁，可指定此字段。如果省略，则返回所有匹配的威胁。我们强烈建议您省略此设置，以便充分利用安全浏览功能，从而提供最全面的保护。 使用 Google 通用表达式语言指定过滤器，您可以在 https://github.com/google/cel-spec 上找到该语言以及通用示例。以下是一些可用于此处的具体示例： 过滤器“"threat_type == ThreatType.SOCIAL_ENGINEERING"”要求 FullHashDetail 中的威胁类型必须为 SOCIAL_ENGINEERING。标识符 "threat_type" 是指当前的威胁类型。标识符 "ThreatType" 是指所有可能的威胁类型的集合。 “"threat_type in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]"”过滤器要求威胁类型必须为 UNWANTED_SOFTWARE 或 MALWARE。

SearchHashesResponse

搜索威胁哈希后返回的响应。

如果找不到任何错误消息，服务器将返回“OK”状态（HTTP 状态代码 200），并将 full_hashes 字段留空，而不是返回 NOT_FOUND 状态（HTTP 状态代码 404）。

V5 的新变化：FullHash 与 FullHashDetail 分开。如果哈希表示某个网站存在多种威胁（例如，同时存在 MALWARE 和 SOCIAL_ENGINEERING），则无需像 V4 中那样发送完整哈希两次。此外，缓存时长已简化为单个 cache_duration 字段。

字段
full_hashes[]	FullHash 无序列表。找到的完整哈希值的无序列表。
cache_duration	Duration 客户端缓存时长。客户端必须将此时长添加到当前时间，以确定到期时间。然后，到期时间将应用于客户端在请求中查询的每个哈希前缀，无论响应中返回了多少完整的哈希。即使服务器没有针对特定的哈希前缀返回完整的哈希，客户端也必须缓存这一事实。 当且仅当字段 full_hashes 为空时，客户端才可以增加 cache_duration 以确定晚于服务器指定的新到期时间。在任何情况下，增加的缓存时长不得超过 24 小时。 重要提示：客户端不得假定服务器对所有响应返回相同的缓存时长。服务器可以根据具体情况为不同的响应选择不同的缓存时长。

SizeConstraints

对哈希列表大小的限制。

字段
max_update_entries	int32 条目数的大小上限。更新包含的条目数不会超过此值，但可能会少于此值。该值必须至少为 1024。如果省略或为零，则未设置更新大小限制。
max_database_entries	int32 设置客户端愿意在本地数据库中为列表包含的条目数上限。（服务器可以使客户端存储的条目数少于此数量的条目）。如果省略或为零，则未设置数据库大小限制。

ThreatAttribute

威胁的属性。这些属性可能对特定威胁赋予其他含义，但不会影响威胁类型。例如，某个属性指定的置信度可能较低，而其他属性指定的置信度可能较高。未来我们可能会添加更多属性。

枚举
THREAT_ATTRIBUTE_UNSPECIFIED	未知属性。如果服务器返回此错误代码，则客户端应完全忽略外围的 FullHashDetail。
CANARY	表示 threat_type 不应用于强制执行。
FRAME_ONLY	表示 threat_type 应仅用于对帧强制执行。

ThreatType

威胁类型。

枚举
THREAT_TYPE_UNSPECIFIED	未知威胁类型。如果服务器返回此错误代码，则客户端应完全忽略外围的 FullHashDetail。
MALWARE	恶意软件威胁类型。恶意软件是指符合以下特征的所有软件或移动应用：蓄意危害计算机、移动设备、计算机/移动设备上运行的软件或计算机/移动设备用户。恶意软件会表现出各种恶意行为，其中包括：未经用户同意就擅自安装软件，以及安装病毒等有害软件。 如需了解详情，请参阅此处。
SOCIAL_ENGINEERING	社会工程学威胁类型。社交工程页面会谎称代表第三方行事，意图混淆观看者做出某种行为，而观看者只会相信第三方的真正代理人。钓鱼式攻击是一种社会工程学攻击，它会诱使观看者执行提供信息（例如登录凭据）的具体操作。 如需了解详情，请参阅此处。
UNWANTED_SOFTWARE	垃圾软件威胁类型。垃圾软件是指任何不符合 Google 软件准则但不属于恶意软件的软件。
POTENTIALLY_HARMFUL_APPLICATION	Google Play 保护机制针对 Play 商店使用的潜在有害应用威胁类型。