Overview

簡介

注意：這份文件目前仍在開發階段，希望不久後也能有所改善。

Google 安全瀏覽第 5 版是 Google 安全瀏覽第 4 版的演變過程。第 5 版中的兩項重要變更是資料更新間隔和 IP 隱私權。此外，API 介面也經過改善，可提高彈性、效率並減少膨脹。此外，Google 安全瀏覽第 5 版是專為簡化第 4 版遷移作業而設計。

目前，Google 同時提供第 4 版和第 5 版，且兩者均視為正式版。建議使用 v4 或 v5。我們尚未宣布停用第 4 版的日期，否則，至少會有一年的時間通知。本頁面將說明第 5 版，以及從 v4 至 v5 的遷移指南；完整的 v4 說明文件仍可供使用。

資料更新間隔

相較於 v4 Update API，Google 安全瀏覽第 5 版大幅改善了資料更新間隔和涵蓋範圍。由於保護高度取決於用戶端維護的本機資料庫，因此本機資料庫更新的延遲時間與大小是遺漏保護的主要原因。在 v4 中，典型用戶端需要 20 至 50 分鐘才能取得最新版本的威脅清單。不幸的是，網路釣魚攻擊快速擴散：截至 2021 年，60% 的網站發動攻擊的時間不到 10 分鐘。我們的分析顯示，約有 25-30% 的網路釣魚防護手段是這些資料過時所致。此外，某些裝置無法管理整個 Google 安全瀏覽威脅清單，且這份清單仍在持續增加中。

在第 5 版中，我們引進了一種作業模式，稱為即時防護。這能規避上述的資料過時問題。在 v4 中，用戶端應下載並維護本機資料庫，針對本機下載的威脅清單執行檢查，當有部分前置碼相符時，執行要求下載完整的雜湊。在 v5 中，雖然用戶端應繼續下載並維護本機威脅清單的本機資料庫，但用戶端現在也預計下載可能良性的網站清單（稱為「全域快取」），對此全域快取和本機威脅清單檢查執行本機檢查，最後在威脅清單有部分前置字串相符或全域快取不相符時，執行下載完整雜湊的要求。(如要進一步瞭解用戶端所需的本機處理程序，請參閱以下提供的程序)。這代表從預設為「允許」轉變為預設為「預設檢查」，在加快網路威脅傳播速度的同時提升防護能力。換句話說，這個通訊協定旨在提供近乎即時的防護：我們的目標是讓客戶受益於更新過的 Google 安全瀏覽資料。

IP 隱私權

Google 安全瀏覽 (v4 或 v5) 不會在服務要求期間處理與使用者身分相關聯的任何內容。如果傳送 Cookie，系統會忽略 Cookie。Google 已知道要求的來源 IP 位址，但 Google 只會將這些 IP 位址用於基本網路需求 (例如傳送回應) 和反 DoS 用途。

與第 5 版同時，我們導入了名為 Safe Browsing Oblivious HTTP Gateway API 的隨附 API。這會使用顯而易見的 HTTP 向 Google 隱藏使用者的 IP 位址。這項功能的運作方式是由非合作的第三方處理使用者要求的加密版本，然後再轉達給 Google。也就是說，第三方僅可存取 IP 位址，而 Google 也只能存取要求內容。第三方會執行「顯而易見的 HTTP 轉送」(例如 Fastly 提供的這項服務)，而 Google 會負責執行「假冒的 HTTP 閘道」。這是選用的隨附 API。將 Google 安全瀏覽功能與 Google 安全瀏覽功能搭配使用時，系統就不會再將使用者的 IP 位址傳送給 Google。

適當使用方式

許可的用途

Safe Browsing API 僅供非商業用途 (意即「不得用於銷售或產生收益」)。如需商業用途的解決方案，請參閱 Web Risk。

定價

所有 Google Safe Browsing API 都開放免費使用。

配額

啟用 Safe Browsing API 後，開發人員會獲得預設的使用配額。如要查看目前的配置和用量，請前往 Google Developers Console。如果預期使用的資源會超過目前分配的配額，您可以透過 Developer Console 的「配額」介面要求額外配額。我們會審查這些要求，並在申請提高配額時要求聯絡，確保 Google 服務可用性符合所有使用者的需求。

適當網址

Google 安全瀏覽功能可以為顯示在瀏覽器網址列中的網址採取行動。而不是用來檢查子資源 (例如 HTML 檔案參照的 JavaScript 或圖片，或 JavaScript 啟動的 WebSocket 網址)。「請勿」比對 Google 安全瀏覽功能檢查這類子資源網址。

造訪網址會導致重新導向 (例如 HTTP 301) 時，Google 安全瀏覽功能可以檢查重新導向的網址。用戶端網址操控 (例如 History.pushState)「不會」讓 Google 安全瀏覽功能檢查新網址。

使用者警告

如果您使用 Google 安全瀏覽服務，警告使用者留意特定網頁的風險，請遵守下列規範。

這些規範會清楚指出網頁並非 100% 的確定度為不安全的網路資源，且只是指出可能的風險，有助於您和 Google 避免受到誤解。

• 使用者看到警告訊息時，不得讓使用者以為有問題的網頁，而非疑惑的網路資源。如果您提及被識別的網頁或可能對使用者造成的風險，則必須使用以下字詞讓警告認定為可能、可能、有可能是可能、可能有以下字詞。
• 您的警告必須讓使用者能夠檢閱 Google 對各種威脅的定義，瞭解更多資訊。建議使用下列連結：
  • 社交工程：https://developers.google.com/search/docs/monitor-debug/security/social-engineering
  • 惡意軟體和垃圾軟體：https://developers.google.com/search/docs/monitor-debug/security/malware
  • 可能有害的應用程式 (僅限 Android)：https://developers.google.com/android/play-protect/potentially-harmful-applications
• 當您針對安全瀏覽服務判定為具有風險的網頁顯示警告時，必須附上「Google 提供的 Advisory」這行程式碼，並附上安全瀏覽諮詢的連結，將資訊告知 Google。如果產品同時也依據其他來源顯示警告，則不得在由非 Google 資料衍生的警告中納入 Google 歸因分析。

• 您必須在產品說明文件中告知使用者，Google 安全瀏覽功能提供的保護功能並非完美無缺。請務必告知對方，網站可能會誤報 (安全網站標記為有風險的網站) 和系統誤判 (未標記風險網站)。建議您使用以下語言：

  Google 致力針對不安全的網路資源，提供最準確的最新資訊。不過，Google 無法保證所提供的資訊完整且沒有錯誤：系統可能無法找出某些有風險的網站，且可能會誤認為部分安全網站。

作業模式

Google 安全瀏覽第 5 版可讓用戶端選擇三種操作模式。

即時模式

當用戶端選擇使用 Google 安全瀏覽第 5 版即時模式時，用戶端會在本機資料庫中維護：(i) 可能來源網站的全域快取，格式為 host-suffix/path-prefix URL 運算式的 SHA256 雜湊；(ii) 一組威脅清單，格式為主機字尾/路徑前置字元網址運算式的 SHA256 雜湊前置字串。整體來說，當用戶端想要檢查特定網址時，系統會使用全域快取執行本機檢查。如果通過該檢查，將會執行本機威脅清單檢查。否則，用戶端會繼續執行即時雜湊檢查，詳情如下。

除了本機資料庫，用戶端也會維護本機快取。這類本機快取不需要永久儲存空間，可在記憶體有壓力時清除。

如要詳細瞭解這個程序，請參閱下方資訊。

本機清單模式

當用戶端選擇在這個模式下使用 Google 安全瀏覽第 5 版時，用戶端行為會與 v4 Update API 類似，差別只在於使用 v5 改良的 API 介面。用戶端會在本機資料庫中維護一組威脅清單，格式為具有 host-suffix/path-prefix URL 運算式的 SHA256 雜湊前置字串。只要用戶端想要檢查特定網址，系統就會使用本機威脅清單執行檢查。如果有相符項目，用戶端會連線至伺服器繼續檢查。

和上述方法一樣，用戶端也會維護一個不需要永久儲存空間的本機快取。

無儲存空間即時模式

當用戶端選擇在無儲存空間的即時模式下使用 Google 安全瀏覽第 5 版時，用戶端就不必維護任何永久本機資料庫。不過，用戶端仍應保留本機快取。這類本機快取不需要永久儲存空間，可在記憶體有壓力時清除。

每當用戶端想要檢查特定網址時，用戶端一律會連線到伺服器執行檢查。這個模式與第 4 版 Lookup API 的用戶端可以實作的模式類似。

與即時模式相比，這個模式可能會使用較多網路頻寬，但如果用戶端無法維持永久本機狀態，這個模式可能更適合。

正在檢查網址

本節詳細說明用戶端檢查網址的方式。

網址標準化

用戶端應先對該網址執行部分標準化，再檢查任何網址。

首先，我們假設用戶端已剖析網址，並根據 RFC 2396 使網址有效。如果網址使用國際化網域名稱 (IDN)，用戶端應將網址轉換為 ASCII Punycode 表示法。網址必須包含路徑元件，也就是說，網址中至少要在網域後方加入一個斜線 (http://google.com/，而不是 http://google.com)。

首先，請移除網址中的 Tab 鍵 (0x09)、CR (0x0d) 和 LF (0x0a) 字元。請勿移除這些字元的逸出序列 (例如 %0a)。

其次，如果網址結束於片段，請移除該片段。例如，請將 http://google.com/#frag 縮短為 http://google.com/。

第三，重複將網址取消逸出百分比，直到沒有其他百分比逸出為止。(這可能會導致網址無效)。

如何標準化主機名稱：

從網址中擷取主機名稱，然後：

1. 移除所有開頭和結尾的點。
2. 以單一點取代連續點。
3. 如果主機名稱可以剖析為 IPv4 位址，請將其正規化為 4 個以點分隔的十進位值。用戶端應處理任何合法的 IP 位址編碼，包括八進位、十六進位以及少於四個元件。
4. 如果主機名稱可剖析為括號內的 IPv6 位址，請將其正規化，方法是移除元件中不需要的前置零，並使用雙冒號語法收合零個元件。舉例來說，[2001:0db8:0000::1] 必須轉換為 [2001:db8::1]。如果主機名稱是下列任一特殊 IPv6 位址類型之一，請轉換為 IPv4：
   • 與 IPv4 對應的 IPv6 位址 (例如 [::ffff:1.2.3.4])，應轉換為 1.2.3.4。
   • 使用知名前置碼 64:ff9b::/96 的 NAT64 位址 (例如 [64:ff9b::1.2.3.4])，應轉換為 1.2.3.4。
5. 將整個字串小寫。

如要標準化路徑：

1. 將 /./ 替換為 /，並移除 /../ 與上述路徑元件，即可解決路徑中的 /../ 和 /./ 序列。
2. 以單一斜線字元取代連續斜線字元。

請勿將這些路徑標準化程序套用至查詢參數。

在網址中，所有 <= ASCII 32、>= 127、# 或 % 的字元都會以百分比逸出的形式表示。逸出應使用大寫十六進位字元。

主機後置字串路徑前置字元運算式

將網址標準化後，下一步是建立後置字元/前置字串運算式。每個後置字元/前置字串運算式都是由主機後置字串 (或完整主機) 和路徑前置字串 (或完整路徑) 組成。

用戶端最多可建立 30 個不同的主機後置字元和路徑前置字元組合。這些組合只會使用網址的主機和路徑元件。配置、使用者名稱、密碼和通訊埠將遭到捨棄。如果網址包含查詢參數，則至少一個組合會包含完整路徑和查詢參數。

針對主機，用戶端最多將嘗試五個不同的字串。這些因素包括：

• 但若主機名稱不是 IPv4 或 IPv6 常值，最多則以 eTLD+1 網域開頭並新增後續的前置元件，形成最多四個主機名稱。eTLD+1 的判斷依據應為公開尾碼清單。舉例來說，a.b.example.com 會得到 example.com 的 eTLD+1 網域，以及含有一個額外主機元件 b.example.com 的主機。
• 網址的完整主機名稱。根據上一個範例，系統會檢查 a.b.example.com。

針對路徑，用戶端最多只可嘗試六個不同的字串。這些因素包括：

• 網址的確切路徑，包括查詢參數。
• 網址的確切路徑，不含查詢參數。
• 四個路徑是由根 (/) 開始，並依序附加路徑元件 (包括結尾的斜線) 形成。

以下範例說明檢查行為：

針對 http://a.b.com/1/2.html?param=1 網址，用戶端將嘗試下列可能的字串：

a.b.com/1/2.html?param=1
a.b.com/1/2.html
a.b.com/
a.b.com/1/
b.com/1/2.html?param=1
b.com/1/2.html
b.com/
b.com/1/

針對 http://a.b.c.d.e.f.com/1.html 網址，用戶端將嘗試下列可能的字串：

a.b.c.d.e.f.com/1.html
a.b.c.d.e.f.com/
c.d.e.f.com/1.html
c.d.e.f.com/
d.e.f.com/1.html
d.e.f.com/
e.f.com/1.html
e.f.com/
f.com/1.html
f.com/

(注意：請略過 b.c.d.e.f.com，因為我們只需取得最後 5 個主機名稱元件，以及完整的主機名稱)。

針對 http://1.2.3.4/1/ 網址，用戶端將嘗試下列可能的字串：

1.2.3.4/1/
1.2.3.4/

針對 http://example.co.uk/1 網址，用戶端將嘗試下列可能的字串：

example.co.uk/1
example.co.uk/

雜湊

Google 安全瀏覽功能只會使用 SHA256 做為雜湊函式。這個雜湊函式應套用至上述運算式。

完整 32 位元組雜湊會視需要縮短為 4 個位元組、8 個位元組或 16 個位元組：

• 使用 hashes.search 方法時，目前要求中的雜湊必須整併至 4 個位元組。在這項要求中傳送額外的位元組會侵害使用者隱私。

• 使用 hashList.get 方法或 hashLists.batchGet 方法下載本機資料庫的清單時，伺服器傳送的雜湊長度會同時影響清單的性質以及用戶端對 參數的偏好長度 (由 desired_hash_length 參數傳遞)。

即時網址檢查程序

用戶端選擇即時作業模式時，就會使用這項程序。

這個程序需要單一網址 u，並傳回 SAFE、UNSAFE 或 UNSURE。如果傳回 SAFE，Google 安全瀏覽功能會將網址視為安全。如果傳回 UNSAFE，Google 安全瀏覽功能判定該網址可能不安全，並應採取適當行動，例如向使用者顯示警告、將收到的郵件移至垃圾郵件資料夾，或要求使用者進行額外確認才能繼續操作。如果傳回 UNSURE，則之後應使用以下本機檢查程序。

1. 讓 expressions 是網址 u 產生的後置字元/前置字串運算式清單。
2. 讓 expressionHashes 為清單，其中元素為 expressions 中每個運算式的 SHA256 雜湊。
3. 針對 expressionHashes 的每個 hash：
   1. 如果 hash 可在全域快取中找到，請傳回 UNSURE。
4. 可以將 expressionHashPrefixes 設為清單，其中元素是 expressionHashes 中每個雜湊的前 4 個位元組。
5. 針對 expressionHashPrefixes 的每個 expressionHashPrefix：
   1. 在本機快取中查詢 expressionHashPrefix。
   2. 如果找到快取項目：
      1. 判斷目前時間是否大於其到期時間。
      2. 如果選項較大：
         1. 從本機快取中移除找到的快取項目。
         2. 繼續迴圈。
      3. 如果數值不大：
         1. 從 expressionHashPrefixes 移除這個特定expressionHashPrefix。
         2. 檢查快取項目中是否有 expressionHashes 內的對應完整雜湊。
         3. 找到後，請傳回 UNSAFE。
         4. 如果找不到，請繼續迴圈。
   3. 如果找不到快取項目，請繼續執行迴圈。
6. 使用 RPC SearchHashes 或 REST 方法 hashes.search，將 expressionHashPrefixes 傳送至 Google 安全瀏覽第 5 版伺服器。如果發生錯誤 (包括網路錯誤、HTTP 錯誤等)，請傳回 UNSURE。否則，請讓回應來自 SB 伺服器收到的 response，這個清單是完整的雜湊清單，以及指出威脅性質的輔助資訊 (社交工程和惡意軟體等)，以及快取到期時間 expiration。
7. 針對 response 的每個 fullHash：
   1. 將 fullHash 和 expiration 一起插入本機快取中。
8. 針對 response 的每個 fullHash：
   1. 讓 isFound 成為在 expressionHashes 中找到 fullHash 的結果。
   2. 如果 isFound 為 False，請繼續執行迴圈。
   3. 如果 isFound 為 True，則傳回 UNSAFE。
9. 傳回「SAFE」。

雖然這個通訊協定會指定用戶端將 expressionHashPrefixes 傳送至伺服器的時間，但此通訊協定刻意不明確地指定傳送用戶端的「方式」。舉例來說，用戶端可以在單一要求中傳送所有 expressionHashPrefixes，也可以讓用戶端透過個別要求，將 expressionHashPrefixes 中的每個個別前置字串傳送至伺服器 (也許可以同時處理)。此外，只要單一要求傳送的雜湊前置字元數量不超過 30 個，用戶端也可以傳送不相關或隨機產生的雜湊前置字元，以及 expressionHashPrefixes 中的雜湊前置字元。

本機威脅清單網址檢查程序

當用戶端選擇使用本機清單作業模式時，就會使用這項程序。當上述的 RealTimeCheck 程序傳回 UNSURE 的值時，也會使用這個符號。

這個程序需要單一網址 u 並傳回 SAFE 或 UNSAFE。

1. 讓 expressions 是網址 u 產生的後置字元/前置字串運算式清單。
2. 讓 expressionHashes 為清單，其中元素為 expressions 中每個運算式的 SHA256 雜湊。
3. 可以將 expressionHashPrefixes 設為清單，其中元素是 expressionHashes 中每個雜湊的前 4 個位元組。
4. 針對 expressionHashPrefixes 的每個 expressionHashPrefix：
   1. 在本機快取中查詢 expressionHashPrefix。
   2. 如果找到快取項目：
      1. 判斷目前時間是否大於其到期時間。
      2. 如果選項較大：
         1. 從本機快取中移除找到的快取項目。
         2. 繼續迴圈。
      3. 如果數值不大：
         1. 從 expressionHashPrefixes 移除這個特定expressionHashPrefix。
         2. 檢查快取項目中是否有 expressionHashes 內的對應完整雜湊。
         3. 找到後，請傳回 UNSAFE。
         4. 如果找不到，請繼續迴圈。
   3. 如果找不到快取項目，請繼續執行迴圈。
5. 針對 expressionHashPrefixes 的每個 expressionHashPrefix：
   1. 在本機威脅清單資料庫中查詢 expressionHashPrefix。
   2. 如果在本機威脅清單資料庫中找不到 expressionHashPrefix，請將其從 expressionHashPrefixes 中移除。
6. 使用 RPC SearchHashes 或 REST 方法 hashes.search，將 expressionHashPrefixes 傳送至 Google 安全瀏覽第 5 版伺服器。如果發生錯誤 (包括網路錯誤、HTTP 錯誤等)，請傳回 SAFE。否則，請讓回應來自 SB 伺服器收到的 response，這個清單是完整的雜湊清單，以及指出威脅性質的輔助資訊 (社交工程和惡意軟體等)，以及快取到期時間 expiration。
7. 針對 response 的每個 fullHash：
   1. 將 fullHash 和 expiration 一起插入本機快取中。
8. 針對 response 的每個 fullHash：
   1. 讓 isFound 成為在 expressionHashes 中找到 fullHash 的結果。
   2. 如果 isFound 為 False，請繼續執行迴圈。
   3. 如果 isFound 為 True，則傳回 UNSAFE。
9. 傳回「SAFE」。

即時網址檢查程序不使用本機資料庫

在用戶端選擇無儲存空間即時作業模式時，系統會使用這項程序。

這個程序需要單一網址 u 並傳回 SAFE 或 UNSAFE。

1. 讓 expressions 是網址 u 產生的後置字元/前置字串運算式清單。
2. 讓 expressionHashes 為清單，其中元素為 expressions 中每個運算式的 SHA256 雜湊。
3. 可以將 expressionHashPrefixes 設為清單，其中元素是 expressionHashes 中每個雜湊的前 4 個位元組。
4. 針對 expressionHashPrefixes 的每個 expressionHashPrefix：
   1. 在本機快取中查詢 expressionHashPrefix。
   2. 如果找到快取項目：
      1. 判斷目前時間是否大於其到期時間。
      2. 如果選項較大：
         1. 從本機快取中移除找到的快取項目。
         2. 繼續迴圈。
      3. 如果數值不大：
         1. 從 expressionHashPrefixes 移除這個特定expressionHashPrefix。
         2. 檢查快取項目中是否有 expressionHashes 內的對應完整雜湊。
         3. 找到後，請傳回 UNSAFE。
         4. 如果找不到，請繼續迴圈。
   3. 如果找不到快取項目，請繼續執行迴圈。
5. 使用 RPC SearchHashes 或 REST 方法 hashes.search，將 expressionHashPrefixes 傳送至 Google 安全瀏覽第 5 版伺服器。如果發生錯誤 (包括網路錯誤、HTTP 錯誤等)，請傳回 SAFE。否則，請讓回應來自 SB 伺服器收到的 response，這個清單是完整的雜湊清單，以及指出威脅性質的輔助資訊 (社交工程和惡意軟體等)，以及快取到期時間 expiration。
6. 針對 response 的每個 fullHash：
   1. 將 fullHash 和 expiration 一起插入本機快取中。
7. 針對 response 的每個 fullHash：
   1. 讓 isFound 成為在 expressionHashes 中找到 fullHash 的結果。
   2. 如果 isFound 為 False，請繼續執行迴圈。
   3. 如果 isFound 為 True，則傳回 UNSAFE。
8. 傳回「SAFE」。

與即時網址檢查程序一樣，這個程序並不會明確指定將雜湊前置字串傳送至伺服器的方式。舉例來說，用戶端可以在單一要求中傳送所有 expressionHashPrefixes，也可以讓用戶端透過個別要求，將 expressionHashPrefixes 中的每個個別前置字串傳送至伺服器 (也許可以同時處理)。此外，只要單一要求傳送的雜湊前置字元數量不超過 30 個，用戶端也可以傳送不相關或隨機產生的雜湊前置字元，以及 expressionHashPrefixes 中的雜湊前置字元。

本機資料庫維護

除非用戶端選擇無儲存空間即時模式，Google 安全瀏覽第 5 版預期用戶端會維護本機資料庫。用戶端可自行決定這個本機資料庫的格式和儲存空間。從概念上來說，這個本機資料庫的內容可視為資料夾，內含多份清單做為檔案，且這些檔案的內容為 SHA256 雜湊或雜湊前置字串。

資料庫更新

用戶端會定期呼叫 hashList.get 方法或 hashLists.batchGet 方法來更新資料庫。一般用戶端會一次更新多份清單，因此建議使用 hashLists.batchGet 方法。

系統會透過名稱明確識別清單。這些名稱是短的 ASCII 字串，長度為幾個字元。

與 V4 不同，在 v5 清單中，清單會按照威脅類型、平台類型、威脅項目類型的元組識別。當多個 v5 清單可共用相同威脅類型時，這提供了彈性。第 5 版移除了平台類型和威脅項目類型，

為清單命名後，清單名稱就不會再變更。此外，一旦清單產生後就永遠不會遭到移除 (如果清單已經不再實用，該清單會變成空白，但會繼續存在)。因此，您可以在 Google 安全瀏覽用戶端程式碼中以硬式編碼方式編寫這些名稱。

hashList.get 方法和 hashLists.batchGet 方法都支援漸進式更新。使用漸進式更新可以節省頻寬並提升效能。漸進式更新的運作方式為用戶端清單和最新版清單提供差異值。(如果用戶端才剛部署完畢，且沒有任何可用版本，則有可用的完整更新。)增量更新包括移除索引和新增功能。用戶端首先應從本機資料庫移除指定索引的項目，再套用新增的部分。

最後，為防止資料損毀，用戶端應根據伺服器提供的總和檢查碼檢查儲存的資料。只要總和檢查碼不相符，用戶端就應執行完整更新。

解碼清單內容

將雜湊和雜湊前置字串解碼

所有清單都會以特殊編碼方式傳送，以縮減大小。這個編碼的運作方式是，在概念上清楚知道 Google 安全瀏覽清單包含一組雜湊或雜湊字首，這些雜湊與隨機整數在統計上難以區分。如果我們將這些整數排序並相鄰，這些相鄰的差異應該是「小」。接著 Golomb-Rice 編碼利用這個小型程式碼。

假設三個主機字尾路徑運算式運算式 (即 a.example.com/、b.example.com/ 和 y.example.com/) 都會使用 4 位元組雜湊前置字元進行傳輸。此外，假設 Rice 參數 (以 k 表示) 已設為 30。伺服器會先計算這些字串的完整雜湊，如下所示：

291bc5421f1cd54d99afcc55d166e2b9fe42447025895bf09dd41b2110a687dc  a.example.com/
1d32c5084a360e58f1b87109637a6810acad97a861a7769e8f1841410d2a960c  b.example.com/
f7a502e56e8b01c6dc242b35122683c9d25d07fb1f532d9853eb0ef3ff334f03  y.example.com/

接著，伺服器會為上述每個項目組成 4 位元組雜湊前置字串，也就是 32 位元組完整雜湊的前 4 個位元組，解讀為大端序 32 位元整數。很大程度是指完整雜湊的第一個位元組會成為 32 位元整數中最重要的位元組。這個步驟會產生整數 0x291bc542、0x1d32c508 和 0xf7a502e5。

伺服器必須按字母順序排列這三個雜湊前置字元 (相當於大端序的數值排序)，排序結果為 0x1d32c508, 0x291bc542, 0xf7a502e5。第一個雜湊前置字串儲存於 first_value 欄位中，

然後伺服器會計算這兩個相鄰的差異，分別分別為 0xbe9003a 和 0xce893da3。由於 k 選擇為 30，伺服器會將這兩個數字分成商量部分，並分別時間長度為 2 和 30 位元的餘數部分。第一個數字的商部分為 0，餘數則是 0xbe9003a；在第二個數字中，商數的部分為 3，因為最重要的兩個位元在二進位中為 11，餘數則是 0xe893da3。針對指定的商數 q，它會完全使用 1 + q 位元編碼為 (1 << q) - 1；餘數則直接使用 k 位元編碼。第一個數字的商部分會編碼為 0，其餘部分則使用二進位 00101111101001000000000111010；第二個數字的商分部分會編碼為 0111，而餘式部分則是 0011101001010101010101010101010

將這些數字轉換為位元組字串時，會使用簡單的結尾字元。從概念上來說，這可能比較容易想像：從最低重要位元開始形成長位元字串，將第一個數字的商部分放在前面，然後在第一個數字的其餘部分前面加上；然後，我們再加上第二個數字的商式部分，並在後面加上其餘部分。應該會產生下列大量的數量 (為求清楚分行符號和註解)：

001110100010010011110110100011 # Second number, remainder part
0111 # Second number, quotient part
001011111010010000000000111010 # First number, remainder part
0 # First number, quotient part

以單行文字表示

00111010001001001111011010001101110010111110100100000000001110100

這個數字顯然遠超過單一位元組可用的 8 位元。接著，小端的編碼會接受該數字中最少的有效 8 位元，並輸出為第一個位元組，也就是 01110100。為求明確，我們可從最低重要位元開始，將上述位元字串分為 8 組：

0 01110100 01001001 11101101 00011011 10010111 11010010 00000000 01110100

接著，這個小元素編碼會從右側的每個位元組擷取至位元組字串：

01110100
00000000
11010010
10010111
00011011
11101101
01001001
01110100
00000000

您會發現，因為在概念上，新部分會在左側的大數字前「加入」prepend新的部分 (也就是加入較多位元)，但從右側進行編碼 (也就是極少的位元)，因此編碼與解碼能夠以漸進方式執行。

這最終會產生

additions_four_bytes {
  first_value: 489866504
  rice_parameter: 30
  entries_count: 2
  encoded_data: "t\000\322\227\033\355It\000"
}

用戶端只要按照上述步驟反向操作，將雜湊前置字串解碼。與第 4 版不同，由於雜湊前置字元整數被解譯為大端字元，因此在結尾不需要執行位元組交換。

解碼移除索引

移除索引採用的技術和上述 32 位元整數相同。在 v4 和 v5 之間，移除索引的編碼和解碼作業並未變更。

可用清單

下列清單建議在 v5alpha1 中使用：

名單名稱	對應的 v4 ThreatType 列舉	說明
gc	沒有任何通知	這份清單為全域快取清單。這種特殊清單只用於「即時」作業模式。
se	SOCIAL_ENGINEERING	這份清單包含 SOCIAL_ENGINEERING 威脅類型的威脅。
mw	MALWARE	這份清單包含電腦平台的惡意軟體威脅類型威脅。
uws	UNWANTED_SOFTWARE	這份清單包含桌面平台的 UNWANTED_SOFTWARE 威脅類型威脅。
uwsa	UNWANTED_SOFTWARE	這份清單包含 Android 平台的 UNWANTED_SOFTWARE 威脅類型威脅。
pha	POTENTIALLY_HARMFUL_APPLICATION	這份清單包含 Android 平台 POTENTIALLY_HARMFUL_APPLICATION 威脅類型的威脅。

日後還會推出其他清單，屆時將擴大上表。

允許用戶端運作快取 Proxy 伺服器來擷取上述部分或所有清單，然後要求用戶端連線至 Proxy 伺服器。如果實作此方法，建議縮短快取持續時間，例如五分鐘；未來系統可能會使用標準 Cache-Control HTTP 標頭來進行通訊。

更新頻率

用戶端應檢查 minimum_wait_duration 欄位中伺服器傳回的值，並使用該值安排下次更新資料庫的時間。這個值可能為零 (minimum_wait_duration 欄位完全遺漏)，在這種情況下，用戶端「必須」立即執行另一次更新。

要求範例

本節列舉一些直接使用 HTTP API 存取 Google 安全瀏覽的範例。我們通常建議使用產生的語言繫結，因為這種繫結會自動以方便的方式處理編碼和解碼。請參閱該繫結的說明文件。

以下是使用 hashes.search 方法的 HTTP 要求範例：

GET https://safebrowsing.googleapis.com/v5/hashes:search?key=INSERT_YOUR_API_KEY_HERE&hashPrefixes=WwuJdQ

回應主體是通訊協定緩衝區格式的酬載，您隨後可以解碼。

以下是使用 hashLists.batchGet 方法的 HTTP 要求範例：

GET https://safebrowsing.googleapis.com/v5alpha1/hashLists:batchGet?key=INSERT_YOUR_API_KEY_HERE&names=se&names=mw

回應主體同樣是通訊協定緩衝區格式的酬載，您隨後可以解碼。

遷移指南

如果您目前使用的是 v4 Update API，則有從 v4 至 v5 的無縫遷移路徑，無需重設或清除本機資料庫。本節說明此做法。

正在轉換清單更新

在 v4 中，您需要使用 threatListUpdates.fetch 方法下載清單。在第 5 版中，首先會切換為 hashLists.batchGet 方法。

您應對要求進行下列變更：

1. 完全移除 v4 ClientInfo 物件。只要使用已知的 User-Agent 標頭，不用使用專屬欄位提供用戶端的識別資訊。雖然並沒有規定的格式來在此標頭中提供用戶端識別，但我們建議您直接加入原始用戶端 ID 和用戶端版本，並以空格字元或斜線字元分隔。
2. 針對每個 v4 ListUpdateRequest 物件：
   • 查看上表中對應的 v5 清單名稱，並在 v5 要求中提供該名稱。
   • 移除不需要的欄位，例如 threat_entry_type 或 platform_type。
   • 第 4 版中的 state 欄位與第 5 版 versions 欄位直接相容。若是在 v4 中使用 state 欄位傳送至伺服器的同一位元組字串，也可以在 v5 中使用 versions 欄位在 v5 中傳送。
   • 對於 v4 的限制，第 5 版會使用名為 SizeConstraints 的簡化版本。應捨棄 region 等其他欄位。

應對回應進行下列變更：

1. v4 的列舉 ResponseType 只會替換成名為 partial_update 的布林值欄位。
2. minimum_wait_duration 欄位現在可以為零或省略。如果相符，用戶端會要求立即提出其他要求。只有在用戶端在 SizeConstraints 中指定更新大小上限的比資料庫大小上限較小時，才會發生這種情況。
3. 需調整 32 位元整數的 Rice 解碼演算法。差別在於編碼的資料是以不同的句號編碼。在 v4 和 v5 中，32 位元雜湊前置字串會按照字母順序排序。但在 v4 中，這些前置字串在排序時會被視為簡單的結尾，在第 5 版中則在排序時會視為大型結尾。這表示用戶端不需要任何排序，因為字典排序與大終點的數字排序相同。您可以在這裡查看第 4 版 Chromium 的這類實作方法範例。您可以移除這類排序方式。
4. 其他雜湊長度必須實作 Rice 解碼演算法。

轉換雜湊搜尋

在 v4 中，會使用 fullHashes.find 方法取得完整的雜湊。第 5 版中的對等方法是 hashes.search 方法。

您應對要求進行下列變更：

1. 建構程式碼，只傳送長度為 4 個位元組的雜湊前置字串。
2. 完全移除 v4 ClientInfo 物件。只要使用已知的 User-Agent 標頭，不用使用專屬欄位提供用戶端的識別資訊。雖然並沒有規定的格式來在此標頭中提供用戶端識別，但我們建議您直接加入原始用戶端 ID 和用戶端版本，並以空格字元或斜線字元分隔。
3. 移除 client_states 欄位。因為不再需要使用。
4. 不再需要加入 threat_types 和類似欄位。

應對回應進行下列變更：

1. 已移除 minimum_wait_duration 欄位。用戶端隨時可以視需要發出新的要求。
2. v4 ThreatMatch 物件已簡化為 FullHash 物件。
3. 快取已簡化為單一快取持續時間。請參閱上述與快取互動的程序。