Aktualizacja interfejsu Bezpieczne przeglądanie (wersja 4)

Opis

Interfejs Update API umożliwia aplikacjom klienckim pobieranie zaszyfrowanych wersji list Bezpiecznego przeglądania na potrzeby przechowywania ich w lokalnej bazie danych. Adresy URL można wtedy sprawdzać lokalnie. Dopiero po znalezieniu dopasowania w lokalnej bazie danych klient musi wysłać żądanie do serwerów Bezpiecznego przeglądania, aby sprawdzić, czy dany URL znajduje się na listach Bezpiecznego przeglądania.

Zanim użyjesz interfejsu Update API, musisz skonfigurować lokalną bazę danych. Bezpieczne przeglądanie udostępnia pakiet Go, którego możesz użyć na początku. Więcej informacji znajdziesz w sekcji Konfiguracja bazy danych w sekcji Lokalne bazy danych.

Aktualizowanie lokalnej bazy danych

Aby być na bieżąco, klienci muszą okresowo aktualizować listy Bezpiecznego przeglądania w lokalnej bazie danych. Aby oszczędzać przepustowość, klienci pobierają prefiksy skrótów adresów URL zamiast nieprzetworzonych adresów URL. Jeśli na przykład na liście Bezpiecznego przeglądania znajduje się ciąg „www.badurl.com/”, klient pobiera prefiks skrótu SHA256 tego adresu URL, a nie sam adres URL. W większości przypadków prefiksy skrótów mają 4 bajty, co oznacza, że średni koszt przepustowości pobierania jednej pozycji na liście wynosi 4 bajty przed skompresowaniem.

Aby zaktualizować listy Bezpiecznego przeglądania w lokalnej bazie danych, wyślij żądanie HTTP POST do metody threatListUpdates.fetch:

  • Żądanie HTTP POST zawiera nazwy list do zaktualizowania oraz różne ograniczenia klienta, aby uwzględnić ograniczenia pamięci i przepustowości.
  • Odpowiedź HTTP POST zwraca pełną lub częściową aktualizację. Odpowiedź może też zwracać minimalny czas oczekiwania.

Przykład: threatListUpdates.fetch

Żądanie POST HTTP

W poniższym przykładzie żądane są aktualizacje pojedynczej listy Bezpiecznego przeglądania.

Nagłówek żądania

Nagłówek żądania zawiera adres URL żądania i typ treści. Pamiętaj, aby zastąpić klucz interfejsu API w adresie URL fragmentem API_KEY.

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1
Content-Type: application/json

Treść żądania

Treść żądania zawiera informacje o kliencie (identyfikator i wersja) oraz informacje o aktualizacji (nazwę listy, stan listy i ograniczenia dotyczące klienta). Więcej informacji znajdziesz w treści żądania o threatListUpdates.fetch oraz w objaśnieniach za pomocą przykładowego kodu.

{
  "client": {
    "clientId":       "yourcompanyname",
    "clientVersion":  "1.5.2"
  },
  "listUpdateRequests": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "state":           "Gg4IBBADIgYQgBAiAQEoAQ==",
    "constraints": {
      "maxUpdateEntries":      2048,
      "maxDatabaseEntries":    4096,
      "region":                "US",
      "supportedCompressions": ["RAW"]
    }
  }]
}
Informacje o kliencie

Pola clientID i clientVersion powinny jednoznacznie identyfikować implementację klienta, a nie użytkownika. Informacje o kliencie są używane do logowania po stronie serwera. Możesz wybrać dowolną nazwę identyfikatora klienta, ale zalecamy użycie nazwy reprezentującej prawdziwą tożsamość klienta, np. nazwę firmy, przedstawione w postaci jednego słowa, małymi literami).

Listy Bezpiecznego przeglądania

Pola threatType, platformType i threatEntryType są połączone, aby zidentyfikować (nazwa) listy Bezpiecznego przeglądania. W tym przykładzie identyfikujemy jedną listę: ZŁOŚLIWE OPROGRAMOWANIE/WINDOWS/URL. Przed wysłaniem żądania upewnij się, że wybrane kombinacje typów są prawidłowe (patrz Listy Bezpiecznego przeglądania).

Stan klienta

Pole state zawiera bieżący stan klienta listy Bezpieczne przeglądanie. (Stany klienta są zwracane w polu newClientState odpowiedzi threatListUpdates.fetch). Aby przeprowadzić wstępną aktualizację, pozostaw pole state puste.

Ograniczenia rozmiaru

Pole maxUpdateEntries określa łączną liczbę aktualizacji, którymi może zarządzać klient (w tym przykładzie jest to 2048). Pole maxDatabaseEntries określa łączną liczbę wpisów, którymi może zarządzać lokalna baza danych (w tym przykładzie jest to 4096). Klienty powinny ustawiać ograniczenia rozmiaru, aby chronić pamięć oraz przepustowość i uchronić się przed wzrostem liczby list. Aby dowiedzieć się więcej, (zobacz Aktualizowanie ograniczeń).

Obsługiwane kompresje

W polu supportedCompressions wymienione są typy kompresji obsługiwane przez klienta. W tym przykładzie klient obsługuje tylko nieprzetworzone, nieskompresowane dane. Bezpieczne przeglądanie obsługuje jednak dodatkowe typy kompresji (patrz Kompresja).

Odpowiedź HTTP POST

W tym przykładzie odpowiedź zwraca częściową aktualizację listy Bezpieczne przeglądanie korzystające z żądanego typu kompresji.

Nagłówek odpowiedzi

Nagłówek odpowiedzi zawiera kod stanu HTTP i typ treści. Klienci, którzy otrzymują kod stanu inny niż HTTP/200, muszą przejść w tryb wycofywania (patrz Częstotliwość żądań).

HTTP/1.1 200 OK
Content-Type: application/json

Treść odpowiedzi

Treść odpowiedzi zawiera informacje o aktualizacji (nazwę listy, typ odpowiedzi, dodane i usunięte elementy, które mają zostać zastosowane do lokalnej bazy danych, nowy stan klienta oraz sumę kontrolną). W tym przykładzie odpowiedź zawiera też minimalny czas oczekiwania. Więcej informacji znajdziesz w treści odpowiedzi związanej z threatListUpdates.fetch oraz w objaśnieniach za pomocą przykładowego kodu.

{
  "listUpdateResponses": [{
    "threatType":      "MALWARE",
    "threatEntryType": "URL",
    "platformType":    "WINDOWS",
    "responseType" :   "PARTIAL_UPDATE",
    "additions": [{
      "compressionType": "RAW",
      "rawHashes": {
        "prefixSize": 4,
        "rawHashes":  "rnGLoQ=="
      }
    }],
    "removals": [{
      "compressionType": "RAW",
      "rawIndices": {
        "indices": [0, 2, 4]
      }
    }],
    "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
    "checksum": {
      "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
    }
  }],
  "minimumWaitDuration": "593.440s"
}
Aktualizacje bazy danych

Pole responseType wskazuje częściową lub pełną aktualizację. W tym przykładzie zwracana jest częściowa aktualizacja, więc odpowiedź obejmuje zarówno dodanie, jak i usunięcie. Może być wiele zestawów zmian, ale tylko 1 zestaw usunięć (patrz Aktualizacje bazy danych).

Nowy stan klienta

Pole newClientState zawiera nowy stan klienta dla niedawno zaktualizowanej listy Bezpieczne przeglądanie. Klienty muszą zapisać nowy stan klienta na potrzeby kolejnych żądań aktualizacji (pole state w żądaniu threatListUpdates.fetch lub clientStates w fullHashes.find żądaniach).

Sumy kontrolne

Suma kontrolna umożliwia klientom sprawdzenie, czy lokalna baza danych nie uległa uszkodzeniu. Jeśli suma kontrolna się nie zgadza, klient musi wyczyścić bazę danych i ponownie wykonać aktualizację z pustym polem state. W tej sytuacji klienci muszą jednak nadal przestrzegać przedziałów czasowych aktualizacji (patrz Częstotliwość żądań).

Minimalny czas oczekiwania

Pole minimumWaitDuration wskazuje, że klient musi odczekać 593,44 sekundy (9,89 minuty) przed wysłaniem kolejnego żądania aktualizacji. Pamiętaj, że w odpowiedzi może zostać uwzględniony okres oczekiwania (patrz Częstotliwość żądań).

Sprawdzam adresy URL

Aby sprawdzić, czy adres URL znajduje się na liście Bezpiecznego przeglądania, klient musi najpierw obliczyć prefiks i hashtagu adresu URL (patrz Adresy URL i haszowanie). Klient wysyła zapytanie do lokalnej bazy danych, aby sprawdzić, czy występuje dopasowanie. Jeśli w lokalnej bazie danych nie ma prefiksu skrótu, adres URL jest uznawany za bezpieczny (nie ma go na listach Bezpiecznego przeglądania).

Jeśli prefiks skrótu jest obecny w lokalnej bazie danych (konflikt prefiksów), klient musi wysłać go do serwerów Bezpiecznego przeglądania w celu weryfikacji. Serwery zwracają wszystkie skróty SHA256 pełnej długości zawierające podany prefiks skrótu. Jeśli jeden z tych haszów pełnej długości odpowiada haszu pełnej długości adresu URL, którego dotyczy zgłoszenie, adres URL jest uznawany za niebezpieczny. Jeśli żaden z skrótów pełnej długości nie odpowiada haszu pełnej długości adresu URL, którego dotyczy zgłoszenie, adres URL jest uznawany za bezpieczny.

W żadnym momencie Google nie uzyskuje informacji o sprawdzanych przez Ciebie adresach URL. Google rozpoznaje prefiksy skrótów adresów URL, ale nie zapewniają one wielu informacji o rzeczywistych adresach URL.

Aby sprawdzić, czy adres URL znajduje się na liście Bezpiecznego przeglądania, wyślij żądanie HTTP POST za pomocą metody fullHashes.find:

  • Żądanie HTTP POST może zawierać do 500 pozycji o zagrożeniu.
  • Żądanie HTTP POST zawiera prefiksy skrótu adresów URL do sprawdzenia. Zachęcamy klientów do grupowania wielu wpisów o zagrożeniach w jednym żądaniu w celu zmniejszenia wykorzystania przepustowości.
  • Odpowiedź HTTP POST zwraca pasujące hasze pełnej długości oraz dodatnie i ujemne wartości czasu trwania pamięci podręcznej. Odpowiedź może też zwracać minimalny czas oczekiwania.

Przykład: pełneHashes.find

Żądanie POST HTTP

W poniższym przykładzie nazwy 2 list Bezpiecznego przeglądania i 3 prefiksy skrótu są wysyłane do porównania i weryfikacji.

Nagłówek żądania

Nagłówek żądania zawiera adres URL żądania i typ treści. Pamiętaj, aby zastąpić klucz interfejsu API ciągiem API_KEY w adresie URL.

POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1
Content-Type: application/json

Treść żądania

Treść żądania zawiera informacje o kliencie (identyfikator i wersja), stany klienta oraz informacje o zagrożeniu (nazwy list i prefiksy skrótu). W przypadku żądań JSON prefiksy skrótu muszą być wysyłane w postaci zakodowanej w formacie base64. Więcej informacji znajdziesz w treści żądania fullHashes.find oraz w wyjaśnieniach po przykładowym kodzie.

{
  "client": {
    "clientId":      "yourcompanyname",
    "clientVersion": "1.5.2"
  },
  "clientStates": [
    "ChAIARABGAEiAzAwMSiAEDABEAE=",
    "ChAIAhABGAEiAzAwMSiAEDABEOgH"
  ],
  "threatInfo": {
    "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes":    ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"hash": "WwuJdQ=="},
      {"hash": "771MOg=="},
      {"hash": "5eOrwQ=="}
    ]
  }
}
Informacje o kliencie

Pola clientID i clientVersion powinny jednoznacznie identyfikować implementację klienta, a nie użytkownika. Informacje o kliencie są używane do logowania po stronie serwera. Możesz wybrać dowolną nazwę identyfikatora klienta, ale zalecamy wybranie nazwy reprezentującej prawdziwą tożsamość klienta, np. nazwę firmy, przedstawione w postaci jednego słowa, małymi literami).

Wszystkie stany klientów

Pole clientStates zawiera stany klienta wszystkich list Bezpiecznego przeglądania w lokalnej bazie danych klienta. (Stany klienta są zwracane w polu newClientState odpowiedzi threatListUpdates.fetch).

Listy Bezpiecznego przeglądania

Pola threatTypes, platformTypes i threatEntryTypes łączą się, aby zidentyfikować (nazwa) listy Bezpiecznego przeglądania. W tym przykładzie zidentyfikowano 2 listy: ZŁOŚLIWE/WINDOWS/URL i SOCIAL_ENGINEERING/WINDOWS/URL. Przed wysłaniem żądania upewnij się, że określone kombinacje typów są prawidłowe (patrz Listy Bezpiecznego przeglądania).

Prefiksy skrótu zagrożenia

Tablica threatEntries zawiera prefiksy skrótów adresów URL, które chcesz sprawdzić. Pole hash musi zawierać dokładnie taki prefiks skrótu, który występuje w lokalnej bazie danych. Jeśli na przykład lokalny prefiks skrótu ma 4 bajty, wpis o zagrożeniu musi mieć 4 bajty. Jeśli prefiks lokalnego skrótu został wydłużony do 7 bajtów, wpis o zagrożeniu musi mieć 7 bajtów.

W przykładzie żądanie zawiera 3 prefiksy skrótu. Wszystkie 3 prefiksy są porównywane z każdą listą Bezpiecznego przeglądania w celu określenia, czy istnieje zgodny hasz o pełnej długości.

Uwaga: interfejs Update API i metoda fullHashes.find powinny zawsze używać pola hash, a nie pola URL (patrz ThreatEntry).

Odpowiedź HTTP POST

W poniższym przykładzie odpowiedź zwraca pasujące dane uporządkowane według listy Bezpiecznego przeglądania, wraz z pamięci podręcznej i czasem oczekiwania.

Nagłówek odpowiedzi

Nagłówek odpowiedzi zawiera kod stanu HTTP i typ treści. Klienty, które otrzymają kod stanu inny niż HTTP/200, muszą się wycofać (patrz Częstotliwość żądań).

HTTP/1.1 200 OK
Content-Type: application/json

Treść odpowiedzi

Treść odpowiedzi zawiera informacje o dopasowaniu (nazwy list i skróty o pełnej długości, metadane (jeśli są dostępne) oraz czasy trwania pamięci podręcznej). W tym przykładzie treść odpowiedzi zawiera też minimalny czas oczekiwania. Więcej informacji znajdziesz w treści odpowiedzi fullHashes.find oraz w wyjaśnieniach po przykładowym kodzie.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
    },
    "threatEntryMetadata": {
      "entries": [{
        "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==",  // base64-encoded "malware_threat_type"
        "value": "TEFORElORw=="  // base64-encoded "LANDING"
       }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "SOCIAL_ENGINEERING",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
    },
    "threatEntryMetadata": {
      "entries": []
    },
    "cacheDuration": "300.000s"
  }],
  "minimumWaitDuration": "300.000s",
  "negativeCacheDuration": "300.000s"
}
Odpowiada

Obiekt Dopasowania zwraca pasujący hasz o pełnej długości dla 2 prefiksów haszowania. Adresy URL odpowiadające tym haszom są uznawane za niebezpieczne. Nie znaleziono dopasowania dla trzeciego prefiksu skrótu, więc nie jest zwracany wynik. Adres URL odpowiadający temu prefiksowi skrótu jest uznawany za bezpieczny.

Zwróć uwagę, że w tym przykładzie 1 skrót o pełnej długości odpowiada 1 prefiksowi skrótu. Może jednak istnieć wiele pełnych haszów mapowanych na ten sam prefiks.

Metadane

Pole threatEntryMetadata jest opcjonalne i zawiera dodatkowe informacje o dopasowaniu zagrożeń. Obecnie metadane są dostępne w przypadku listy Bezpieczne przeglądanie dotyczące MALWARE/WINDOWS/URL-a (patrz Metadane).

Czasy trwania pamięci podręcznej

Pola cacheDuration i negativeCacheDuration wskazują, przez jaki czas hasze muszą zostać uznane za niebezpieczne lub bezpieczne (patrz Zapisywanie w pamięci podręcznej).

Minimalny czas oczekiwania

Pole minimumWaitDuration wskazuje, że klient musi odczekać 300 sekund (5 minut), zanim wyśle kolejne żądanie fullHashes. Pamiętaj, że okres oczekiwania może, ale nie musi być uwzględniony w odpowiedzi (patrz Częstotliwość żądań).