Aktualizacja interfejsu Bezpieczne przeglądanie (wersja 4)

Omówienie

Interfejs Update API umożliwia aplikacjom klienckim pobieranie zaszyfrowanych wersji list Safe Browsing do przechowywania w lokalnej bazie danych. Adresy URL można wtedy sprawdzać lokalnie. Tylko wtedy, gdy w lokalnej bazie danych zostanie znalezione dopasowanie, klient musi wysłać żądanie do serwerów Bezpiecznego przeglądania, aby sprawdzić, czy adres URL znajduje się na listach Bezpiecznego przeglądania.

Zanim zaczniesz używać interfejsu Update API, musisz skonfigurować lokalną bazę danych. Bezpieczne przeglądanie zapewnia Pakiet Go, który możesz wykorzystać na początek. Więcej informacji znajdziesz w sekcji Konfiguracja bazy danych w Local Databases (Lokalne bazy danych).

Aktualizowanie lokalnej bazy danych

Aby zawsze być na bieżąco, klienci muszą okresowo aktualizować listy Bezpiecznego przeglądania w w lokalnej bazie danych. Aby oszczędzać przepustowość, klienci pobierają prefiksy szyfrowania adresów URL zamiast samych adresów URL. Jeśli na przykład adres „www.złyurl.com/” znajduje się na liście Bezpieczeństwo w wyszukiwarce, klienci pobierają prefiks szyfrowania SHA256 tego adresu URL zamiast samego adresu URL. W większości przypadków prefiksy skrótów mają długość 4 bajtów, co oznacza, że średni koszt przepustowości podczas pobierania pojedynczego wpisu na liście to 4 bajty przed kompresją.

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, które mają zostać zaktualizowane, oraz różne ograniczenia klienta uwzględniające ograniczenia pamięci i przepustowości.
  • Odpowiedź HTTP POST zwraca pełną lub częściową aktualizację. Odpowiedź może też zwrócić minimalny czas oczekiwania.

Przykład: threatListUpdates.fetch

Żądanie HTTP POST

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

Nagłówek żądania

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

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 wersję) oraz informacje o aktualizacji (element nazwa listy, stan listy i ograniczenia klienta). Więcej informacji: threatListUpdates.fetch treść i wyjaśnienia dostępne na podstawie 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 określać implementację klienta, a nie pojedynczego użytkownika. (Informacje o kliencie są używane w logowaniu po stronie serwera. Możesz wybrać, dowolnej nazwy, ale zalecamy wybranie takiej nazwy, która odzwierciedla rzeczywistą tożsamość takie jak nazwa firmy zapisana jako jedno słowo małymi literami).

listy Bezpiecznego przeglądania,

Pola threatType, platformType i threatEntryType są łączone, aby identyfikować (nazywać) listy Bezpiecznego przeglądania. W tym przykładzie zidentyfikowano jedną listę: MALWARE/WINDOWS/URL. Zanim wyślesz żądanie, sprawdź, czy podane przez Ciebie kombinacje typów są prawidłowe (patrz Listy Bezpiecznego przeglądania).

Stan klienta

Pole state zawiera aktualny stan klienta na liście Bezpiecznego przeglądania. (Stany klienta są zwracane w polu newClientState funkcji odpowiedź threatListUpdates.fetch. W przypadku początkowych aktualizacji pozostaw pole state puste.

Ograniczenia dotyczące rozmiaru

Pole maxUpdateEntries określa łączną liczbę aktualizacji, którymi klient może zarządzać (w tym przykładzie 2048). Pole maxDatabaseEntries określa łączną liczbę wpisów lokalnych może zarządzać bazą danych (w tym przykładzie będzie to 4096). Klienci powinni ustawiać ograniczenia dotyczące rozmiaru aby chronić ograniczenia pamięci i przepustowości oraz i rozwoju działalności. Aby dowiedzieć się więcej, (zobacz Aktualizowanie ograniczeń).

Obsługiwane kompresje

Pole supportedCompressions zawiera listę typów kompresji obsługiwanych przez klienta. W Przykład: 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 Bezpiecznego przeglądania z użyciem parametru wybranego typu kompresji.

Nagłówek odpowiedzi

Nagłówek odpowiedzi zawiera kod stanu HTTP oraz typ treści. Klienci, którzy otrzymują kod stanu inny niż HTTP/200, muszą przejść w tryb wycofania (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, dodania i usunięcia informacji, które mają być zastosowane do lokalnej bazy danych, stan i sumę kontrolną). W tym przykładzie odpowiedź zawiera też minimalny czas oczekiwania. Więcej , zapoznaj się z treść odpowiedzi threatListUpdates.fetch i wyjaśnienia dostępne na podstawie 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 aktualizację częściową lub pełną. W tym przykładzie aktualizacja częściowa więc odpowiedź obejmuje zarówno dodanie, jak i usunięcie. Może być wiele zbiorów dodania, ale tylko jeden zestaw usunięć (zobacz Aktualizacje bazy danych).

Nowy stan klienta

Pole newClientState zawiera nowy stan klienta dla nowo zaktualizowanej listy Bezpiecznego przeglądania. Klienci muszą zapisać nowy stan klienta na potrzeby kolejnych żądań aktualizacji (pole state w żądaniu threatListUpdates.fetch lub pole clientStates w żądaniu fullHashes.find).

Sumy kontrolne

Suma kontrolna umożliwia klientom sprawdzenie, czy nie doszło do uszkodzenia lokalnej bazy danych. Jeśli sumy kontrolne nie są zgodne, klient musi wyczyścić bazę danych i ponownie wydać aktualizację z pustym polem state. W takim przypadku klienci muszą jednak przestrzegać interwałów czasowych dotyczących 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 okres oczekiwania może nie być uwzględniony w (patrz Częstotliwość żądań).

Sprawdzanie adresów URL

Aby sprawdzić, czy adres URL znajduje się na liście Bezpiecznego przeglądania, klient musi najpierw obliczyć ciąg znaków i prefiks adresu URL (patrz Adresy URL i łańcuchy znaków). Klient wysyła zapytanie do lokalnej bazy danych, by sprawdzić, czy istnieje dopasowanie. Jeśli prefiks skrótu to nie występuje w lokalnej bazie danych, oznacza to, że adres URL jest uznawany za bezpieczny (nie znajduje się podczas przeglądania list).

Jeśli prefiks skrótu jest obecny w lokalnej bazie danych (kolizja prefiksów skrótu), klient musi wysłać prefiks skrótu do serwerów Bezpiecznego przeglądania w celu weryfikacji. Serwery zwracają wszystkie pełne identyfikatory SHA-256, które zawierają podany prefiks. Jeśli jeden z tych haszów pełnej długości pasuje do pełnej długości skrótu odpowiedniego adresu URL, adres URL jest uznawany za niebezpieczny. Jeśli żaden z haszy pełnej długości nie odpowiada haszowi pełnej długości adres URL danego adresu URL, jest on uważany za bezpieczny.

Google nie dowiaduje się niczego o adresach URL, które sprawdzasz. Google uczy się prefiksów adresów URL zaszyfrowanych za pomocą funkcji skrótu haszowego, ale prefiksy te nie zawierają zbyt wielu informacji o rzeczywistych adresach URL.

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

  • Żądanie HTTP POST może zawierać do 500 wpisów o zagrożeniach.
  • Żądanie HTTP POST zawiera prefiksy haszowania adresów URL, które mają zostać sprawdzone. Klienci są zachęcano do zgrupowania wielu wpisów dotyczących zagrożeń w 1 żądaniu w celu zmniejszenia wykorzystania przepustowości.
  • Odpowiedź HTTP POST zwraca pasujące pełnowymiarowe hasze wraz z czasem trwania pamięci podręcznej z dodatnim i ujemnym czasem trwania. Odpowiedź może też zwracać minimalny czas oczekiwania.

Przykład: pełneHasze.find

Żądanie HTTP POST

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

Nagłówek żądania

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

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żeniach (nazwy list i prefiksy haszowane). W przypadku żądań JSON prefiksy skrótu muszą musi być zakodowana w formacie base64. Więcej informacji: fullHashes.find treść żądania i wyjaśnienia dostępne na podstawie przykładowego kodu.

{
  "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 określać implementację klienta, a nie pojedynczego użytkownika. (informacje o kliencie są używane w logach po stronie serwera. Możesz wybrać dowolną nazwę dla klienta, ale zalecamy wybranie nazwy reprezentującej prawdziwą tożsamość klienta, taką jak nazwa firmy zapisana jako jedno słowo, małymi literami).

Wszystkie stany klienta

Pole clientStates zawiera stany klienta wszystkich list Bezpiecznego przeglądania w: do lokalnej bazy danych klienta. (Stany klienta są zwracane w polu newClientState funkcji odpowiedź threatListUpdates.fetch.

listy Bezpiecznego przeglądania,

Pola threatTypes, platformTypes i threatEntryTypes służą do identyfikacji (nazywania) list Bezpiecznego przeglądania. W tym przykładzie zidentyfikowano 2 listy: MALWARE/WINDOWS/URL i SOCIAL_ENGINEERING/WINDOWS/URL. Przed wysłaniem prośby upewnij się, że kombinacje typów określone wartości są prawidłowe (patrz Listy Bezpiecznego przeglądania).

Prefiksy haszy zagrożeń

Tablica threatEntries zawiera prefiksy skrótu adresów URL, które mają być sprawdzane. Pole hash musi zawierać dokładnie ten prefiks skrótu, który istnieje w lokalnej bazie danych. Jeśli na przykład lokalny prefiks haszowania ma długość 4 bajtów, wpis dotyczący zagrożenia musi mieć długość 4 bajtów. Jeśli Lokalny prefiks skrótu został wydłużony do 7 bajtów, a następnie wpis zagrożenia musi mieć 7 bajtów.

W tym przykładzie żądanie zawiera 3 prefiksy skrótu. Zostaną porównane wszystkie 3 prefiksy względem każdej z list Bezpiecznego przeglądania w celu określenia, czy istnieje pasujący pełnej długości hash.

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

Odpowiedź HTTP POST

W tym przykładzie odpowiedź zwraca pasujące dane uporządkowane według listy Bezpiecznego przeglądania wraz z czasem trwania buforowania i czasu oczekiwania.

Nagłówek odpowiedzi

Nagłówek odpowiedzi zawiera kod stanu HTTP. oraz typu treści. Klienty, którzy otrzymają kod stanu inny niż HTTP/200, muszą się cofnąć (zobacz 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, metadanych (jeśli są dostępne) i czasach przechowywania w pamięci podręcznej). W tym przykładzie treść odpowiedzi zawiera też minimalny czas oczekiwania. Więcej informacji: treść odpowiedzi fullHashes.find i wyjaśnienia dostępne na podstawie przykładowego kodu.

{
  "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"
}
Dopasowania

Obiekt Matches zwraca pasujący do pełnej długości hasz dla 2 prefików haszowanych. Adresy URL odpowiadające tym haszom są uważane za niebezpieczne. Nie znaleziono dopasowania dla trzeciego prefiksu skrótu, więc nic nie zostanie zwrócone. adres URL odpowiadający temu prefiksowi skrótu jest uważany za bezpieczny.

Zwróć uwagę, że w tym przykładzie jeden pełny ciąg znaków odpowiada jednemu prefiksowi hasha, ale może istnieć wiele pełnych ciągów znaków, które odpowiadają temu samemu prefiksowi hasha.

Metadane

Pole threatEntryMetadata jest opcjonalne i zawiera dodatkowe informacje o zagrożeniu dopasowania. Obecnie metadane są dostępne na liście adresów URL, złośliwego oprogramowania i systemów operacyjnych w Bezpiecznym przeglądaniu (patrz Metadane).

Czasy trwania buforowania

Pola cacheDuration i negativeCacheDuration wskazują, przez jaki czas hasze muszą być uważane za niebezpieczne lub bezpieczne (patrz Przyspieszanie).

Minimalny czas oczekiwania

Pole minimumWaitDuration wskazuje, że klient musi poczekać 300 sekund (5 minut) na wysyłanie kolejnego żądania fullHashes. Pamiętaj, że odpowiedź może, ale nie musi zawierać okresu oczekiwania (patrz Częstotliwość żądań).