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

借助安全浏览 API，客户端可以根据 Google 不断更新的不安全网络资源列表检查网络资源（最常见的是网址）。

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

GetHashList
rpc GetHashList(GetHashListRequest) returns (HashList) 获取哈希列表的最新内容。哈希列表可以是威胁列表，也可以是全球缓存等非威胁列表。 这是 https://google.aip.dev/131 中定义的标准 Get 方法，HTTP 方法也是 GET。

ListHashLists
rpc ListHashLists(ListHashListsRequest) returns (ListHashListsResponse) 列出哈希列表。 在 V5 API 中，Google 绝不会移除此方法返回的任何哈希列表。这样，客户端就可以跳过使用此方法，而只需对所需的所有哈希列表进行硬编码。 这是 https://google.aip.dev/132 中定义的标准列表方法，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 (deprecated)	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

用于获取哈希列表的请求，该列表可能是威胁列表或非威胁列表（例如全局缓存）。

V5 中的新变化：为清楚起见，之前在 V4 中称为 states 的项已重命名为 version。列表现在带有名称，平台类型和威胁条目类型已移除。现在，多个列表可以具有相同的威胁类型，或者单个列表可以涉及多种威胁类型。客户端现在可以指定所需的哈希长度。这只是解决 V4 可变长度哈希前缀问题的部分答案，该问题在许多客户端实现中都造成了麻烦：列表中的所有哈希现在都具有单一长度，从而允许实现更高效的客户端。简化了约束条件，并移除了压缩类型（始终应用压缩）。

字段
name	string 必需。此特定哈希列表的名称。它可以是威胁列表，也可以是全局缓存。
version	bytes 客户端已有的哈希列表的版本。如果这是客户端首次提取哈希列表，则此字段必须留空。否则，客户端应提供之前从服务器收到的版本。客户端不得操纵这些字节。 v5 中的新变化：在 API 的 v4 中，此参数名为 states；为清楚起见，现已重命名为 version。
desired_hash_length (deprecated)	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 增量编码的删除索引版本。由于每个哈希列表的条目数肯定少于 2^32，因此编号会被视为 32 位整数并进行编码。
minimum_wait_duration	Duration 客户端至少应等待此时长才能再次获取哈希列表。如果省略或为零，客户端应立即提取，因为这表示服务器有其他更新要发送给客户端，但由于客户端指定的约束条件而无法发送。
sha256_checksum	bytes 所有哈希值的排序列表，已使用 SHA256 再次进行哈希处理。这是应用所提供更新后数据库中存在的所有哈希的排序列表的校验和。如果未提供任何更新，服务器将忽略此字段，以指示客户端应使用现有校验和。
metadata	HashListMetadata 有关哈希列表的元数据。此值不会由 GetHashList 方法填充，而是由 ListHashLists 方法填充。
联合字段 compressed_additions。使用 Rice 增量编码的添加内容。列表中所有添加项的哈希前缀长度均相同。它是客户端发送的 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 个字节的附加内容。

HashListMetadata

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

字段
threat_types[]	ThreatType 无序列表。如果不为空，则表示哈希列表是一种威胁列表，并会枚举与此哈希列表中的哈希或哈希前缀相关联的威胁类型。如果条目不代表威胁（即代表可能安全的类型），则可以为空。
likely_safe_types[]	LikelySafeType 无序列表。如果不为空，则表示哈希列表代表可能安全的哈希列表，并列出了这些哈希被视为可能安全的方式。此字段与 threat_types 字段互斥。
description	string 此列表的直观易懂说明。使用英语撰写。
supported_hash_lengths[] (deprecated)	HashLength 此项已弃用！ 此哈希列表支持的哈希长度。每个哈希列表都至少支持一种长度。因此，此字段不会为空。
hash_length	HashLength 此哈希列表支持的哈希长度。每个哈希列表都将仅支持一种长度。如果为同一组威胁类型或安全类型引入了不同的哈希长度，则会将其作为一个单独的列表引入，并设置不同的名称和相应的哈希长度。

HashLength

哈希列表中的哈希的长度。

枚举
HASH_LENGTH_UNSPECIFIED	未指定长度。服务器不会在向客户端的响应中返回此值（在 supported_hash_lengths 字段中），但客户端可以将此值发送给服务器（在 desired_hash_length 字段中），在这种情况下，服务器会自动选择一个值。客户端应让服务器选择一个值。
FOUR_BYTES	每个哈希都是一个四字节前缀。
EIGHT_BYTES	每个哈希都是一个八字节前缀。
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 发送并用于检索下一页的令牌。如果省略此字段，则不存在后续页面。

RiceDeltaEncoded128Bit

与 RiceDeltaEncoded32Bit 相同，但用于编码 128 位数字。

字段
first_value_hi	uint64 编码数据（哈希）中第一个条目的前 64 位。如果该字段为空，则前 64 位均为零。
first_value_lo	fixed64 编码数据（哈希）中第一个条目的低 64 位。如果该字段为空，则低 64 位均为零。
rice_parameter	int32 Golomb-Rice 参数。此参数保证介于 99 到 126 之间（包括这两个数值）。
entries_count	int32 在编码后的数据中采用增量编码的条目数量。如果仅编码了一个整数，则此值将为零，并且单个值将存储在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 编码器编码的编码增量。

RiceDeltaEncoded256Bit

与 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 之间（包括这两个数值）。
entries_count	int32 在编码后的数据中采用增量编码的条目数量。如果仅编码了一个整数，则此值将为零，并且单个值将存储在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 编码器编码的编码增量。

RiceDeltaEncoded32Bit

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

一般来说，如果按字典顺序对所有条目进行排序，我们会发现高阶位通常不会像低阶位那样频繁更改。这意味着，如果我们还考虑条目之间的相邻差值，高阶位数很有可能为零。这实际上是通过选择一定数量的位来利用这种高概率的零；所有更重要的位都可能为零，因此我们使用单元编码。请参阅 rice_parameter 字段。

历史备注：Rice-delta 编码首次在此 API 的 V4 中使用。在 V5 中，我们进行了两项重大改进：首先，现在可以使用长度超过 4 个字节的哈希前缀进行 Rice-delta 编码；其次，编码后的数据现在被视为大端字节序，以避免耗时的排序步骤。

字段
first_value	uint32 编码数据（哈希或索引）中的第一个条目，或者如果仅编码了单个哈希前缀或索引，则为该条目的值。如果该字段为空，则条目为零。
rice_parameter	int32 Golomb-Rice 参数。此参数的值保证介于 3 到 30 之间（包括这两个数值）。
entries_count	int32 在编码后的数据中采用增量编码的条目数量。如果仅编码了一个整数，则此值将为零，并且单个值将存储在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 编码器编码的编码增量。

RiceDeltaEncoded64Bit

与 RiceDeltaEncoded32Bit 相同，但此属性会编码 64 位数字。

字段
first_value	uint64 编码数据（哈希）中的第一个条目，或者如果仅编码了单个哈希前缀，则为该条目的值。如果该字段为空，则条目为零。
rice_parameter	int32 Golomb-Rice 参数。此参数保证介于 35 到 62 之间（包括这两个数值）。
entries_count	int32 在编码后的数据中采用增量编码的条目数量。如果仅编码了一个整数，则此值将为零，并且单个值将存储在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 编码器编码的编码增量。

SearchHashesRequest

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

此功能仅用于搜索威胁列表，而不搜索全球缓存等非威胁列表。

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

字段
hash_prefixes[]	bytes 必需。要查询的哈希前缀。客户端不得发送超过 1,000 个哈希前缀。不过，按照网址处理流程，客户端不应发送超过 30 个哈希前缀。 目前，每个哈希前缀的长度都必须为 4 个字节。我们日后可能会放宽此限制。
filter	string 可选。如果客户有过滤需求（例如仅检索特定类型的威胁），可以指定此过滤条件。如果省略，则返回所有匹配的威胁。强烈建议您忽略此设置，以获得安全浏览功能可提供的最全面保护。 过滤条件使用 Google 通用表达式语言 (CEL) 指定，您可以在 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。如果省略或设为 0，则不设置更新大小限制。
max_database_entries	int32 设置客户端愿意在本地数据库中为列表保留的条目数量上限。（服务器可能会导致客户端存储的条目数量少于此数值。）如果省略或设为 0，则不会设置数据库大小限制。

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 商店使用的潜在有害应用威胁类型。