Overview

Uwaga: ta dokumentacja jest obecnie w trakcie tworzenia. W najbliższej przyszłości wprowadzimy ulepszenia.

Bezpieczne przeglądanie Google w wersji 5 jest rozwinięciem wersji 4. Dwie główne zmiany w wersji 5 to aktualność danych i prywatność adresów IP. Ponadto interfejs API został ulepszony, aby zwiększyć elastyczność i wydajność oraz ograniczyć nadmierne rozrostanie. Ponadto Bezpieczne przeglądanie w wersji 5 zostało zaprojektowane tak, aby ułatwić migrację z wersji 4.

Obecnie Google oferuje wersję 4 i 5, a obie są gotowe do wdrożenia w wersji produkcyjnej. Możesz użyć wersji 4 lub 5. Nie ogłosiliśmy jeszcze daty wycofania wersji 4. Jeśli to zrobimy, powiadomimy Cię z co najmniej rocznym wyprzedzeniem. Na tej stronie znajdziesz opis wersji 5 oraz przewodnik po migracji z wersji 4 na 5. Cała dokumentacja wersji 4 pozostaje dostępna.

Aktualność danych

W wersji 5 wprowadzamy tryb działania zwany ochroną w czasie rzeczywistym. Dzięki temu można uniknąć problemu ze starymi danymi. W wersji 4 klienci muszą pobierać i utrzymywać lokalną bazę danych, przeprowadzać kontrole na podstawie pobranych lokalnie list zagrożeń, a następnie, gdy występuje częściowe dopasowanie prefiksu, wysyłać żądanie pobierania pełnego hasha. W wersji 5 klienci nadal powinni pobierać i utrzymywać lokalną bazę danych z listami zagrożeń, ale teraz muszą też pobrać listę witryn, które prawdopodobnie są nieszkodliwe (tzw. globalny bufor), przeprowadzić lokalną kontrolę tego globalnego bufora oraz lokalną kontrolę listy zagrożeń. Jeśli w globalnym buforze nie ma dopasowania lub jest ono częściowe, klient powinien wysłać żądanie pobierania pełnych haszy. (Szczegóły dotyczące lokalnego przetwarzania danych wymaganego przez klienta znajdziesz w procedurze poniżej). Oznacza to przejście z domyślnego zezwolenia na domyślne sprawdzanie, co może zwiększyć poziom ochrony w świetle szybszego rozprzestrzeniania się zagrożeń w internecie. Inaczej mówiąc, jest to protokół, który ma zapewniać ochronę w czasie zbliżonym do rzeczywistego. Chcemy, aby klienci mogli korzystać z najświeższych danych Bezpiecznego przeglądania Google.

Prywatność adresu IP

Bezpieczne przeglądanie Google (w wersji 4 lub 5) nie przetwarza podczas obsługi żądań żadnych informacji powiązanych z tożsamością użytkownika. Pliki cookie, jeśli zostały wysłane, są ignorowane. Google zna adresy IP, z których pochodzą żądania, ale używa ich tylko do obsługi sieci (np. do wysyłania odpowiedzi) i do ochrony przed atakami typu DoS.

Wraz z wersją 5 wprowadzamy dodatkowy interfejs API o nazwie Bezpieczne przeglądanie – Oblivious HTTP Gateway API. Używa on protokołu HTTP Oblivious, aby ukryć adresy IP użytkowników przed Google. Polega ona na tym, że firma zewnętrzna, która nie jest zaangażowana w zmowy, przetwarza zaszyfrowaną wersję żądania użytkownika, a potem przekazuje ją do Google. Oznacza to, że aplikacja innej firmy ma dostęp tylko do adresów IP, a Google ma dostęp tylko do treści żądania. Usługa zewnętrzna obsługuje Oblivious HTTP Relay (np. tę usługę firmy Fastly), a Google obsługuje Oblivious HTTP Gateway. To opcjonalny interfejs API towarzyszący. Gdy jest używany w połączeniu z Bezpiecznym przeglądaniem Google, adresy IP użytkowników nie są już wysyłane do Google.

Tryby działania

Bezpieczne przeglądanie Google w wersji 5 umożliwia klientom wybór 1 z 3 trybów działania.

Tryb Czas rzeczywisty

Gdy klienci zdecydują się używać Bezpiecznego wyszukiwania Google w wersji 5 w czasie rzeczywistym, będą utrzymywać w swojej bazie danych lokalnej: (i) globalny bufor witryn prawdopodobnie nieszkodliwych w formacie haszy SHA256 wyrażeń URL host-suffix/path-prefix, (ii) zbiór list zagrożeń w formacie prefiksów haszy SHA256 wyrażeń URL host-suffix/path-prefix. Ogólnie rzecz biorąc, gdy klient chce sprawdzić konkretny adres URL, przeprowadza lokalną weryfikację za pomocą globalnego pamięci podręcznej. Jeśli to sprawdzenie się powiedzie, przeprowadzane jest sprawdzenie na podstawie lokalnych list zagrożeń. W przeciwnym razie klient kontynuuje sprawdzanie wartości skrótu w czasie rzeczywistym, jak opisano poniżej.

Oprócz lokalnej bazy danych klient będzie utrzymywać lokalny bufor. Taki lokalny bufor nie musi być w trwałym miejscu na dane i może zostać wyczyszczony w przypadku braku pamięci.

Szczegółowe informacje o tej procedurze znajdziesz poniżej.

Tryb listy lokalnej

Gdy klienci zdecydują się używać w tym trybie interfejsu Google Safe Browsing w wersji 5, ich zachowanie będzie podobne do zachowania interfejsu Update API w wersji 4, ale z użyciem ulepszonej wersji interfejsu API w wersji 5. Klienci będą przechowywać w swojej lokalnej bazie danych zestaw list zagrożeń w formacie prefiksów szyfrowania SHA256 wyrażeń URL host-suffix/path-prefix. Gdy klient chce sprawdzić konkretny adres URL, sprawdzanie jest wykonywane przy użyciu lokalnej listy zagrożeń. Jeśli i tylko jeśli występuje dopasowanie, klient łączy się z serwerem, aby kontynuować sprawdzanie.

Podobnie jak w przypadku wyżej, klient będzie też utrzymywać lokalną pamięć podręczną, która nie musi znajdować się w trwałej pamięci masowej.

Tryb w czasie rzeczywistym bez pamięci

Jeśli klienci zdecydują się korzystać z Google Bezpieczne przeglądanie w wersji 5 w trybie czasu rzeczywistego bez przechowywania danych, nie muszą utrzymywać trwałej bazy danych lokalnej. Klient musi jednak utrzymywać lokalny bufor. Taki lokalny bufor nie musi być przechowywany w trwałym miejscu na dane i może zostać usunięty w przypadku braku pamięci.

Gdy klient chce sprawdzić konkretny adres URL, zawsze łączy się z serwerem, aby przeprowadzić sprawdzenie. Ten tryb jest podobny do tego, który mogą stosować klienci interfejsu Lookup API w wersji 4.

W porównaniu z trybem w czasie rzeczywistym może on zużywać więcej przepustowości sieci, ale może być bardziej odpowiedni, jeśli utrzymanie trwałego stanu lokalnego jest dla klienta niewygodne.

Procedura sprawdzania adresów URL w czasie rzeczywistym

Ta procedura jest używana, gdy klient wybierze tryb działania w czasie rzeczywistym.

Ta procedura przyjmuje pojedynczy adres URL u i zwraca SAFE, UNSAFE lub UNSURE. Jeśli zwróci wartość SAFE, Bezpieczne przeglądanie Google uzna adres URL za bezpieczny. Jeśli zwróci wartość UNSAFE, oznacza to, że przeglądarka Google Safe Browsing uznała adres URL za potencjalnie niebezpieczny i należy podjąć odpowiednie działania, np. wyświetlić ostrzeżenie dla użytkownika, przenieść otrzymaną wiadomość do folderu spamu lub poprosić o dodatkowe potwierdzenie. Jeśli zwróci wartość UNSURE, należy użyć tej procedury sprawdzania lokalnego.

  1. Niech expressions będzie listą wyrażeń sufiksów/prefiksów wygenerowanych przez adres URL u.
  2. Niech expressionHashes będzie listą, której elementy to hashe SHA256 każdego wyrażenia w expressions.
  3. W przypadku każdego hash z expressionHashes:
    1. Jeśli hash można znaleźć w globalnej pamięci podręcznej, zwracać UNSURE.
  4. Niech expressionHashPrefixes będzie listą, której elementy to pierwsze 4 bajty każdego hasha w expressionHashes.
  5. W przypadku każdego expressionHashPrefix z expressionHashPrefixes:
    1. Wyszukaj expressionHashPrefix w lokalnej pamięci podręcznej.
    2. Jeśli zostanie znaleziony wpis z pamięci podręcznej:
      1. Sprawdzanie, czy bieżąca godzina jest późniejsza niż czas wygaśnięcia.
      2. Jeśli jest większa:
        1. Usuń znaleziony wpis z pamięci podręcznej z pamięci lokalnej.
        2. Kontynuuj pętlę.
      3. Jeśli nie:
        1. Usuń to konkretne urządzenie expressionHashPrefix z konta expressionHashPrefixes.
        2. Sprawdź, czy odpowiadający mu pełny hasz w elementach expressionHashes znajduje się w zapamiętanym wpisie.
        3. W przeciwnym razie zwraca wartość UNSAFE.
        4. Jeśli nie zostanie znaleziony, przejdź do następnego pętli.
    3. Jeśli nie uda się znaleźć pozycji w pamięci podręcznej, przejdź do następnego elementu pętli.
  6. Prześlij expressionHashPrefixes do serwera Bezpiecznego przeglądania Google w wersji 5 za pomocą interfejsu RPC SearchHashes lub metody REST hashes.search. Jeśli wystąpił błąd (np. błąd sieci lub błąd HTTP), zwracany jest obiekt UNSURE. W przeciwnym razie odpowiedź to response otrzymany z serwera SB, czyli lista pełnych haszy wraz z informacjami pomocniczymi identyfikującymi charakter zagrożenia (inżynierię społeczną, złośliwe oprogramowanie itp.), a także czas wygaśnięcia pamięci podręcznej expiration.
  7. W przypadku każdego fullHash z response:
    1. Wstaw fullHash do lokalnego pamięci podręcznej razem z expiration.
  8. W przypadku każdego fullHash z response:
    1. Niech isFound będzie wynikiem znalezienia fullHashexpressionHashes.
    2. Jeśli isFound ma wartość False, kontynuuj pętlę.
    3. Jeśli isFound ma wartość Prawda, zwraca UNSAFE.
  9. Zwrot: SAFE.

Chociaż ten protokół określa, kiedy klient wysyła expressionHashPrefixes do serwera, celowo nie określa dokładnie, jak to zrobić. Dopuszczalne jest na przykład wysyłanie przez klienta wszystkich expressionHashPrefixes w jednym żądaniu, a także wysyłanie przez klienta poszczególnych prefiksów w expressionHashPrefixes w osobnych żądaniach (być może w tym samym czasie). Klient może też wysyłać niepasujące lub losowo wygenerowane prefiksy skrótów razem z prefiksami skrótów w expressionHashPrefixes, o ile liczba prefiksów skrótów wysłanych w pojedynczym żądaniu nie przekracza 30.

Procedura sprawdzania adresów URL w liście lokalnych zagrożeń

Ta procedura jest używana, gdy klient wybierze tryb działania listy lokalnej. Jest ona też używana, gdy klient w ramach procedury RealTimeCheck zwraca wartość UNSURE.

Ta procedura przyjmuje pojedynczy adres URL u i zwraca SAFE lub UNSAFE.

  1. Niech expressions będzie listą wyrażeń sufiksów/prefiksów wygenerowanych przez adres URL u.
  2. Niech expressionHashes będzie listą, której elementy to hashe SHA256 każdego wyrażenia w expressions.
  3. Niech expressionHashPrefixes będzie listą, której elementy to pierwsze 4 bajty każdego hasha w expressionHashes.
  4. W przypadku każdego expressionHashPrefix z expressionHashPrefixes:
    1. Wyszukaj expressionHashPrefix w lokalnej pamięci podręcznej.
    2. Jeśli zostanie znaleziony wpis z pamięci podręcznej:
      1. Sprawdzanie, czy bieżąca godzina jest późniejsza niż czas wygaśnięcia.
      2. Jeśli jest większa:
        1. Usuń znaleziony wpis z pamięci podręcznej z pamięci lokalnej.
        2. Kontynuuj pętlę.
      3. Jeśli nie:
        1. Usuń to konkretne urządzenie expressionHashPrefix z konta expressionHashPrefixes.
        2. Sprawdź, czy odpowiadający mu pełny hasz w elementach expressionHashes znajduje się w zapamiętanym wpisie.
        3. W przeciwnym razie zwraca wartość UNSAFE.
        4. Jeśli nie zostanie znaleziony, przejdź do następnego pętli.
    3. Jeśli nie uda się znaleźć pozycji w pamięci podręcznej, przejdź do następnego elementu pętli.
  5. W przypadku każdego expressionHashPrefix z expressionHashPrefixes:
    1. Wyszukaj expressionHashPrefix w lokalnej bazie danych z listą zagrożeń.
    2. Jeśli expressionHashPrefix nie można znaleźć w lokalnej bazie danych z listą zagrożeń, usuń go z expressionHashPrefixes.
  6. Prześlij expressionHashPrefixes do serwera Bezpiecznego przeglądania Google w wersji 5 za pomocą interfejsu RPC SearchHashes lub metody REST hashes.search. Jeśli wystąpił błąd (np. błąd sieci lub błąd HTTP), zwracany jest obiekt SAFE. W przeciwnym razie odpowiedź to response otrzymany z serwera SB, czyli lista pełnych haszy wraz z informacjami pomocniczymi identyfikującymi charakter zagrożenia (inżynierię społeczną, złośliwe oprogramowanie itp.), a także czas ważności pamięci podręcznej expiration.
  7. W przypadku każdego fullHash z response:
    1. Wstaw fullHash do lokalnego pamięci podręcznej razem z expiration.
  8. W przypadku każdego fullHash z response:
    1. Niech isFound będzie wynikiem znalezienia fullHashexpressionHashes.
    2. Jeśli isFound ma wartość False, kontynuuj pętlę.
    3. Jeśli isFound ma wartość Prawda, zwraca UNSAFE.
  9. Zwrot: SAFE.

Procedura sprawdzania adresów URL w czasie rzeczywistym bez bazy danych lokalnej

Ta procedura jest używana, gdy klient wybierze tryb działania w czasie rzeczywistym bez przechowywania danych.

Ta procedura przyjmuje pojedynczy adres URL u i zwraca SAFE lub UNSAFE.

  1. Niech expressions będzie listą wyrażeń sufiksów/prefiksów wygenerowanych przez adres URL u.
  2. Niech expressionHashes będzie listą, której elementy to hashe SHA256 każdego wyrażenia w expressions.
  3. Niech expressionHashPrefixes będzie listą, której elementy to pierwsze 4 bajty każdego hasha w expressionHashes.
  4. W przypadku każdego expressionHashPrefix z expressionHashPrefixes:
    1. Wyszukaj expressionHashPrefix w lokalnej pamięci podręcznej.
    2. Jeśli zostanie znaleziony wpis z pamięci podręcznej:
      1. Sprawdzanie, czy bieżąca godzina jest późniejsza niż czas wygaśnięcia.
      2. Jeśli jest większa:
        1. Usuń znaleziony wpis z pamięci podręcznej z pamięci lokalnej.
        2. Kontynuuj pętlę.
      3. Jeśli nie:
        1. Usuń to konkretne urządzenie expressionHashPrefix z konta expressionHashPrefixes.
        2. Sprawdź, czy odpowiadający mu pełny hasz w elementach expressionHashes znajduje się w zapamiętanym wpisie.
        3. W przeciwnym razie zwraca wartość UNSAFE.
        4. Jeśli nie zostanie znaleziony, przejdź do następnego pętli.
    3. Jeśli nie uda się znaleźć pozycji w pamięci podręcznej, przejdź do następnego elementu pętli.
  5. Prześlij expressionHashPrefixes do serwera Bezpiecznego przeglądania Google w wersji 5 za pomocą interfejsu RPC SearchHashes lub metody REST hashes.search. Jeśli wystąpił błąd (np. błąd sieci lub błąd HTTP), zwracany jest kod SAFE. W przeciwnym razie odpowiedź to response otrzymany z serwera SB, czyli lista pełnych haszy wraz z informacjami pomocniczymi identyfikującymi charakter zagrożenia (inżynierię społeczną, złośliwe oprogramowanie itp.), a także czas wygaśnięcia pamięci podręcznej expiration.
  6. W przypadku każdego fullHash z response:
    1. Wstaw fullHash do lokalnego pamięci podręcznej razem z expiration.
  7. W przypadku każdego fullHash z response:
    1. Niech isFound będzie wynikiem znalezienia fullHashexpressionHashes.
    2. Jeśli isFound ma wartość False, kontynuuj pętlę.
    3. Jeśli isFound ma wartość Prawda, zwraca UNSAFE.
  8. Zwrot: SAFE.

Podobnie jak w przypadku procedury sprawdzania adresów URL w czasie rzeczywistym, nie określa ona dokładnie, jak przesłać prefiksy haszowania do serwera. Dopuszczalne jest na przykład wysyłanie przez klienta wszystkich expressionHashPrefixes w jednym żądaniu, a także wysyłanie przez klienta poszczególnych prefiksów w expressionHashPrefixes w osobnych żądaniach (być może w tym samym czasie). Klient może też wysyłać niepasujące lub losowo wygenerowane prefiksy skrótów razem z prefiksami skrótów w expressionHashPrefixes, o ile liczba prefiksów skrótów wysłanych w pojedynczym żądaniu nie przekracza 30.

Przykładowe żądania

W tej sekcji znajdziesz kilka przykładów bezpośredniego korzystania z interfejsu HTTP API do uzyskiwania dostępu do Bezpiecznego przeglądania Google. Zwykle zalecamy używanie wygenerowanego języka, ponieważ automatycznie obsługuje on kodowanie i dekodowanie w wygodny sposób. Więcej informacji znajdziesz w dokumentacji dotyczącej tego typu dokumentu.

Oto przykład żądania HTTP korzystającego z metody hashes.search:

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

Treść odpowiedzi to dane w formacie bufora protokołu, które możesz następnie zdekodować.

Oto przykład żądania HTTP korzystającego z metody hashLists.batchGet:

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

Treść odpowiedzi to ponownie ładunek sformatowany zgodnie z buforem protokołu, który możesz następnie zdekodować.