Package google.security.safebrowsing.v5alpha1

索引

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 字段的可接受值有不同的要求。您可以在 HashListMetadatasupported_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 消息。因此,客户端应负责检查所有 ThreatTypeThreatAttribute 枚举值的有效性;如果任何值被视为无效,客户端必须忽略整条 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 字段的可接受值有不同的要求。您可以在 HashListMetadatasupported_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_SOFTWAREMALWARE

SearchHashesResponse

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

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

V5 的新变化FullHashFullHashDetail 分开。如果哈希表示某个网站存在多种威胁(例如,同时存在 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 商店使用的潜在有害应用威胁类型。