REST Resource: hashList

Resource: HashList

A list of hashes identified by its name.

JSON representation 
{
  "name": string,
  "version": string,
  "partialUpdate": boolean,
  "compressedRemovals": {
    object (RiceDeltaEncoded32Bit)
  },
  "minimumWaitDuration": string,
  "metadata": {
    object (HashListMetadata)
  },

  // Union field compressed_additions can be only one of the following:
  "additionsFourBytes": {
    object (RiceDeltaEncoded32Bit)
  },
  "additionsEightBytes": {
    object (RiceDeltaEncoded64Bit)
  },
  "additionsSixteenBytes": {
    object (RiceDeltaEncoded128Bit)
  },
  "additionsThirtyTwoBytes": {
    object (RiceDeltaEncoded256Bit)
  }
  // End of list of possible types for union field compressed_additions.

  // Union field checksum can be only one of the following:
  "sha256Checksum": string
  // End of list of possible types for union field checksum.
}
Fields
name

string

The name of the hash list. Note that the Global Cache is also just a hash list and can be referred to here.
version

string (bytes format)

The version of the hash list. The client MUST NOT manipulate those bytes.

A base64-encoded string.
partialUpdate

boolean

When true, this is a partial diff containing additions and removals based on what the client already has. When false, this is the complete hash list.

When false, the client MUST delete any locally stored version for this hash list. This means that either the version possessed by the client is seriously out-of-date or the client data is believed to be corrupt. The compressedRemovals field will be empty.

When true, the client MUST apply an incremental update by applying removals and then additions.
compressedRemovals

object (RiceDeltaEncoded32Bit)

The Rice-delta encoded version of removal indices. Since each hash list definitely has less than 2^32 entries, the indices are treated as 32-bit integers and encoded.
minimumWaitDuration

string (Duration format)

Clients should wait at least this long to get the hash list again. If omitted or zero, clients SHOULD fetch immediately because it indicates that the server has an additional update to be sent to the client, but could not due to the client-specified constraints.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
metadata

object (HashListMetadata)

Metadata about the hash list. This is not populated by the hashList.get method, but this is populated by the ListHashLists method.
Union field compressed_additions. The Rice-delta encoded version of additions. The hash prefix lengths of additions are uniform across all additions in the list. It is either the desired_hash_length sent by the client or a value chosen by the server if the client omitted that field. compressed_additions can be only one of the following:
additionsFourBytes

object (RiceDeltaEncoded32Bit)

The 4-byte additions.
additionsEightBytes

object (RiceDeltaEncoded64Bit)

The 8-byte additions.
additionsSixteenBytes

object (RiceDeltaEncoded128Bit)

The 16-byte additions.
additionsThirtyTwoBytes

object (RiceDeltaEncoded256Bit)

The 32-byte additions.
Union field checksum. This is the checksum for the sorted list of all hashes present in the database after applying the provided update. This is a "oneof" field to allow multiple hashing algorithms. It is also possible for the server to omit this field (in the case that no updates were provided) to indicate that the client should use the existing checksum. checksum can be only one of the following:
sha256Checksum

string (bytes format)

The sorted list of all hashes, hashed again with SHA256.

A base64-encoded string.

RiceDeltaEncoded32Bit

The Rice-Golomb encoded data. Used for either hashes or removal indices. It is guaranteed that every hash or index here has the same length, and this length is exactly 32 bits.

Generally speaking, if we sort all the entries lexicographically, we will find that the higher order bits tend not to change as frequently as lower order bits. This means that if we also take the adjacent difference between entries, the higher order bits have a high probability of being zero. This exploits this high probability of zero by essentially choosing a certain number of bits; all bits more significant than this are likely to be zero so we use unary encoding. See the riceParameter field.

Historical note: the Rice-delta encoding was first used in V4 of this API. In V5, two significant improvements were made: firstly, the Rice-delta encoding is now available with hash prefixes longer than 4 bytes; secondly, the encoded data are now treated as big-endian so as to avoid a costly sorting step.

JSON representation 
{
  "firstValue": integer,
  "riceParameter": integer,
  "entriesCount": integer,
  "encodedData": string
}
Fields
firstValue

integer (uint32 format)

The first entry in the encoded data (hashes or indices), or, if only a single hash prefix or index was encoded, that entry's value. If the field is empty, the entry is zero.
riceParameter

integer

The Golomb-Rice parameter. This parameter is guaranteed to be between 3 and 30, inclusive.
entriesCount

integer

The number of entries that are delta encoded in the encoded data. If only a single integer was encoded, this will be zero and the single value will be stored in firstValue.
encodedData

string (bytes format)

The encoded deltas that are encoded using the Golomb-Rice coder.

A base64-encoded string.

RiceDeltaEncoded64Bit

Same as RiceDeltaEncoded32Bit except this encodes 64-bit numbers.

JSON representation 
{
  "firstValue": string,
  "riceParameter": integer,
  "entriesCount": integer,
  "encodedData": string
}
Fields
firstValue

string

The first entry in the encoded data (hashes), or, if only a single hash prefix was encoded, that entry's value. If the field is empty, the entry is zero.
riceParameter

integer

The Golomb-Rice parameter. This parameter is guaranteed to be between 35 and 62, inclusive.
entriesCount

integer

The number of entries that are delta encoded in the encoded data. If only a single integer was encoded, this will be zero and the single value will be stored in firstValue.
encodedData

string (bytes format)

The encoded deltas that are encoded using the Golomb-Rice coder.

A base64-encoded string.

RiceDeltaEncoded128Bit

Same as RiceDeltaEncoded32Bit except this encodes 128-bit numbers.

JSON representation 
{
  "firstValueHi": string,
  "firstValueLo": string,
  "riceParameter": integer,
  "entriesCount": integer,
  "encodedData": string
}
Fields
firstValueHi

string

The upper 64 bits of the first entry in the encoded data (hashes). If the field is empty, the upper 64 bits are all zero.
firstValueLo

string (uint64 format)

The lower 64 bits of the first entry in the encoded data (hashes). If the field is empty, the lower 64 bits are all zero.
riceParameter

integer

The Golomb-Rice parameter. This parameter is guaranteed to be between 99 and 126, inclusive.
entriesCount

integer

The number of entries that are delta encoded in the encoded data. If only a single integer was encoded, this will be zero and the single value will be stored in firstValue.
encodedData

string (bytes format)

The encoded deltas that are encoded using the Golomb-Rice coder.

A base64-encoded string.

RiceDeltaEncoded256Bit

Same as RiceDeltaEncoded32Bit except this encodes 256-bit numbers.

JSON representation 
{
  "firstValueFirstPart": string,
  "firstValueSecondPart": string,
  "firstValueThirdPart": string,
  "firstValueFourthPart": string,
  "riceParameter": integer,
  "entriesCount": integer,
  "encodedData": string
}
Fields
firstValueFirstPart

string

The first 64 bits of the first entry in the encoded data (hashes). If the field is empty, the first 64 bits are all zero.
firstValueSecondPart

string (uint64 format)

The 65 through 128th bits of the first entry in the encoded data (hashes). If the field is empty, the 65 through 128th bits are all zero.
firstValueThirdPart

string (uint64 format)

The 129 through 192th bits of the first entry in the encoded data (hashes). If the field is empty, the 129 through 192th bits are all zero.
firstValueFourthPart

string (uint64 format)

The last 64 bits of the first entry in the encoded data (hashes). If the field is empty, the last 64 bits are all zero.
riceParameter

integer

The Golomb-Rice parameter. This parameter is guaranteed to be between 227 and 254, inclusive.
entriesCount

integer

The number of entries that are delta encoded in the encoded data. If only a single integer was encoded, this will be zero and the single value will be stored in firstValue.
encodedData

string (bytes format)

The encoded deltas that are encoded using the Golomb-Rice coder.

A base64-encoded string.

HashListMetadata

Metadata about a particular hash list.

JSON representation 
{
  "threatTypes": [
    enum (ThreatType)
  ],
  "likelySafeTypes": [
    enum (LikelySafeType)
  ],
  "mobileOptimized": boolean,
  "description": string,
  "supportedHashLengths": [
    enum (HashLength)
  ]
}
Fields
threatTypes[]

enum (ThreatType)

Unordered list. If not empty, this specifies that the hash list is a kind of threat list, and this enumerates the kind of threats associated with hashes or hash prefixes in this hash list. May be empty if the entry does not represent a threat, i.e. in the case that it represents a likely safe type.
likelySafeTypes[]

enum (LikelySafeType)

Unordered list. If not empty, this specifies that the hash list represents a list of likely safe hashes, and this enumerates the ways they are considered likely safe. This field is mutually exclusive with the threatTypes field.
mobileOptimized

boolean

Whether this list is optimized for mobile devices (Android and iOS).
description

string

A human-readable description about this list. Written in English.
supportedHashLengths[]

enum (HashLength)

The supported hash lengths for this hash list. Each hash list would support at least one length. This field therefore will not be empty.

ThreatType

Types of threats.

Enums
THREAT_TYPE_UNSPECIFIED Unknown threat type. If this is returned by the server, the client shall disregard the enclosing FullHashDetail altogether.
MALWARE

Malware threat type. Malware is any software or mobile application specifically designed to harm a computer, a mobile device, the software it's running, or its users. Malware exhibits malicious behavior that can include installing software without user consent and installing harmful software such as viruses.

More information can be found here.
SOCIAL_ENGINEERING

Social engineering threat type. Social engineering pages falsely purport to act on behalf of a third party with the intention of confusing viewers into performing an action with which the viewer would only trust a true agent of that third party. Phishing is a type of social engineering that tricks the viewer into performing the specific action of providing information, such as login credentials.

More information can be found here.
UNWANTED_SOFTWARE Unwanted software threat type. Unwanted software is any software that does not adhere to Google's Software Principles but isn't malware.
POTENTIALLY_HARMFUL_APPLICATION Potentially harmful application threat type as used by Google Play Protect for the Play Store.

LikelySafeType

Types of likely-safe sites.

Note that the SearchHashesResponse intentionally does not contain LikelySafeType.

Enums
LIKELY_SAFE_TYPE_UNSPECIFIED Unknown.
GENERAL_BROWSING This site is likely safe enough for general browsing. This is also known as the global cache.
CSD This site is likely safe enough that there is no need to run Client-Side Detection models or password protection checks.
DOWNLOAD This site is likely safe enough that downloads from the site need not be checked.

HashLength

The length of hashes in a hash list.

Enums
HASH_LENGTH_UNSPECIFIED Unspecified length. The server will not return this value in responses to the client (in the supportedHashLengths field), but the client is allowed to send this value to the server (in the desiredHashLength field), in which case the server will pick a value automatically. Clients SHOULD let the server pick a value.
FOUR_BYTES Each hash is a four-byte prefix.
EIGHT_BYTES Each hash is an eight-byte prefix.
SIXTEEN_BYTES Each hash is a sixteen-byte prefix.
THIRTY_TWO_BYTES Each hash is a thirty-two-byte full hash.

Methods

get

 Get the latest contents of a hash list.