Overview

Wstęp

Uwaga: ta dokumentacja jest nadal w fazie rozwoju. W najbliższej przyszłości spodziewaj się ulepszeń.

Bezpieczne przeglądanie Google w wersji 5 to ewolucja Bezpiecznego przeglądania Google w wersji 4. Dwie kluczowe zmiany wprowadzone w wersji 5 to częstotliwość aktualizacji danych i prywatność adresów IP. Ulepszyliśmy też interfejs API, aby zwiększyć elastyczność, wydajność i zmniejszyć wzdęcie. Ponadto Bezpieczne przeglądanie Google w wersji 5 zostało zaprojektowane tak, by ułatwić migrację z wersji 4.

Obecnie Google oferuje zarówno wersje 4, jak i 5. Obie są uważane za gotowe do wdrożenia w środowisku produkcyjnym. Możesz użyć wersji 4 lub 5. Nie ogłosiliśmy jeszcze daty wycofania wersji 4, ale w takim przypadku powiadomimy Cię o tym z co najmniej rocznym wyprzedzeniem. Na tej stronie znajduje się opis wersji 5 oraz przewodnik po migracji z wersji 4 do 5. Pełna dokumentacja wersji 4 pozostaje dostępna.

Aktualność danych

Istotnym ulepszeniem Bezpiecznego przeglądania Google w wersji 5 w porównaniu z wersją 4 (w szczególności interfejsem API aktualizacji w wersji 4) jest częstotliwość aktualizacji i zasięg danych. Ochrona w dużym stopniu zależy od lokalnej bazy danych obsługiwanej przez klienta, więc opóźnienie i rozmiar lokalnej aktualizacji są głównym czynnikiem wpływającym na braki w ochronie. W wersji 4 typowy klient potrzebuje od 20 do 50 minut na uzyskanie najnowszej wersji list zagrożeń. Niestety, ataki phishingowe szybko się rozprzestrzeniają: według danych na 60% witryn, które przeprowadzają ataki, trwa mniej niż 10 minut. Z naszych analiz wynika, że brak aktualizacji danych w około 25–30% brakuje ochrony przed phishingiem. Niektóre urządzenia nie są przystosowane do zarządzania wszystkimi listami zagrożeń Bezpiecznego przeglądania Google, które z czasem rosną.

W wersji 5 wprowadziliśmy tryb działania nazywany ochroną w czasie rzeczywistym. Pozwala to ominąć powyższy problem z brakiem aktualizacji danych. W wersji 4 klienty muszą pobrać i utrzymywać lokalną bazę danych, przeprowadzać testy pod kątem lokalnie pobranych list zagrożeń, a następnie w przypadku częściowego dopasowania prefiksu wysłać żądanie pobrania pełnego hasza. W wersji v5 klienci powinni nadal pobierać i utrzymywać lokalną bazę danych z listami zagrożeń. Oczekuje się jednak, że klienty również pobierzą listę prawdopodobnych nieszkodliwych witryn (nazywanych globalną pamięcią podręczną), wykonują zarówno lokalne sprawdzenie tej globalnej pamięci podręcznej, jak i sprawdzenie lokalnej listy zagrożeń, a wreszcie w przypadku częściowego dopasowania prefiksu dla list zagrożeń lub braku dopasowania w globalnej pamięci podręcznej żądania, (szczegółowe informacje na temat lokalnego przetwarzania wymaganego przez klienta znajdziesz poniżej). Jest to zmiana z trybu domyślnie zezwalania na sprawdzanie domyślnie, co może poprawić ochronę w świetle szybszego rozprzestrzeniania zagrożeń w internecie. Inaczej mówiąc, protokół ten ma zapewniać ochronę w czasie zbliżonym do rzeczywistego. Chcemy, aby klienci mogli czerpać korzyści z aktualnych danych Bezpiecznego przeglądania Google.

Prywatność adresów IP

Bezpieczne przeglądanie Google (w wersjach 4 i 5) nie przetwarza podczas wyświetlania żądań żadnych danych związanych z tożsamością użytkownika. Wysyłane pliki cookie są ignorowane. Źródłowe adresy IP żądań są znane Google, ale używamy ich tylko do niezbędnych celów związanych z siecią (np. do wysyłania odpowiedzi) i do ochrony przed atakami typu DoS.

Równocześnie z wersją 5 wprowadzamy dodatkowy interfejs API o nazwie Safe Browsing Oblivious HTTP Gateway API. Ta metoda ukrywa adresy IP użytkowników przed Google przy użyciu protokołu Oblivious HTTP. Wykorzystuje w tym celu niewykluczającą firmę zewnętrzną, która obsługuje zaszyfrowaną wersję żądania użytkownika i przekazuje ją do Google. W takim przypadku inna firma ma dostęp tylko do adresów IP, a Google ma dostęp jedynie do treści żądania. Firma zewnętrzna obsługuje Oblivious HTTP Relay (taką jak usługę Fastly), a Google obsługuje bramę Oblivious HTTP. To jest opcjonalny interfejs API towarzyszący. Gdy używasz tej funkcji w połączeniu z Bezpiecznym przeglądaniem Google, adresy IP użytkowników nie są już wysyłane do Google.

Właściwe wykorzystanie

Dozwolone użytkowanie

Interfejs Safe Browsing API jest przeznaczony tylko do użytku niekomercyjnego (czyli „nie do sprzedaży ani generowania przychodów”). Jeśli potrzebujesz rozwiązania do celów komercyjnych, skorzystaj z Web Risk.

Ceny

Wszystkie interfejsy API Bezpiecznego przeglądania Google są bezpłatne.

Limity

Po włączeniu interfejsu Safe Browsing API deweloperzy otrzymują domyślny limit wykorzystania. Aktualne przydziały i wykorzystanie możesz sprawdzić w Google Developer Console. Jeśli spodziewasz się zużywać więcej niż masz obecnie przydzielony limit, możesz poprosić o zwiększenie limitu w interfejsie limitów w Konsoli programisty. Rozpatrujemy te wnioski i prosimy o kontakt z prośbą o zwiększenie limitu, aby mieć pewność, że dostępność naszych usług spełnia potrzeby wszystkich użytkowników.

Odpowiednie adresy URL

Bezpieczne przeglądanie Google działa z adresami URL, które są wyświetlane na pasku adresu przeglądarki. Nie służy do sprawdzania zasobów podrzędnych (takich jak kod JavaScript lub obraz, do których odwołuje się plik HTML, ani adres URL WebSocket zainicjowany przez JavaScript). Nie należy sprawdzać takich adresów URL zasobów podrzędnych pod kątem Bezpiecznego przeglądania Google.

Jeśli otwarcie adresu URL powoduje przekierowanie (np. HTTP 301), należy go sprawdzić pod kątem Bezpiecznego przeglądania Google. Manipulacja adresami URL po stronie klienta, np. History.pushState, nie skutkuje sprawdzeniem nowych adresów URL pod kątem Bezpiecznego przeglądania Google.

Ostrzeżenia dla użytkowników

Jeśli używasz Bezpiecznego przeglądania Google do ostrzegania użytkowników o zagrożeniach związanych z konkretnymi stronami internetowymi, obowiązują Cię te wskazówki.

Te wytyczne pomagają chronić zarówno Ciebie, jak i Google przed nieporozumieniem, ponieważ jasno określają, że dana strona nie jest znana z całkowitej pewności, że nie jest niebezpiecznym zasobem internetowym, oraz że ostrzeżenia wskazują tylko potencjalne ryzyko.

  • W widocznym dla użytkownika ostrzeżeniu nie możesz skłaniać użytkowników do myślenia, że strona, której dotyczy zgłoszenie, bez wątpienia zawiera niebezpieczne treści. Gdy wspominasz o rozpoznanej stronie lub o potencjalnych zagrożeniach, jakie może ona stanowić dla użytkowników, musisz odpowiednio opisać ostrzeżenie, używając takich określeń jak: podejrzenie, potencjalnie, możliwe, prawdopodobne.
  • Twoje ostrzeżenie musi dać użytkownikowi możliwość uzyskania dodatkowych informacji z opracowanej przez Google definicji różnych zagrożeń. Proponujemy te linki:
  • Jeśli wyświetlasz ostrzeżenia dotyczące stron zidentyfikowanych przez usługę Bezpieczne przeglądanie jako niebezpieczne, musisz poinformować o tym Google, dodając wiersz „Zalecenie dostarczone przez Google” z linkiem do Zalecenia dotyczące bezpiecznego przeglądania. Jeśli produkt wyświetla też ostrzeżenia z innych źródeł, nie możesz umieszczać informacji o atrybucji Google w ostrzeżeniach pochodzących z danych spoza Google.

  • W dokumentacji usługi należy umieścić informację dla użytkowników, że ochrona oferowana przez Bezpieczne przeglądanie Google nie jest doskonała. Musi informować o możliwości wystąpienia zarówno wyników fałszywie pozytywnych (bezpieczne witryny oznaczone jako ryzykowne), jak i fałszywie negatywnych (witryny nieoznaczone jako ryzykowne). Sugerujemy użycie następującego języka:

    Staramy się udostępniać najbardziej dokładne i aktualne informacje o niebezpiecznych zasobach internetowych. Google nie może jednak zagwarantować, że zawarte w nim informacje są wyczerpujące i wolne od błędów: niektóre niebezpieczne witryny mogą nie zostać zidentyfikowane, a niektóre bezpieczne.

Tryby działania

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

Tryb czasu rzeczywistego

Gdy klienty zdecydują się na używanie Bezpiecznego przeglądania Google w wersji 5 w trybie rzeczywistym, zachowają w swojej lokalnej bazie danych: (i) globalną pamięć podręczną z prawdopodobnymi niegroźnymi witrynami sformatowaną jako hasze SHA256 wyrażeń adresu URL hosta i prefiksu ścieżki oraz (ii) zestaw list zagrożeń w postaci prefiksów haszy SHA256 wyrażeń adresu URL hosta/prefiksu ścieżki. Ogólnie rzecz biorąc, za każdym razem, gdy klient chce sprawdzić konkretny adres URL, przeprowadza się kontrolę lokalną przy użyciu globalnej pamięci podręcznej. Jeśli weryfikacja przebiegnie pomyślnie, przeprowadzany jest test dotyczący lokalnych list zagrożeń. W przeciwnym razie klient kontynuuje sprawdzanie haszowania w czasie rzeczywistym, jak opisano poniżej.

Oprócz lokalnej bazy danych klient będzie utrzymywać lokalną pamięć podręczną. Taka lokalna pamięć podręczna nie musi być w pamięci trwałej i może zostać wyczyszczona w przypadku wyczerpania pamięci.

Szczegółową specyfikację tej procedury znajdziesz poniżej.

Tryb listy lokalnej

Gdy klienci zdecydują się na używanie w tym trybie Bezpiecznego przeglądania Google w wersji 5, zachowanie klienta będzie podobne do interfejsu Update API w wersji 4, z wyjątkiem korzystania z ulepszonej platformy interfejsu API w wersji 5. Klient będzie przechowywać w lokalnej bazie danych zestaw list zagrożeń w postaci prefiksów skrótu SHA256 wyrażeń adresów URL z prefiksem hosta/prefiksem ścieżki. Za każdym razem, gdy klient chce sprawdzić konkretny adres URL, przeprowadza się kontrolę przy użyciu lokalnej listy zagrożeń. Jeśli (i tylko jeśli) udało się dopasować kod, klient łączy się z serwerem, aby kontynuować sprawdzanie.

Tak jak w przypadku powyższego, klient zachowa również lokalną pamięć podręczną, która nie musi być w pamięci trwałej.

Tryb czasu rzeczywistego bez pamięci

Gdy klienty zdecydują się używać Bezpiecznego przeglądania Google w wersji 5 w trybie braku pamięci w czasie rzeczywistym, nie muszą utrzymywać żadnej trwałej lokalnej bazy danych. Oczekuje się jednak, że klient nadal będzie utrzymywać lokalną pamięć podręczną. Taka lokalna pamięć podręczna nie musi być w pamięci trwałej i może zostać wyczyszczona w przypadku wyczerpania pamięci.

Za każdym razem, gdy klient chce sprawdzić określony adres URL, zawsze łączy się z serwerem, aby wykonać tę operację. Ten tryb jest podobny do tego, które mogą implementować klienty interfejsu lookup API w wersji 4.

W porównaniu z trybem w czasie rzeczywistym ten tryb może wykorzystywać większą przepustowość sieci, ale może być bardziej odpowiedni, jeśli utrzymanie stałego stanu lokalnego jest uciążliwe dla klienta.

Sprawdzam adresy URL

Ta sekcja zawiera szczegółowe specyfikacje dotyczące sposobu sprawdzania adresów URL przez klientów.

Kanonizacja adresów URL

Przed sprawdzeniem jakichkolwiek adresów URL klient powinien dokonać wyboru kanonicznego adresu URL.

Na początek zakładamy, że klient przeanalizował adres URL i przyznał jego poprawność zgodnie ze standardem RFC 2396. Jeśli w adresie URL jest używana umiędzynarodowiona nazwa domeny (IDN), klient powinien przekonwertować adres URL na format ASCII Punycode. Adres URL musi zawierać komponent ścieżki. Oznacza to, że po domenie musi znajdować się co najmniej 1 ukośnik (http://google.com/ zamiast http://google.com).

Najpierw usuń z adresu URL znaki tabulacji (0x09), CR (0x0d) i LF (0x0a). Nie usuwaj sekwencji zmiany znaczenia tych znaków (np. %0a).

Po drugie, jeśli adres URL kończy się fragmentem, usuń ten fragment. Na przykład skróć http://google.com/#frag do http://google.com/.

Po trzecie, wielokrotnie zmieniaj znak znaczenia procenta, aż w adresie URL nie będzie już znaków zmiany znaczenia. (Może to spowodować, że URL będzie nieprawidłowy).

Aby sprowadzić nazwę hosta do postaci kanonicznej:

Wyodrębnij nazwę hosta z adresu URL, a potem:

  1. Usuń wszystkie kropki na początku i na końcu ciągu znaków.
  2. Zastąp kolejne kropki jedną kropką.
  3. Jeśli nazwę hosta można przeanalizować jako adres IPv4, znormalizuj ją do 4 wartości dziesiętnych rozdzielonych kropkami. Klient powinien obsługiwać wszelkie dozwolone kodowanie adresów IP, w tym ósemkowe, szesnastkowe i mniej niż 4 komponenty.
  4. Jeśli nazwę hosta można przeanalizować jako adres IPv6 umieszczony w nawiasach, znormalizuj ją, usuwając z komponentów niepotrzebne zera na początku i zwijając zero komponentów przy użyciu składni z podwójnym dwukropkiem. Na przykład [2001:0db8:0000::1] należy przekształcić w element [2001:db8::1]. Jeśli nazwa hosta jest jednym z 2 tych specjalnych typów adresów IPv6, przekształć je na IPv4:
    • Adres IPv6 mapowany na IPv4, np. [::ffff:1.2.3.4], który należy przekształcić w: 1.2.3.4.
    • Adres NAT64 z dobrze znanym prefiksem 64:ff9b::/96, na przykład [64:ff9b::1.2.3.4], który należy przekształcić w ciąg 1.2.3.4.
  5. Cały ciąg należy pisać małymi literami.

Aby określić ścieżkę kanoniczną:

  1. Rozwiąż sekwencje /../ i /./ w ścieżce, zastępując element /./ elementem / i usuwając element /../ wraz z poprzednim komponentem ścieżki.
  2. Zastąp ciągi kolejnych ukośników jednym ukośnikiem.

Nie stosuj tych kanonicznych ścieżek do parametrów zapytania.

W adresie URL użyj znaku zmiany znaczenia przed upływem procentowego znaczenia wszystkich znaków, które są znakami <= ASCII 32, >= 127, # lub %. Znak ucieczki powinien zawierać wielkie litery szesnastkowe.

Wyrażenia prefiksu ścieżki hosta i prefiksu ścieżki

Następnym krokiem po przekształceniu adresu URL jest utworzenie wyrażenia sufiksu/prefiksu. Każde wyrażenie sufiksu/prefiksu składa się z sufiksu hosta (lub pełnego hosta) i prefiksu ścieżki (lub pełnej ścieżki).

Klient utworzy maksymalnie 30 różnych kombinacji sufiksów hosta i prefiksów ścieżki. W tych kombinacjach używane są tylko komponenty hosta i ścieżki adresu URL. Schemat, nazwa użytkownika, hasło i port są odrzucane. Jeśli adres URL zawiera parametry zapytania, co najmniej jedna z nich będzie zawierać pełną ścieżkę i parametry zapytania.

W przypadku hosta klient próbuje wypróbować maksymalnie 5 różnych ciągów. Są to:

  • Jeśli nazwa hosta nie jest literałem IPv4 ani IPv6, można utworzyć maksymalnie 4 nazwy hosta, zaczynając od domeny eTLD+1 i dodając kolejne główne komponenty. Domena eTLD+1 musi zostać określona na podstawie listy domen publicznych. Na przykład dyrektywa a.b.example.com spowodowałaby utworzenie domeny eTLD+1 domeny example.com, a także hosta z 1 dodatkowym komponentem hosta b.example.com.
  • Dokładna nazwa hosta w adresie URL. Zgodnie z poprzednim przykładem zaznaczone będzie pole a.b.example.com.

W przypadku ścieżki klient próbuje wypróbować maksymalnie 6 różnych ciągów znaków. Są to:

  • Dokładna ścieżka adresu URL wraz z parametrami zapytania.
  • Dokładna ścieżka adresu URL, bez parametrów zapytania.
  • Cztery ścieżki składające się z początku (/) i stopniowego dodawania komponentów ścieżki, w tym ukośnika końcowego.

Sposób sprawdzania poprawności ilustruje poniższe przykłady:

W przypadku adresu URL http://a.b.com/1/2.html?param=1 klient spróbuje wykonać te czynności:

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/

W przypadku adresu URL http://a.b.c.d.e.f.com/1.html klient spróbuje wykonać te czynności:

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/

(Uwaga: pomiń b.c.d.e.f.com, ponieważ wykorzystamy tylko 5 ostatnich komponentów nazwy hosta i pełną nazwę hosta).

W przypadku adresu URL http://1.2.3.4/1/ klient spróbuje wykonać te czynności:

1.2.3.4/1/
1.2.3.4/

W przypadku adresu URL http://example.co.uk/1 klient spróbuje wykonać te czynności:

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

Haszowanie

Bezpieczne przeglądanie Google używa wyłącznie SHA256 jako funkcji skrótu. Tę funkcję skrótu należy stosować do powyższych wyrażeń.

Pełny 32-bajtowy hasz (w zależności od sytuacji) zostanie skrócony do 4, 8 lub 16 bajtów:

  • W przypadku korzystania z metody hashes.search wymagamy obecnie skrócenia haszów w żądaniu do dokładnie 4 bajtów. Wysłanie dodatkowych bajtów w tym żądaniu spowoduje naruszenie prywatności użytkownika.

  • Podczas pobierania list dla lokalnej bazy danych za pomocą metody hashList.get lub hashLists.batchGet długość haszy wysyłanych przez serwer zależy zarówno od charakteru listy, jak i preferencji klienta dotyczących długości skrótu wskazywanego przez parametr desired_hash_length.

Procedura sprawdzania adresów URL w czasie rzeczywistym

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

Ta procedura obejmuje pojedynczy adres URL u i zwraca SAFE, UNSAFE lub UNSURE. Jeśli zwraca wartość SAFE, adres URL zostanie uznany za bezpieczny przez Bezpieczne przeglądanie Google. Jeśli zwracana jest wartość UNSAFE, oznacza to, że Bezpieczne przeglądanie Google uznało adres URL za potencjalnie niebezpieczny. W takim przypadku należy podjąć odpowiednie działanie, na przykład wyświetlić ostrzeżenie użytkownikowi, przenieść otrzymaną wiadomość do folderu ze spamem lub wymagać od użytkownika dodatkowego potwierdzenia przed kontynuacją. Jeśli zwraca kod UNSURE, należy wykonać poniższą procedurę kontroli lokalnej.

  1. Niech expressions będzie listą wyrażeń sufiksu/prefiksu wygenerowanych przez adres URL u.
  2. Niech expressionHashes będzie listą, gdzie elementy są skrótami SHA256 każdego wyrażenia w zasadzie expressions.
  3. Dla każdego elementu hash z expressionHashes:
    1. Jeśli hash można znaleźć w globalnej pamięci podręcznej, zwróć wartość UNSURE.
  4. Niech expressionHashPrefixes będzie listą, w której elementy to pierwsze 4 bajty każdego hasza w expressionHashes.
  5. Dla każdego elementu expressionHashPrefix z expressionHashPrefixes:
    1. Wyszukaj expressionHashPrefix w lokalnej pamięci podręcznej.
    2. Jeśli wpis z pamięci podręcznej zostanie znaleziony:
      1. Określ, czy bieżący czas jest późniejszy niż czas jego wygaśnięcia.
      2. Jeśli jest większa:
        1. Usuń znaleziony wpis w pamięci podręcznej z lokalnej pamięci podręcznej.
        2. Utwórz pętlę.
      3. Jeśli nie jest większa:
        1. Usuń ten konkretny produkt typu expressionHashPrefix z usługi expressionHashPrefixes.
        2. Sprawdź, czy we wpisie w pamięci podręcznej znajduje się odpowiedni pełny hasz z pola expressionHashes.
        3. Jeśli zostanie znaleziony, zwróć UNSAFE.
        4. Jeśli tak się nie stanie, powtórz pętlę.
    3. Jeśli wpis z pamięci podręcznej nie zostanie znaleziony, kontynuuj tworzenie pętli.
  6. Wyślij expressionHashPrefixes do serwera Bezpiecznego przeglądania Google w wersji 5, używając haszy RPC lub metody REST hashes.search. Jeśli wystąpił błąd (w tym błędy sieci lub HTTP), zwróć UNSURE. W przeciwnym razie w odpowiedzi umieść response otrzymany z serwera SB, który jest listą pełnych haszów wraz z informacjami pomocniczymi identyfikującymi charakter zagrożenia (inżynierią społeczną, złośliwym oprogramowaniem itp.), a także czasem wygaśnięcia pamięci podręcznej (expiration).
  7. Dla każdego elementu fullHash z response:
    1. Wstaw plik fullHash do lokalnej pamięci podręcznej razem z plikiem expiration.
  8. Dla każdego elementu fullHash z response:
    1. Niech isFound będzie wynikiem znalezienia fullHash w expressionHashes.
    2. Jeśli isFound ma wartość Fałsz, kontynuuj tworzenie pętli.
    3. Jeśli isFound ma wartość Prawda, zwraca UNSAFE.
  9. Zwróć: SAFE.

Protokół ten określa, kiedy klient wysyła expressionHashPrefixes na serwer, ale nie określa dokładnie, jak je wysyłać. Na przykład klient może wysłać wszystkie żądania expressionHashPrefixes w jednym żądaniu, jak również może wysyłać poszczególne prefiksy w usłudze expressionHashPrefixes do serwera w osobnych żądaniach (być może równolegle). Klient może też wysyłać niepowiązane lub wygenerowane losowo prefiksy haszujące wraz z prefiksami skrótu w zasadzie expressionHashPrefixes, o ile liczba takich prefiksów wysłanych w jednym żądaniu nie przekracza 30.

Procedura sprawdzania adresów URL na liście LocalThreat

Ta procedura jest używana, gdy klient zdecyduje się na działanie w trybie listy lokalnej. Jest też używany, gdy klient powyższa procedura RealTimeCheck zwraca wartość UNSURE.

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

  1. Niech expressions będzie listą wyrażeń sufiksu/prefiksu wygenerowanych przez adres URL u.
  2. Niech expressionHashes będzie listą, gdzie elementy są skrótami SHA256 każdego wyrażenia w zasadzie expressions.
  3. Niech expressionHashPrefixes będzie listą, w której elementy to pierwsze 4 bajty każdego hasza w expressionHashes.
  4. Dla każdego elementu expressionHashPrefix z expressionHashPrefixes:
    1. Wyszukaj expressionHashPrefix w lokalnej pamięci podręcznej.
    2. Jeśli wpis z pamięci podręcznej zostanie znaleziony:
      1. Określ, czy bieżący czas jest późniejszy niż czas jego wygaśnięcia.
      2. Jeśli jest większa:
        1. Usuń znaleziony wpis w pamięci podręcznej z lokalnej pamięci podręcznej.
        2. Utwórz pętlę.
      3. Jeśli nie jest większa:
        1. Usuń ten konkretny produkt typu expressionHashPrefix z usługi expressionHashPrefixes.
        2. Sprawdź, czy we wpisie w pamięci podręcznej znajduje się odpowiedni pełny hasz z pola expressionHashes.
        3. Jeśli zostanie znaleziony, zwróć UNSAFE.
        4. Jeśli tak się nie stanie, powtórz pętlę.
    3. Jeśli wpis z pamięci podręcznej nie zostanie znaleziony, kontynuuj tworzenie pętli.
  5. Dla każdego elementu expressionHashPrefix z expressionHashPrefixes:
    1. Wyszukaj aplikację expressionHashPrefix w bazie danych lokalnych list zagrożeń.
    2. Jeśli elementu expressionHashPrefix nie można znaleźć w bazie danych lokalnych list zagrożeń, usuń go z expressionHashPrefixes.
  6. Wyślij expressionHashPrefixes do serwera Bezpiecznego przeglądania Google w wersji 5, używając haszy RPC lub metody REST hashes.search. Jeśli wystąpił błąd (w tym błędy sieci lub HTTP), zwróć SAFE. W przeciwnym razie w odpowiedzi umieść response otrzymany z serwera SB, który jest listą pełnych haszów wraz z informacjami pomocniczymi identyfikującymi charakter zagrożenia (inżynierią społeczną, złośliwym oprogramowaniem itp.), a także czasem wygaśnięcia pamięci podręcznej (expiration).
  7. Dla każdego elementu fullHash z response:
    1. Wstaw plik fullHash do lokalnej pamięci podręcznej razem z plikiem expiration.
  8. Dla każdego elementu fullHash z response:
    1. Niech isFound będzie wynikiem znalezienia fullHash w expressionHashes.
    2. Jeśli isFound ma wartość Fałsz, kontynuuj tworzenie pętli.
    3. Jeśli isFound ma wartość Prawda, zwraca UNSAFE.
  9. Zwróć: SAFE.

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

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

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

  1. Niech expressions będzie listą wyrażeń sufiksu/prefiksu wygenerowanych przez adres URL u.
  2. Niech expressionHashes będzie listą, gdzie elementy są skrótami SHA256 każdego wyrażenia w zasadzie expressions.
  3. Niech expressionHashPrefixes będzie listą, w której elementy to pierwsze 4 bajty każdego hasza w expressionHashes.
  4. Dla każdego elementu expressionHashPrefix z expressionHashPrefixes:
    1. Wyszukaj expressionHashPrefix w lokalnej pamięci podręcznej.
    2. Jeśli wpis z pamięci podręcznej zostanie znaleziony:
      1. Określ, czy bieżący czas jest późniejszy niż czas jego wygaśnięcia.
      2. Jeśli jest większa:
        1. Usuń znaleziony wpis w pamięci podręcznej z lokalnej pamięci podręcznej.
        2. Utwórz pętlę.
      3. Jeśli nie jest większa:
        1. Usuń ten konkretny produkt typu expressionHashPrefix z usługi expressionHashPrefixes.
        2. Sprawdź, czy we wpisie w pamięci podręcznej znajduje się odpowiedni pełny hasz z pola expressionHashes.
        3. Jeśli zostanie znaleziony, zwróć UNSAFE.
        4. Jeśli tak się nie stanie, powtórz pętlę.
    3. Jeśli wpis z pamięci podręcznej nie zostanie znaleziony, kontynuuj tworzenie pętli.
  5. Wyślij expressionHashPrefixes do serwera Bezpiecznego przeglądania Google w wersji 5, używając haszy RPC lub metody REST hashes.search. Jeśli wystąpił błąd (w tym błędy sieci lub HTTP), zwróć SAFE. W przeciwnym razie w odpowiedzi umieść response otrzymany z serwera SB, który jest listą pełnych haszów wraz z informacjami pomocniczymi identyfikującymi charakter zagrożenia (inżynierią społeczną, złośliwym oprogramowaniem itp.), a także czasem wygaśnięcia pamięci podręcznej (expiration).
  6. Dla każdego elementu fullHash z response:
    1. Wstaw plik fullHash do lokalnej pamięci podręcznej razem z plikiem expiration.
  7. Dla każdego elementu fullHash z response:
    1. Niech isFound będzie wynikiem znalezienia fullHash w expressionHashes.
    2. Jeśli isFound ma wartość Fałsz, kontynuuj tworzenie pętli.
    3. Jeśli isFound ma wartość Prawda, zwraca UNSAFE.
  8. Zwróć: SAFE.

Podobnie jak w przypadku sprawdzania adresów URL w czasie rzeczywistym, procedura ta nie określa dokładnie, jak wysłać prefiksy skrótu na serwer. Na przykład klient może wysłać wszystkie żądania expressionHashPrefixes w jednym żądaniu, jak również może wysyłać poszczególne prefiksy w usłudze expressionHashPrefixes do serwera w osobnych żądaniach (być może równolegle). Klient może też wysyłać niepowiązane lub wygenerowane losowo prefiksy haszujące wraz z prefiksami skrótu w zasadzie expressionHashPrefixes, o ile liczba takich prefiksów wysłanych w jednym żądaniu nie przekracza 30.

Konserwacja lokalnej bazy danych

Bezpieczne przeglądanie Google w wersji 5 wymaga od klienta utrzymywania lokalnej bazy danych, chyba że wybierze tryb czasu rzeczywistego bez przechowywania danych. To od klienta zależy format i przechowywanie tej lokalnej bazy danych. Zawartość tej lokalnej bazy danych można traktować jak folder zawierający różne listy w formie plików, a zawartość tych plików to hasze SHA256 lub prefiksy skrótu.

Aktualizacje bazy danych

Klient będzie regularnie wywoływać metodęhashList.get lub metodęhashLists.batchGet, aby aktualizować bazę danych. Typowy klient będzie chciał zaktualizować wiele list jednocześnie, dlatego zalecamy użycie metodyhashLists.batchGet.

Listy mają różne nazwy. Nazwy są krótkimi ciągami ASCII o długości kilku znaków.

W przeciwieństwie do wersji 4, w której listy w wersji 5 są identyfikowane na podstawie krotki typu zagrożenia, typu platformy i typu wpisu zagrożenia, na listach w wersji 5 listy są po prostu identyfikowane za pomocą nazwy. Zapewnia to elastyczność, gdy wiele list w wersji 5 może mieć ten sam typ zagrożenia. Typy platform i typy wpisów zagrożeń zostały usunięte w wersji 5.

Wybrana nazwa listy nigdy nie zostanie zmieniona. Ponadto po pojawieniu się listy nigdy nie zostanie ona usunięta (jeśli nie jest już przydatna, stanie się pusta, ale będzie nadal istnieć). Dlatego można je zakodować na stałe w kodzie klienta Bezpiecznego przeglądania Google.

Zarówno metodahashList.get, jak i metodahashLists.batchGet obsługują aktualizacje przyrostowe. Aktualizacje przyrostowe pozwalają oszczędzać przepustowość i zwiększać wydajność. Aktualizacje przyrostowe działają, ponieważ zapewniają różnice między wersją listy klienta a jej najnowszą wersją. (Jeśli klient został niedawno wdrożony i nie ma żadnych dostępnych wersji, dostępna jest pełna aktualizacja). Aktualizacja przyrostowa zawiera indeksy usunięć i dodania. Klient powinien najpierw usunąć wpisy o określonych indeksach z lokalnej bazy danych, a następnie zastosować dodane elementy.

Aby zapobiec uszkodzeniu, klient powinien porównać zapisane dane z sumą kontrolną podaną przez serwer. Gdy suma kontrolna się nie zgadza, klient powinien przeprowadzić pełną aktualizację.

Dekodowanie zawartości listy

Dekodowanie haszy i prefiksów haszy

Wszystkie listy są wysyłane przy użyciu specjalnego kodowania, aby je zmniejszyć. Kodowanie polega na rozpoznawaniu, że listy Bezpiecznego przeglądania Google zawierają, koncepcyjnie, zestaw haszów lub prefiksów skrótu, których statystycznie nie da się odróżnić od losowych liczb całkowitych. Gdybyśmy posortowali liczby całkowite i obliczyliśmy ich sąsiadujące z nimi różnice, można uznać, że różnica między nimi jest „mała”. Następnie wykorzystuje tę niedokładność kodowanie Golomb-Rice.

Załóżmy, że 3 wyrażenia z prefiksem ścieżki hosta i sufiksu (prefiks hosta), tzn. a.example.com/, b.example.com/ i y.example.com/, mają być przesyłane przy użyciu 4-bajtowych prefiksów haszujących. Ponadto załóżmy, że parametr Ryż, oznaczony symbolem k, ma wartość 30. Serwer zaczyna od obliczenia pełnej wartości hash tych ciągów, które są odpowiednio:

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

Następnie dla każdej z tych wartości serwer tworzy 4-bajtowe prefiksy skrótu, czyli pierwsze 4 bajty z 32-bajtowego pełnego skrótu, interpretowane jako 32-bitowe liczby całkowite. Wielki koniec oznacza fakt, że pierwszy bajt pełnej wartości staje się najważniejszym bajtem w 32-bitowej liczbie całkowitej. Wynikiem tego kroku są liczby całkowite 0x291bc542, 0x1d32c508 i 0xf7a502e5.

Serwer musi posortować te 3 prefiksy leksykograficzne leksykograficznie (odpowiednik sortowania na big endian), a wynik sortowania to 0x1d32c508, 0x291bc542, 0xf7a502e5. Pierwszy prefiks skrótu jest przechowywany w polu first_value bez zmian.

Serwer oblicza następnie 2 sąsiadujące różnice, czyli odpowiednio 0xbe9003a i 0xce893da3. Zakładając, że k ma wartość 30, serwer dzieli te dwie liczby na części ilorazu i pozostałe części o długości odpowiednio 2 i 30 bitów. Dla pierwszej liczby część ilorazu wynosi zero, a reszta to 0xbe9003a. W przypadku drugiej części ilorazu wynosi 3, ponieważ 2 najważniejsze bity to 11 w zapisie dwójkowym, a reszta to 0xe893da3. Dla danego ilorazu q jest on zakodowany w formacie (1 << q) - 1 z użyciem dokładnie 1 + q bitów. Pozostała część jest kodowana bezpośrednio z użyciem k bitów. Część ilorazu pierwszej liczby jest zakodowana jako 0, a reszta ma format binarny 00101111101001000000000111010. Iloraz drugiej liczby jest zakodowany jako 0111, a reszta to 00111010101010.

Gdy te liczby są złożone w ciąg bajtów, używany jest mały znacznik endian. Łatwiej jest sobie wyobrazić tworzenie długiego ciągu bitów, zaczynając od najmniej istotnych bitów: wybieramy część ilorazu pierwszej liczby i dodajemy na początku pozostałą część pierwszej liczby. Następnie dodajemy na początku iloraz części drugiej liczby i części pozostałej na początku. Z tego powodu możesz uzyskać bardzo dużo wyników poniżej (w celu uniknięcia wątpliwości: podziały wierszy i komentarze):

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

Napisane w jednym wierszu:

00111010001001001111011010001101110010111110100100000000001110100

Oczywiście ta liczba znacznie przekracza limit 8 bitów dostępnych w jednym bajcie. Małe kodowanie endian bierze następnie najmniej istotne 8 bitów z tej liczby i przesyła jako pierwszy bajt, czyli 01110100. Aby uniknąć wątpliwości, możemy zgrupować powyższy ciąg znaków w grupy po 8 bitów, zaczynając od najmniej istotnych bitów:

0 01110100 01001001 11101101 00011011 10010111 11010010 00000000 01110100

Małe kodowanie Endian pobiera każdy bajt z prawej strony i umieszcza go w ciągu bajtów:

01110100
00000000
11010010
10010111
00011011
11101101
01001001
01110100
00000000

Widać, że koncepcyjnie prepend nowe części do dużej liczby po lewej stronie (czyli dodajesz więcej istotnych bitów), ale kodujemy od prawej strony (tj. najmniej ważne bity), więc kodowanie i dekodowanie można wykonywać stopniowo.

Dzięki temu uzyskamy

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

Klient wykonuje po prostu te same czynności opisane powyżej, aby zdekodować prefiksy skrótu. W przeciwieństwie do wersji 4 nie trzeba zmieniać bajtów na końcu, ponieważ liczby całkowite prefiksu skrótu są interpretowane jako „wielkie końce”.

Dekodowanie indeksów usuwania

Indeksy usuwania są kodowane dokładnie w ten sam sposób co powyżej, przy użyciu 32-bitowych liczb całkowitych. Kodowanie i dekodowanie indeksów usuwania nie uległo zmianie między wersjami 4 i 5.

Dostępne listy

W wersji 5alfa1 zalecamy stosowanie tych list:

Nazwa listy Odpowiadające jej wyliczenie w wersji 4 ThreatType Opis
gc Brak To jest lista globalnej pamięci podręcznej. Jest to specjalna lista używana tylko w trybie czasu rzeczywistego.
se SOCIAL_ENGINEERING Ta lista zawiera zagrożenia typu SOCIAL_ENGINEERING.
mw MALWARE Ta lista zawiera zagrożenia typu MALWARE na platformach komputerowych.
uws UNWANTED_SOFTWARE Ta lista zawiera zagrożenia typu UNWANTED_SOFTWARE na platformach komputerowych.
uwsa UNWANTED_SOFTWARE Ta lista zawiera zagrożenia typu UNWANTED_SOFTWARE na platformach Android.
pha POTENTIALLY_HARMFUL_APPLICATION Ta lista zawiera zagrożenia typu POTENTIALLY_HARMFUL_APPLICATION na platformach Androida.

W późniejszym czasie udostępnimy dodatkowe listy, co spowoduje rozszerzenie powyższej tabeli.

Klient może używać serwera proxy buforowania, który pobiera niektóre lub wszystkie z powyższych list, a następnie umożliwia klientowi kontakt z serwerem proxy. Jeśli tak jest, zalecamy krótki czas przechowywania w pamięci podręcznej, na przykład 5 minut. W przyszłości czas ten można przekazywać za pomocą standardowego nagłówka HTTP Cache-Control.

Częstotliwość aktualizacji

Klient powinien sprawdzić wartość zwrócona przez serwer w polu minimum_wait_duration i wykorzystać ją do zaplanowania następnej aktualizacji bazy danych. Możliwe, że ta wartość wynosi zero (pole minimum_wait_duration jest całkowicie puste). W takim przypadku klient POWINIEN natychmiast przeprowadzić kolejną aktualizację.

Przykładowe żądania

W tej sekcji opisujemy kilka przykładów bezpośredniego używania interfejsu API HTTP do uzyskiwania dostępu do Bezpiecznego przeglądania Google. Ogólnie zalecamy użycie wygenerowanego wiązania języka, ponieważ obsługuje ono automatyczne kodowanie i dekodowanie w wygodny sposób. Zapoznaj się z dokumentacją dotyczącą tego powiązania.

Oto przykładowe żądanie HTTP użyte przy użyciu metody hashes.search:

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

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

Oto przykładowe żądanie HTTP z metodą hashLists.batchGet:

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

Treść odpowiedzi to ładunek sformatowany z buforem protokołu, który możesz potem zdekodować.

Przewodnik po migracji

Jeśli obecnie używasz interfejsu API aktualizacji w wersji 4, dostępna jest płynna ścieżka migracji z wersji 4 do wersji 5 bez konieczności resetowania ani usuwania lokalnej bazy danych. Instrukcje znajdziesz w tej sekcji.

Konwertuję aktualizacje listy

W wersji 4 do pobierania list należałoby użyć metody ThreatListUpdates.fetch. W wersji 5 należy użyć metody hashLists.batchGet.

W żądaniu należy wprowadzić te zmiany:

  1. Usuń całkowicie obiekt ClientInfo w wersji 4. Zamiast podawać identyfikator klienta w specjalnym polu, wystarczy użyć dobrze znanego nagłówka User-Agent. Nie ma określonego formatu podawania identyfikatora klienta w tym nagłówku, ale zalecamy dodanie oryginalnego identyfikatora klienta i wersji klienta, rozdzielonych spacją lub ukośnikiem.
  2. Dla każdego obiektu ListUpdateRequest w wersji 4:
    • Wyszukaj odpowiednią nazwę listy wersji 5 w tabeli powyżej i podaj ją w żądaniu wersji 5.
    • Usuń niepotrzebne pola, np. threat_entry_type lub platform_type.
    • Pole state w wersji 4 jest bezpośrednio zgodne z polem versions w wersji 5. Ten sam ciąg bajtów, który zostałby wysłany do serwera za pomocą pola state w wersji 4, można po prostu przesłać w wersji 5 za pomocą pola versions.
    • W przypadku ograniczeń wersji 4 używana jest wersja uproszczona o nazwie SizeConstraints. Dodatkowe pola, takie jak region, należy usunąć.

W odpowiedzi należy wprowadzić te zmiany:

  1. Wyliczenie ResponseType w wersji 4 zostało po prostu zastąpione polem wartości logicznej partial_update.
  2. Pole minimum_wait_duration może mieć wartość 0 lub być pominięte. Jeśli tak, klient zostanie natychmiast poproszony o natychmiastowe przesłanie kolejnej. Dzieje się tak tylko wtedy, gdy klient określa w SizeConstraints mniejsze ograniczenie rozmiaru aktualizacji niż maksymalny rozmiar bazy danych.
  3. Należy dostosować algorytm dekodowania 32-bitowych liczb całkowitych. Różnica polega na tym, że zakodowane dane są kodowane z innym zakończeniem. Zarówno w wersjach 4, jak i 5 32-bitowe prefiksy skrótu są sortowane leksykograficznie. Jednak w wersji 4 te prefiksy są posortowane jako małe Endian, a w wersji 5 – jak te posortowane. Oznacza to, że klient nie musi niczego sortować, ponieważ sortowanie leksykograficzne jest identyczne z sortowaniem liczbowym na końcu z wielkimi literami. Tego typu przykład w implementacji Chromium w wersji 4 znajdziesz tutaj. Takie sortowanie można usunąć.
  4. W przypadku innych długości haszowania należy zastosować algorytm dekodowania ryżu.

Konwertowanie wyszukiwań za pomocą haszy

W wersji 4 do uzyskania pełnych haszów należałoby użyć metody fullHashes.find. Odpowiednikiem w wersji 5 jest metoda hashes.search.

W żądaniu należy wprowadzić te zmiany:

  1. Utwórz strukturę kodu tak, aby wysyłać tylko prefiksy skrótu o długości dokładnie 4 bajtów.
  2. Usuń całkowicie obiekty ClientInfo w wersji 4. Zamiast podawać identyfikator klienta w specjalnym polu, wystarczy użyć dobrze znanego nagłówka User-Agent. Nie ma określonego formatu podawania identyfikatora klienta w tym nagłówku, ale zalecamy dodanie oryginalnego identyfikatora klienta i wersji klienta, rozdzielonych spacją lub ukośnikiem.
  3. Usuń pole client_states. Już nie jest to konieczne.
  4. Nie musisz już uwzględniać pól threat_types ani podobnych pól.

W odpowiedzi należy wprowadzić te zmiany:

  1. Pole minimum_wait_duration zostało usunięte. W razie potrzeby klient może przesłać nową prośbę.
  2. Obiekt ThreatMatch w wersji 4 został uproszczony do formatu FullHash.
  3. Buforowanie zostało uproszczone do pojedynczego czasu trwania pamięci podręcznej. Zapoznaj się z powyższymi procedurami interakcji z pamięcią podręczną.