Overview

注意：本說明文件目前仍在開發中。我們預計近期內會改善這項功能。

Google 安全瀏覽第 5 版是 Google 安全瀏覽第 4 版的進階版。在第 5 版中，我們做出了兩項重大變更，分別是資料新鮮度和 IP 位址隱私權。此外，我們也改善了 API 介面，提升彈性、效率，並減少膨脹情形。此外，Google 安全瀏覽第 5 版的設計可讓您輕鬆從第 4 版遷移。

目前 Google 提供 v4 和 v5，兩者都已可正式使用。您可以使用 v4 或 v5。我們尚未宣布 v4 版本的停用日期，如果有相關消息，我們會提前至少一年通知。本頁面將說明 v5 以及從 v4 遷移至 v5 的指南；完整的 v4 說明文件仍可取得。

資料更新間隔

在 v5 中，我們推出了「即時防護」模式。這可避免上述資料過時的問題。在 v4 中，用戶端應下載並維護本機資料庫，針對本機下載的威脅清單執行檢查，然後在部分前置字元相符時，執行要求來下載完整雜湊。在 v5 中，雖然用戶端應繼續下載並維護威脅清單的本機資料庫，但現在也應下載可能屬於良性網站的清單 (稱為全球快取)，並對此全球快取和本機威脅清單執行本機檢查，最後，如果全球快取中存在部分前置字元相符的威脅清單，或完全不相符，則執行要求來下載完整雜湊。(如要進一步瞭解客戶端所需的本機處理作業，請參閱下方提供的程序)。這代表從預設允許改為預設檢查，可因應網路上威脅傳播速度加快的情況，提升防護力。換句話說，這個通訊協定旨在提供近乎即時的保護：我們希望讓客戶能運用最新的 Google 安全瀏覽資料。

IP 隱私權

Google 安全瀏覽 (第 4 版或第 5 版) 在提供要求的過程中，不會處理任何與使用者身分相關的內容。如果傳送 Cookie，系統會略過。Google 會知道要求的原始 IP 位址，但只會將 IP 位址用於必要的網路需求 (例如傳送回應) 和防範拒絕服務攻擊。

我們會在第 5 版同時推出 Safe Browsing Oblivious HTTP Gateway API 這項伴隨 API。這項功能會使用 Oblivious HTTP 隱藏 Google 的使用者 IP 位址。這項功能會讓非共謀的第三方處理使用者要求的加密版本，然後轉寄給 Google。因此，第三方只能存取 IP 位址，Google 只能存取要求內容。第三方會運作 Oblivious HTTP Relay (例如 Fastly 提供的這項服務)，而 Google 則會運作 Oblivious HTTP Gateway。這是選用的隨播廣告 API。與 Google 安全瀏覽服務搭配使用時，系統就不會再將使用者的 IP 位址傳送給 Google。

運作模式

Google 安全瀏覽 v5 可讓用戶端選擇三種運作模式。

即時模式

當用戶端選擇以即時模式使用 Google Safe Browsing v5 時，用戶端會在本機資料庫中維護以下項目：(i) 可能屬於良性網站的全球快取，其格式為主機代碼/路徑前置字串網址運算式的 SHA256 雜湊值；(ii) 一組威脅清單，其格式為主機代碼/路徑前置字串網址運算式的 SHA256 雜湊前置字串。大致來說，只要用戶端想要檢查特定網址，就會使用全域快取執行本機檢查。如果檢查通過，系統就會執行本機威脅清單檢查。否則，用戶端會繼續進行即時雜湊檢查，詳情請參閱下文。

除了本機資料庫之外，用戶端也會維護本機快取。這種本機快取不需要儲存在永久性儲存空間中，而且在記憶體壓力下可能會清除。

以下提供詳細的程序規格。

本機清單模式

當用戶端選擇在這個模式下使用 Google Safe Browsing v5 時，用戶端行為與 v4 Update API 類似，只是會使用 v5 的改善版 API 介面。客戶會在本機資料庫中維護一組威脅清單，格式為主機後置字串/路徑前置字串網址運算式的 SHA256 雜湊前置字串。只要用戶端想要檢查特定網址，就會使用本機威脅清單執行檢查。只有在比對相符的情況下，用戶端才會連線至伺服器，繼續進行檢查。

如同上述，用戶端也會維護本機快取，但不必儲存在永久性儲存空間中。

無儲存空間即時模式

如果用戶端選擇在無儲存空間的即時模式下使用 Google 安全瀏覽 v5，就不需要維護任何持續性本機資料庫。不過，用戶端仍應保留本機快取。這種本機快取不需要儲存在永久性儲存空間中，而且在記憶體壓力下可能會清除。

只要用戶端想要檢查特定網址，就會一律連線至伺服器執行檢查。這個模式與 v4 Lookup API 的用戶端可能實作的模式類似。

與即時模式相比，此模式可能會使用更多網路頻寬，但如果用戶端不便維護持續性本機狀態，則可能更適合使用此模式。

即時網址檢查程序

當用戶端選擇即時運作模式時，就會使用這個程序。

這個程序會使用單一網址 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 安全瀏覽 v5 伺服器。如果發生錯誤 (包括網路錯誤、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 安全瀏覽 v5 伺服器。如果發生錯誤 (包括網路錯誤、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 安全瀏覽 v5 伺服器。如果發生錯誤 (包括網路錯誤、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 中的雜湊字首。

要求範例

本節將列舉幾個直接使用 HTTP API 存取 Google Safe Browsing 的範例。一般來說，建議您使用產生的語言繫結，因為這樣系統會以方便的方式自動處理編碼和解碼作業。請參閱該繫結的說明文件。

以下是使用 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-4b

回應主體再次是通訊協定緩衝區格式的酬載，您可以對其進行解碼。