REST Resource: hashList

資源:HashList

以名稱識別的雜湊清單。

JSON 表示法
{
  "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.
}
欄位
name

string

雜湊清單的名稱。請注意,全域快取也只是雜湊清單,可以參閱這裡。

version

string (bytes format)

雜湊清單版本。用戶端「不得」操縱這些位元組。

Base64 編碼字串。

partialUpdate

boolean

設為 true 時,僅代表根據用戶端已具備的功能進行新增和移除作業的部分差異。如果為 false,則此為完整的雜湊清單。

如果設為 False,用戶端「必須」刪除這份雜湊清單儲存在本機的任何版本。這表示用戶端擁有的版本非常過時,或是用戶端資料已毀損。compressedRemovals 欄位將留空。

設為 true 時,客戶「必須」先套用移除條件,然後再套用累加更新,以套用漸進式更新。

compressedRemovals

object (RiceDeltaEncoded32Bit)

移除索引的 Rice-delta 編碼版本。由於每個雜湊清單一定會有少於 2^32 個項目,因此索引會被視為 32 位元整數並進行編碼。

minimumWaitDuration

string (Duration format)

用戶端至少應等待這個時間,才能再次取得雜湊清單。如果省略或零,用戶端「必須」立即擷取,因為這表示伺服器還有要傳送至用戶端的額外更新,但由於用戶端指定的限製而無法更新。

持續時間以秒為單位,最多 9 個小數位數,結尾為「s」。範例:"3.5s"

metadata

object (HashListMetadata)

雜湊清單的中繼資料。這不會由 hashList.get 方法填入,但會由 ListHashLists 方法填入。

聯集欄位 compressed_additions。附加內容為 Rice-delta 編碼的版本。清單內所有新增項目的雜湊前置字元長度都相同。它是用戶端傳送的 desired_hash_length,或是用戶端省略該欄位時選擇的值。compressed_additions 只能採用下列其中一種設定:
additionsFourBytes

object (RiceDeltaEncoded32Bit)

額外 4 位元組。

additionsEightBytes

object (RiceDeltaEncoded64Bit)

超過 8 個位元組的新增項目。

additionsSixteenBytes

object (RiceDeltaEncoded128Bit)

額外增加的 16 個位元組。

additionsThirtyTwoBytes

object (RiceDeltaEncoded256Bit)

超過 32 個位元組的額外值。

聯集欄位 checksum。這是套用提供的更新後,資料庫中所有雜湊的排序清單的總和。此為「獨有」] 欄位允許多個雜湊演算法。伺服器也可以省略這個欄位 (如未提供更新),指出用戶端應使用現有的總和檢查碼。checksum 只能是下列其中一項:
sha256Checksum

string (bytes format)

所有雜湊的排序清單,使用 SHA256 再次進行雜湊處理。

Base64 編碼字串。

RiceDeltaEncoded32Bit

Rice-Golomb 編碼的資料。用於雜湊或移除索引。這裡保證這裡每個雜湊或索引的長度都相同,且此長度剛好為 32 位元。

一般而言,如果我們按照字母順序排列所有項目,會發現較高順序的位元往往不會與低階位元一樣頻繁發生。這表示若同時得出項目之間的相鄰差異,則較高順序位元的機率很高為零。此攻擊主要透過選擇特定位元數,來濫用這個高度可能為零的攻擊;剛好比 0 高一些,所以可能是零,所以我們要使用一元編碼。請參閱 riceParameter 欄位。

歷史記錄:此 API 的 V4 首次使用 Rice-delta 編碼。V5 做了兩項重大改善:首先,Rice-delta 編碼可用超過 4 個位元組的雜湊前置字元;其次,編碼後的資料現在會視為大端序,以免排列步驟的成本高昂。

JSON 表示法
{
  "firstValue": integer,
  "riceParameter": integer,
  "entriesCount": integer,
  "encodedData": string
}
欄位
firstValue

integer (uint32 format)

編碼資料的第一個項目 (斜線或索引);如果只有一個雜湊前置字串或索引,則會傳回該項目的值。如果這個欄位空白,項目就會是 0。

riceParameter

integer

Golomb-Rice 參數。此參數保證介於 3 到 30 (含) 之間。

entriesCount

integer

編碼資料中經過差異編碼的項目數量。如果只編碼一個整數,該值將會是 0,而單一值將儲存在 firstValue 中。

encodedData

string (bytes format)

使用 Golomb-Rice 編碼器編碼的編碼差異值。

Base64 編碼字串。

RiceDeltaEncoded64Bit

RiceDeltaEncoded32Bit 相同,差別只在這個編碼會對 64 位元數字進行編碼。

JSON 表示法
{
  "firstValue": string,
  "riceParameter": integer,
  "entriesCount": integer,
  "encodedData": string
}
欄位
firstValue

string

經過編碼的資料 (含雜湊碼) 中的第一個項目;如果只有單一雜湊前置字元經過編碼,則會改為該項目的值。如果這個欄位空白,項目就會是 0。

riceParameter

integer

Golomb-Rice 參數。此參數保證介於 35 到 62 (含) 之間。

entriesCount

integer

編碼資料中經過差異編碼的項目數量。如果只編碼一個整數,該值將會是 0,而單一值將儲存在 firstValue 中。

encodedData

string (bytes format)

使用 Golomb-Rice 編碼器編碼的編碼差異值。

Base64 編碼字串。

RiceDeltaEncoded128Bit

RiceDeltaEncoded32Bit 相同,差別只在這個編碼會編碼 128 位元數字。

JSON 表示法
{
  "firstValueHi": string,
  "firstValueLo": string,
  "riceParameter": integer,
  "entriesCount": integer,
  "encodedData": string
}
欄位
firstValueHi

string

編碼資料中第一個項目的上方 64 位元 (雜湊)。如果這個欄位空白,則上方 64 位元全為 0。

firstValueLo

string (uint64 format)

編碼資料中第一個項目的 64 位元下限。如果這個欄位空白,則低於 64 位元的位元數均為 0。

riceParameter

integer

Golomb-Rice 參數。此參數保證介於 99 到 126 (含) 之間。

entriesCount

integer

編碼資料中經過差異編碼的項目數量。如果只編碼一個整數,該值將會是 0,而單一值將儲存在 firstValue 中。

encodedData

string (bytes format)

使用 Golomb-Rice 編碼器編碼的編碼差異值。

Base64 編碼字串。

RiceDeltaEncoded256Bit

RiceDeltaEncoded32Bit 相同,差別只在這個程式碼會編碼 256 位元數字。

JSON 表示法
{
  "firstValueFirstPart": string,
  "firstValueSecondPart": string,
  "firstValueThirdPart": string,
  "firstValueFourthPart": string,
  "riceParameter": integer,
  "entriesCount": integer,
  "encodedData": string
}
欄位
firstValueFirstPart

string

編碼資料中第一個項目的前 64 位元 (雜湊)。如果這個欄位空白,前 64 位元全為 0。

firstValueSecondPart

string (uint64 format)

編碼資料中第一個項目的 65 到 128 位元 (雜湊)。如果這個欄位空白,65 到 128 位元全為 0。

firstValueThirdPart

string (uint64 format)

編碼資料中第一個項目的 129 到 192 位元 (雜湊)。如果這個欄位空白,則 129 到 192 位元全為 0。

firstValueFourthPart

string (uint64 format)

編碼資料中第一個項目的最後一個 64 位元 (雜湊)。如果這個欄位空白,最後 64 位元全為 0。

riceParameter

integer

Golomb-Rice 參數。此參數保證介於 227 到 254 (含) 之間。

entriesCount

integer

編碼資料中經過差異編碼的項目數量。如果只編碼一個整數,該值將會是 0,而單一值將儲存在 firstValue 中。

encodedData

string (bytes format)

使用 Golomb-Rice 編碼器編碼的編碼差異值。

Base64 編碼字串。

HashListMetadata

特定雜湊清單的相關中繼資料。

JSON 表示法
{
  "threatTypes": [
    enum (ThreatType)
  ],
  "likelySafeTypes": [
    enum (LikelySafeType)
  ],
  "mobileOptimized": boolean,
  "description": string,
  "supportedHashLengths": [
    enum (HashLength)
  ]
}
欄位
threatTypes[]

enum (ThreatType)

未排序的清單。如果非空白,表示雜湊清單是威脅清單的種類,且會在這份雜湊清單中列舉與雜湊或雜湊前置字串相關的威脅類型。如果該項目不代表威脅 (也就是可能為安全類型),則為空白。

likelySafeTypes[]

enum (LikelySafeType)

未排序的清單。如果非空白,表示雜湊清單代表可能安全的雜湊清單,列舉可能為安全的雜湊。此欄位與 ThreatTypes 欄位互斥。

mobileOptimized

boolean

這份清單是否已針對行動裝置 (Android 和 iOS) 進行最佳化。

description

string

使用者可理解的清單說明。英語

supportedHashLengths[]

enum (HashLength)

這份雜湊清單支援的雜湊長度。每份雜湊清單至少支援一種長度。因此,這個欄位不會空白。

ThreatType

威脅類型。

列舉
THREAT_TYPE_UNSPECIFIED 未知的威脅類型。如果伺服器傳回此方法,用戶端應完全忽略內含的 FullHashDetail
MALWARE

惡意軟體威脅類型。只要軟體或行動應用程式會刻意危害電腦、行動裝置、這些裝置執行的軟體或其使用者,就屬於惡意軟體。惡意軟體會帶來各種形式的惡意行為,包括未經使用者同意便擅自安裝軟體,以及安裝病毒等有害軟體。

詳情請參閱這裡

SOCIAL_ENGINEERING

社交工程威脅類型。謊稱有第三方身分的社交工程網頁,企圖讓觀眾誤以為執行某個動作,但觀眾只會信任該第三方的真實代理人。網路釣魚是一種社交工程,會誘騙觀眾執行特定動作,例如登入憑證。

詳情請參閱這裡

UNWANTED_SOFTWARE 垃圾軟體威脅類型。垃圾軟體是指任何不符合 Google 軟體規範,但不是惡意軟體的軟體。
POTENTIALLY_HARMFUL_APPLICATION Google Play 安全防護使用 Play 商店時,可能有害的應用程式威脅類型。

LikelySafeType

可能有安全疑慮的網站類型。

請注意,我們刻意在 SearchHashesResponse 不包含 LikelySafeType

列舉
LIKELY_SAFE_TYPE_UNSPECIFIED 未知。
GENERAL_BROWSING 這個網站可能適合一般瀏覽時使用。這項作業也稱為全域快取。
CSD 這個網站可能已足夠安全,因此不需要執行用戶端偵測模型或密碼保護檢查。
DOWNLOAD 這個網站本身可能安全無虞,因此網站不需要檢查下載。

HashLength

雜湊清單中的雜湊長度。

列舉
HASH_LENGTH_UNSPECIFIED 未指定長度。伺服器不會在給用戶端 (位於 supportedHashLengths 欄位) 的回應中傳回這個值,但用戶端可以將這個值 (位於 desiredHashLength 欄位) 傳送至伺服器;在此情況下,伺服器會自動挑選一個值。用戶端「必須」讓伺服器挑選值。
FOUR_BYTES 每個雜湊都是四位元組的前置字元。
EIGHT_BYTES 每個雜湊都是八位元組的前置字串。
SIXTEEN_BYTES 每個雜湊都是 16 個位元組的前置字元。
THIRTY_TWO_BYTES 每個雜湊都是三十二位元組完整雜湊。

方法

get

取得雜湊清單的最新內容。