Ta strona została przetłumaczona przez Cloud Translation API.

Overview

Wstęp

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

Bezpieczne przeglądanie Google w wersji 5 to ewolucja Bezpiecznego przeglądania Google w wersji 4. Dwie główne zmiany wprowadzone w wersji 5 to częstotliwość aktualizacji danych i prywatność adresów IP. Dodatkowo ulepszyliśmy interfejs API, aby zwiększyć elastyczność i wydajność oraz ograniczyć zwielokrotnienie. Ponadto Bezpieczne przeglądanie Google w wersji 5 zostało zaprojektowane tak, aby ułatwić migrację z wersji 4.

Obecnie Google oferuje wersje 4 i 5, które są uznawane za gotowe do wdrożenia. Możesz użyć wersji 4 lub 5. Nie ogłosiliśmy daty wycofania wersji 4. Jeśli to zrobimy, powiadomimy Cię o tym z co najmniej rocznym wyprzedzeniem. Na tej stronie znajdziesz opis wersji 5 oraz przewodnik po migracji z wersji 4 do 5. Pełna dokumentacja wersji 4 jest dostępna.

Aktualność danych

Ważną zaletą Bezpiecznego przeglądania Google w wersji 5 w porównaniu z wersją 4 (a konkretnie interfejsem API do aktualizacji wersji 4) jest częstotliwość i zasięg danych. Ochrona w dużym stopniu zależy od lokalnej bazy danych zarządzanej przez klienta, dlatego opóźnienie i rozmiar aktualizacji lokalnej bazy danych są głównym powodem braku zabezpieczenia. W wersji 4 typowy klient potrzebuje od 20 do 50 minut na uzyskanie najnowszej wersji list zagrożeń. Niestety ataki phishingowe rozprzestrzeniają się szybko: według danych z 2021 roku 60% stron przeprowadzających ataki trwa krócej niż 10 minut. Nasze analizy pokazują, że około 25-30% przypadków braku ochrony przed wyłudzaniem informacji wynika z braku aktualizacji danych. Niektóre urządzenia nie są przystosowane do zarządzania wszystkimi listami zagrożeń Bezpiecznego przeglądania Google, które z czasem powiększają się.

W wersji 5 wprowadzamy tryb działania nazywany ochroną w czasie rzeczywistym. Pozwala to uniknąć powyższego problemu z brakiem aktualizacji danych. W wersji 4 klienty muszą pobrać i obsługiwać lokalną bazę danych, przeprowadzać testy pod kątem pobranych lokalnie list zagrożeń, a w przypadku częściowego dopasowania prefiksu wysyłać żądanie pobrania pełnego hasz. W wersji 5, chociaż klienci powinni nadal pobierać i utrzymywać lokalną bazę danych list zagrożeń, oczekuje się też, że pobiorą listę prawdopodobnie niegroźnych witryn (tzw. globalną pamięć podręczną), przeprowadź zarówno kontrolę lokalną, jak i lokalną listę zagrożeń, a na koniec, gdy znajdziemy częściowe dopasowanie prefiksu do list zagrożeń lub zapytanie o brak zgodności w globalnej pamięci podręcznej, wykonaj żądanie. Szczegółowe informacje o lokalnym przetwarzaniu wymaganym przez klienta znajdziesz w poniższej procedurze. Oznacza to zmianę trybu zezwalania na sprawdzanie domyślne, co może poprawić ochronę w świetle szybszego rozprzestrzeniania się zagrożeń w internecie. Inaczej mówiąc, ten protokół został zaprojektowany z myślą o ochronie w czasie zbliżonym do rzeczywistego. Naszym celem jest zapewnienie klientom dostępu do aktualnych danych Bezpiecznego przeglądania Google.

Ochrona prywatności

Bezpieczne przeglądanie Google (w wersji 4 lub 5) nie przetwarza niczego, co jest powiązane z tożsamością użytkownika, podczas obsługi żądań. Pliki cookie (jeśli zostaną wysłane) są ignorowane. Źródłowe adresy IP żądań są znane Google, ale Google używa tych adresów tylko do niezbędnych celów sieciowych (np. do wysyłania odpowiedzi) oraz do celów anty-DoS.

Równocześnie z wersją 5 wprowadzamy dodatkowy interfejs API o nazwie Safe Przeglądanie Oblivious HTTP Gateway API. Protokół Oblivious HTTP (Oblivious HTTP) ukrywa adresy IP użytkowników przed Google. Polega to na tym, że inna firma zewnętrzna obsługuje zaszyfrowaną wersję żądania użytkownika, a następnie przekazuje ją do Google. Firma zewnętrzna ma więc dostęp tylko do adresów IP, a Google ma dostęp wyłącznie do treści żądania. Firma zewnętrzna obsługuje usługę Oblivious HTTP Relay (na przykład tę usługę firmy Fastly), a Google obsługuje bramę Oblivious HTTP. Jest to opcjonalny interfejs API towarzyszący. W połączeniu z funkcją Bezpieczne przeglądanie Google adresy IP użytkowników nie są już wysyłane do Google.

Odpowiednie wykorzystanie

Dozwolone użycie

Interfejs Safe Przeglądanie API jest przeznaczony tylko do użytku niekomercyjnego (czyli nie służy do sprzedaży ani generowania przychodów). Jeśli potrzebujesz rozwiązania do celów komercyjnych, przeczytaj artykuł Web Risk.

Ceny

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

Limity

Po włączeniu interfejsu API Bezpiecznego przeglądania deweloperzy otrzymują domyślny limit wykorzystania. Informacje o obecnym przydziałie i wykorzystaniu możesz sprawdzić w Google Developer Console. Jeśli spodziewasz się wykorzystania większego limitu niż obecnie, możesz poprosić o zwiększenie limitu w interfejsie limitów w Konsoli programisty. Rozpatrujemy te prośby i przed złożeniem wniosku o zwiększenie limitu wymagamy kontaktu, aby mieć pewność, że dostępność naszej usługi spełnia potrzeby wszystkich użytkowników.

Odpowiednie adresy URL

Bezpieczne przeglądanie Google zostało zaprojektowane z myślą o działaniu na adresach 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órego odwołuje się plik HTML, czy adres URL WebSocket zainicjowany przez JavaScript). Takie adresy URL zasobów podrzędnych nie powinny być sprawdzane pod kątem Bezpiecznego przeglądania Google.

Jeśli po odwiedzeniu adresu URL następuje przekierowanie (np. HTTP 301), należy sprawdzić, czy adres URL przekierowania jest dostępny w ramach funkcji Bezpieczne przeglądanie Google. Manipulacja adresami URL po stronie klienta (taka jak History.pushState) nie powoduje, że nowe adresy URL będą sprawdzane przez Bezpieczne przeglądanie Google.

Ostrzeżenia użytkownika

Jeśli używasz usługi Bezpieczne przeglądanie Google do ostrzegania użytkowników o zagrożeniach, jakie mogą wystąpić na konkretnych stronach internetowych, obowiązują Cię następujące wytyczne.

Te wytyczne pomagają chronić Ciebie i Google przed nieporozumieniami, wyjaśniając, że strona nie jest w 100% prawdopodobna jako niebezpieczny zasób internetowy, a ostrzeżenia tylko wskazują na potencjalne ryzyko.

W widocznym dla użytkowników ostrzeżeniu nie wolno sugerować użytkownikom, że strona, której dotyczy zgłoszenie, jest bez wątpienia niebezpieczna. W przypadku zidentyfikowanej strony lub potencjalnego zagrożenia, jakie może ona stanowić dla użytkowników, należy sformułować ostrzeżenie, używając takich określeń jak: „podejrzenie”, „potencjalnie”, „możliwe”, „prawdopodobne” może być takie jak:
Ostrzeżenie musi umożliwiać użytkownikowi zapoznanie się z definicją różnych zagrożeń określoną przez Google. Zalecamy skorzystanie z tych linków:
- Inżynieria społeczna: https://developers.google.com/search/docs/monitor-debug/security/social-engineering
- Złośliwe i niechciane oprogramowanie: https://developers.google.com/search/docs/monitor-debug/security/malware
- Potencjalnie szkodliwe aplikacje (tylko na Androidzie): https://developers.google.com/android/play-protect/potentially-harmful-applications.
Jeśli wyświetlasz ostrzeżenia o stronach zidentyfikowanych przez usługę Bezpieczne przeglądanie jako niebezpieczne, musisz podać informacje o swojej firmie Google, dodając wiersz „Porada Google” wraz z linkiem do Zalecenia Bezpiecznego przeglądania. Jeśli Twój produkt wyświetla też ostrzeżenia dotyczące innych źródeł, nie możesz uwzględniać atrybucji Google w ostrzeżeniach pochodzących z danych spoza Google.
W dokumentacji produktu należy umieścić powiadomienie informujące użytkowników, że ochrona oferowana przez Bezpieczne przeglądanie Google nie jest idealna. Należy poinformować go, że istnieje ryzyko zarówno wyników fałszywie pozytywnych (bezpieczne witryny oznaczone jako niebezpieczne), jak i fałszywych negatywnych (niebezpieczne witryny, które nie zostały oznaczone). Zalecamy użycie następującego języka:

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

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 klienci decydują się na używanie Bezpiecznego przeglądania Google w wersji 5 w trybie rzeczywistym, będą utrzymywać w swojej lokalnej bazie danych: (i) globalną pamięć podręczną prawdopodobnie niegroźnych witryn w postaci haszów SHA256 wyrażeń z adresem URL hosta/sufiksu ścieżki z prefiksami ścieżki, (ii) zestawu wyrażeń o zagrożeniach w postaci przedrostków SHA256 prefiksów adresu URL hosta/prefiksu ścieżki. Ogólnie rzecz biorąc, za każdym razem, gdy klient chce sprawdzić konkretny adres URL, wykonywane jest lokalne sprawdzenie z użyciem globalnej pamięci podręcznej. Jeśli weryfikacja przebiegnie pomyślnie, zostanie przeprowadzone lokalne sprawdzenie listy zagrożeń. W przeciwnym razie klient kontynuuje sprawdzanie haszowania w czasie rzeczywistym zgodnie z opisem poniżej.

Oprócz lokalnej bazy danych klient zachowuje lokalną pamięć podręczną. Taka lokalna pamięć podręczna nie musi znajdować się w pamięci trwałej i może zostać wyczyszczona w przypadku braku pamięci.

Szczegółowa specyfikacja procedury jest dostępna poniżej.

Tryb listy lokalnej

Gdy klienci używają w tym trybie Bezpiecznego przeglądania Google w wersji 5, zachowanie klienta jest podobne do interfejsu API aktualizacji w wersji 4, z wyjątkiem używania ulepszonej platformy API w wersji 5. Klienty będą utrzymywać w lokalnej bazie danych zestaw list zagrożeń w postaci prefiksów skrótu SHA256 wyrażeń z adresem URL sufiksu hosta/prefiksu ścieżki. Gdy klient chce sprawdzić konkretny URL, przeprowadzana jest kontrola przy użyciu lokalnej listy zagrożeń. W przypadku wystąpienia dopasowania klient łączy się z serwerem, aby kontynuować sprawdzanie.

Podobnie jak wyżej, klient przechowuje również lokalną pamięć podręczną, która nie musi być przechowywana w pamięci trwałej.

Tryb czasu rzeczywistego bez miejsca na dane

Jeśli klienci używają Bezpiecznego przeglądania Google w wersji 5 w trybie rzeczywistym bez pamięci, nie muszą utrzymywać żadnej lokalnej bazy danych. Za każdym razem, gdy klient chce sprawdzić określony URL, łączy się z serwerem w celu przeprowadzenia sprawdzenia. Ten tryb jest podobny do tego, który mogą implementować klienty interfejsu Lookup API w wersji 4.

Sprawdzam adresy URL

Ta sekcja zawiera szczegółowe instrukcje sprawdzania adresów URL przez klientów.

Stosowanie kanonicznych adresów URL

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

Na początek zakładamy, że klient przeanalizował adres URL i uznał go za prawidłowy zgodnie ze standardem RFC 2396. Jeśli adres URL zawiera międzynarodową nazwę domeny (IDN), klient powinien przekonwertować adres URL na reprezentację ASCII Punycode. Adres URL musi zawierać komponent ścieżki, czyli po domenie musi mieć 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ń go. Na przykład skróć http://google.com/#frag do http://google.com/.

Po trzecie, wielokrotnie za pomocą procentu usuwaj zmiany znaczenia w adresie URL, aż nie będzie już trwałych znaków zmiany znaczenia. (W związku z tym adres URL może być nieprawidłowy).

Aby skonwertować nazwę hosta do postaci kanonicznej:

Wyodrębnij z adresu URL nazwę hosta, a następnie:

Usuń wszystkie początkowe i końcowe kropki.
Zastąp kolejne kropki pojedynczą kropką.
Jeśli nazwę hosta można przetworzyć jako adres IPv4, znormalizuj ją do 4 wartości dziesiętnych oddzielonych kropkami. Klient powinien obsługiwać każde zgodne z prawem kodowanie adresu IP, w tym ósemkowe, szesnastkowe i mniej niż 4 komponenty.
Jeśli nazwę hosta można przeanalizować jako adres IPv6 w nawiasie, znormalizuj ją, usuwając zbędne początkowe zera ze składników i zwijając zero komponentów przy użyciu składni dwukropka. Na przykład wartość [2001:0db8:0000::1] należy przekształcić w element [2001:db8::1]. Jeśli nazwa hosta jest jednym z 2 wymienionych poniżej specjalnych typów adresów IPv6, przekształć je na IPv4:
- Adres IPv6 zmapowany 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, np. [64:ff9b::1.2.3.4], który należy przekształcić na 1.2.3.4.
Zapisuj cały ciąg małymi literami.

Aby skonwertować ścieżkę kanoniczną:

Rozwiąż w ścieżce sekwencje /../ i /./, zastępując fragment /./ wartością / i usuwając element /../ wraz z poprzednim komponentem ścieżki.
Zastąp uruchomienia kolejnych ukośników pojedynczym znakiem ukośnika.

Nie stosuj tych konwertowań kanonicznych do parametrów zapytania.

W adresie URL użyj funkcji ucieczki za pomocą procenta do wszystkich znaków, które są znakami <= ASCII 32, >= 127, # lub %. Znaki szesnastkowe powinny być pisane wielkimi literami.

Wyrażenia prefiksu ścieżki sufiksu hosta

Po przekształceniu adresu kanonicznego możesz utworzyć wyrażenia z sufiksem i prefiksem. 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 możliwych kombinacji sufiksu hosta i prefiksu ścieżki. Te kombinacje korzystają tylko z komponentów 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 1 kombinacja będzie zawierać pełną ścieżkę i parametry zapytania.

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

Jeśli nazwa hosta nie jest literałem IPv4 lub IPv6, możesz utworzyć maksymalnie 4 nazwy hostów, rozpoczynając od domeny eTLD + 1 i dodając kolejne wiodące komponenty. Identyfikator eTLD + 1 należy określić na podstawie listy domen publicznych. Na przykład w wyniku działania a.b.example.com powstanie domena eTLD + 1 o nazwie example.com oraz host z jednym dodatkowym komponentem hosta (b.example.com).
Dokładna nazwa hosta w adresie URL. Zgodnie z poprzednim przykładem sprawdzana będzie wartość a.b.example.com.

W przypadku ścieżki klient użyje 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 utworzone przez zaczynanie w punkcie początkowym (/) i stopniowo dołączanie komponentów ścieżki, łącznie z końcowym ukośnikiem.

Poniższe przykłady ilustrują działanie funkcji sprawdzania:

W przypadku adresu URL http://a.b.com/1/2.html?param=1 klient użyje tych możliwych ciągów:

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 użyje tych możliwych ciągów:

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ż weźmiemy tylko 5 ostatnich komponentów nazwy hosta i pełną nazwę hosta).

W przypadku adresu URL http://1.2.3.4/1/ klient użyje tych możliwych ciągów:

1.2.3.4/1/
1.2.3.4/

W przypadku adresu URL http://example.co.uk/1 klient użyje tych możliwych ciągów:

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

Haszowanie

Bezpieczne przeglądanie Google używa wyłącznie SHA256 jako funkcji skrótu. Ta funkcja skrótu powinna zostać zastosowana do powyższych wyrażeń.

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

Podczas korzystania z metody hashes.search wymagamy, aby hasze w żądaniu były skracane do dokładnie 4 bajtów. Wysyłanie dodatkowych bajtów w tym żądaniu narusza prywatność użytkowników.
W przypadku pobierania list dla lokalnej bazy danych za pomocą metody hashList.get lub metody hashLists.batchGet na długość skrótów wysyłanych przez serwer zależy zarówno od charakteru listy, jak i preferencji klienta dotyczącej długości skrótu, przekazywanej za pomocą parametru desired_hash_length.

Procedura sprawdzania adresu URL w czasie rzeczywistym

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

Ta procedura pobiera pojedynczy adres URL u i zwraca SAFE, UNSAFE lub UNSURE. Jeśli zwraca wartość SAFE, Bezpieczne przeglądanie Google uzna adres URL za bezpieczny. Jeśli zwraca wartość UNSAFE, usługa Bezpieczne przeglądanie Google uzna adres URL za potencjalnie niebezpieczny. W takiej sytuacji należy podjąć odpowiednie działania, takie jak wyświetlenie ostrzeżenia użytkownikowi, przeniesienie otrzymanej wiadomości do folderu ze spamem lub żądanie od użytkownika dodatkowego potwierdzenia przed kontynuacją. Jeśli zwraca wartość UNSURE, należy wykonać poniższą procedurę kontroli lokalnej.

Niech expressions będzie listą wyrażeń z sufiksem/prefiksem wygenerowanymi przez adres URL u.
Niech expressionHashes będzie listą, w której elementy to hasze SHA256 wszystkich wyrażeń w komponencie expressions.
Dla każdej wartości w kolumnie hash elementu expressionHashes:
1. Jeśli plik hash można znaleźć w globalnej pamięci podręcznej, zwróć UNSURE.
Niech expressionHashPrefixes będzie listą, w której elementy to pierwsze 4 bajty każdego skrótu w funkcji expressionHashes.
Dla każdej wartości w kolumnie expressionHashPrefix elementu expressionHashPrefixes:
1. Wyszukaj expressionHashPrefix w lokalnej pamięci podręcznej.
2. Jeśli zostanie znaleziony wpis w pamięci podręcznej:
  1. Ustal, czy bieżący czas jest późniejszy niż czas wygaśnięcia.
  2. Jeśli jest większa:
    1. Usuń znaleziony wpis z lokalnej pamięci podręcznej.
    2. Kontynuuj pętlę.
  3. Jeśli nie jest większa:
    1. Usuń ten konkretny element (expressionHashPrefix) z witryny expressionHashPrefixes.
    2. Sprawdź, czy we wpisie w pamięci podręcznej znajduje się odpowiedni pełny hasz w elemencie expressionHashes.
    3. Jeśli je znajdziesz, zwróć UNSAFE.
    4. Jeśli nie zostanie znaleziony, kontynuuj pętlę.
3. Jeśli nie znaleziono wpisu w pamięci podręcznej, kontynuuj pętlę.
Wyślij expressionHashPrefixes do serwera Bezpiecznego przeglądania Google w wersji 5, używając haszów wyszukiwania RPC lub metody REST hashes.search. Jeśli wystąpił błąd (w tym błędy sieci, błędy HTTP itp.), zwróć UNSURE. W przeciwnym razie niech odpowiedź to response otrzymana z serwera SB, która jest listą pełnych haszów wraz z informacjami pomocniczymi identyfikującymi charakter zagrożenia (inżynierią społeczną, złośliwym oprogramowaniem itp.) oraz okresem ważności pamięci podręcznej (expiration).
Dla każdej wartości w kolumnie fullHash elementu response:
1. Wstaw plik fullHash do lokalnej pamięci podręcznej razem z expiration.
Dla każdej wartości w kolumnie fullHash elementu response:
1. Niech isFound będzie wynikiem znalezionych elementów fullHash w tabeli expressionHashes.
2. Jeśli isFound ma wartość Fałsz, kontynuuj pętlę.
3. Jeśli isFound ma wartość Prawda, zwraca UNSAFE.
Zwróć SAFE.

Procedura sprawdzania adresu URL listy zagrożeń lokalnych

Ta procedura jest używana, gdy klient zdecyduje się na tryb działania listy lokalnej. Jest ona też używana, gdy klient, korzystając z powyższej procedury RealTimeCheck, zwraca wartość UNSURE.

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

Niech expressions będzie listą wyrażeń z sufiksem/prefiksem wygenerowanymi przez adres URL u.
Niech expressionHashes będzie listą, w której elementy to hasze SHA256 wszystkich wyrażeń w komponencie expressions.
Niech expressionHashPrefixes będzie listą, w której elementy to pierwsze 4 bajty każdego skrótu w funkcji expressionHashes.
Dla każdej wartości w kolumnie expressionHashPrefix elementu expressionHashPrefixes:
1. Wyszukaj expressionHashPrefix w lokalnej pamięci podręcznej.
2. Jeśli zostanie znaleziony wpis w pamięci podręcznej:
  1. Ustal, czy bieżący czas jest późniejszy niż czas wygaśnięcia.
  2. Jeśli jest większa:
    1. Usuń znaleziony wpis z lokalnej pamięci podręcznej.
    2. Kontynuuj pętlę.
  3. Jeśli nie jest większa:
    1. Usuń ten konkretny element (expressionHashPrefix) z witryny expressionHashPrefixes.
    2. Sprawdź, czy we wpisie w pamięci podręcznej znajduje się odpowiedni pełny hasz w elemencie expressionHashes.
    3. Jeśli je znajdziesz, zwróć UNSAFE.
    4. Jeśli nie zostanie znaleziony, kontynuuj pętlę.
3. Jeśli nie znaleziono wpisu w pamięci podręcznej, kontynuuj pętlę.
Dla każdej wartości w kolumnie expressionHashPrefix elementu expressionHashPrefixes:
1. Wyszukaj expressionHashPrefix w lokalnej bazie danych z listą zagrożeń.
2. Jeśli nie można znaleźć obiektu expressionHashPrefix w lokalnej bazie danych listy zagrożeń, usuń go z tabeli expressionHashPrefixes.
Wyślij expressionHashPrefixes do serwera Bezpiecznego przeglądania Google w wersji 5, używając haszów wyszukiwania RPC lub metody REST hashes.search. Jeśli wystąpił błąd (w tym błędy sieci, błędy HTTP itp.), zwróć SAFE. W przeciwnym razie niech odpowiedź to response otrzymana z serwera SB, która jest listą pełnych haszów wraz z informacjami pomocniczymi identyfikującymi charakter zagrożenia (inżynierią społeczną, złośliwym oprogramowaniem itp.) oraz okresem ważności pamięci podręcznej (expiration).
Dla każdej wartości w kolumnie fullHash elementu response:
1. Wstaw plik fullHash do lokalnej pamięci podręcznej razem z expiration.
Dla każdej wartości w kolumnie fullHash elementu response:
1. Niech isFound będzie wynikiem znalezionych elementów fullHash w tabeli expressionHashes.
2. Jeśli isFound ma wartość Fałsz, kontynuuj pętlę.
3. Jeśli isFound ma wartość Prawda, zwraca UNSAFE.
Zwróć SAFE.

Procedura sprawdzania adresu URL w czasie rzeczywistym bez lokalnej bazy danych

Ta procedura jest używana, gdy klient wybierze tryb działania w czasie rzeczywistym bez pamięci masowej.

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

Niech expressions będzie listą wyrażeń z sufiksem/prefiksem wygenerowanymi przez adres URL u.
Niech expressionHashes będzie listą, w której elementy to hasze SHA256 wszystkich wyrażeń w komponencie expressions.
Niech expressionHashPrefixes będzie listą, w której elementy to pierwsze 4 bajty każdego skrótu w funkcji expressionHashes.
Dla każdej wartości w kolumnie expressionHashPrefix elementu expressionHashPrefixes:
1. Wyszukaj expressionHashPrefix w lokalnej pamięci podręcznej.
2. Jeśli zostanie znaleziony wpis w pamięci podręcznej:
  1. Ustal, czy bieżący czas jest późniejszy niż czas wygaśnięcia.
  2. Jeśli jest większa:
    1. Usuń znaleziony wpis z lokalnej pamięci podręcznej.
    2. Kontynuuj pętlę.
  3. Jeśli nie jest większa:
    1. Usuń ten konkretny element (expressionHashPrefix) z witryny expressionHashPrefixes.
    2. Sprawdź, czy we wpisie w pamięci podręcznej znajduje się odpowiedni pełny hasz w elemencie expressionHashes.
    3. Jeśli je znajdziesz, zwróć UNSAFE.
    4. Jeśli nie zostanie znaleziony, kontynuuj pętlę.
3. Jeśli nie znaleziono wpisu w pamięci podręcznej, kontynuuj pętlę.
Wyślij expressionHashPrefixes do serwera Bezpiecznego przeglądania Google w wersji 5, używając haszów wyszukiwania RPC lub metody REST hashes.search. Jeśli wystąpił błąd (w tym błędy sieci, błędy HTTP itp.), zwróć SAFE. W przeciwnym razie niech odpowiedź to response otrzymana z serwera SB, która jest listą pełnych haszów wraz z informacjami pomocniczymi identyfikującymi charakter zagrożenia (inżynierią społeczną, złośliwym oprogramowaniem itp.) oraz okresem ważności pamięci podręcznej (expiration).
Dla każdej wartości w kolumnie fullHash elementu response:
1. Wstaw plik fullHash do lokalnej pamięci podręcznej razem z expiration.
Dla każdej wartości w kolumnie fullHash elementu response:
1. Niech isFound będzie wynikiem znalezionych elementów fullHash w tabeli expressionHashes.
2. Jeśli isFound ma wartość Fałsz, kontynuuj pętlę.
3. Jeśli isFound ma wartość Prawda, zwraca UNSAFE.
Zwróć SAFE.

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. Od klienta zależy format i przechowywanie tej lokalnej bazy danych. Zawartość tej lokalnej bazy danych można koncepcyjnie traktować jako folder zawierający różne listy jako pliki, a zawartością tych plików są hasze SHA256 lub prefiksy haszów.

Aktualizacje bazy danych

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

Listy są identyfikowane za pomocą odrębnych nazw. Nazwy są krótkimi ciągami ASCII składającymi się z kilku znaków.

W przeciwieństwie do wersji 4, gdzie listy są identyfikowane przez kropkę typu zagrożenia, typ platformy i typ wpisu o zagrożeniu, na listach w wersji 5 są one po prostu identyfikowane na podstawie nazwy. Zapewnia to elastyczność w sytuacji, gdy wiele list w wersji 5 może współdzielić ten sam typ zagrożenia. W wersji 5 typy platform i wpisy zagrożeń zostały usunięte.

Po wybraniu nazwy dla listy nazwa nie zostanie nigdy zmieniona. Co więcej, wyświetlana lista nigdy nie jest usuwana (jeśli nie jest już przydatna, stanie się pusta, ale będzie nadal istnieć). Dlatego nazwy te można zakodować na stałe w kodzie klienta Bezpiecznego przeglądania Google.

Zarówno metoda hashList.get, jak i hashLists.batchGet obsługują aktualizacje przyrostowe. Aktualizacje przyrostowe pozwalają ograniczyć przepustowość i zwiększyć wydajność. Aktualizacje przyrostowe działają przez dostarczenie różnicy między wersją listy klienta a jej najnowszą wersją. (Jeśli klient został niedawno wdrożony i nie ma dostępnych wersji, dostępna jest pełna aktualizacja). Aktualizacja przyrostowa zawiera indeksy usunięć i dodatki. Oczekuje się, że klient najpierw usunie z lokalnej bazy danych wpisy znajdujące się w określonych indeksach, a następnie zastosuje dodane elementy.

Wreszcie, aby zapobiec uszkodzeniu, klient powinien sprawdzić przechowywane dane pod kątem sumy kontrolnej dostarczonej przez serwer. Gdy suma kontrolna się nie zgadza, klient powinien przeprowadzić pełną aktualizację.

Dekodowanie zawartości listy

Wszystkie listy są dostarczane przy użyciu specjalnego kodowania w celu zmniejszenia rozmiaru. Kodowanie to działa, bo listy Bezpiecznego przeglądania Google zawierają, koncepcyjnie zbiór haszów lub ich prefiksów, których nie można odróżnić od losowych liczb całkowitych. Gdybyśmy posortowali te liczby całkowite i porównali ich sąsiednie różnice, różnica ta będzie w sensie „mała”. Kodowanie Golomb-Rice wykorzystuje tę nieistotność.

Bezpieczne przeglądanie Google w wersji 5 oferuje 4 różne typy obsługi danych 4-bajtowych, 8-bajtowych, 16-bajtowych i 32-bajtowych. Przyjrzyjmy się przykładowi, w którym zakodowane są trzy kolejne po sobie 4-bajtowe liczby całkowite. Niech parametr Rice oznaczony przez k ma wartość 3. Iloczyn kodowania odpowiada po prostu sąsiedniej wartości różnicy przesuniętej w prawo o k bitów. Podane liczby całkowite są następujące po sobie, więc różnica między nimi wynosi 1, a po przesunięciu o 3 bity część ilorazu wynosi 0. Najmniej istotne k bitów to 001. Iloczyn zerowy jest kodowany jako pojedynczy 0 bitów. Pozostała część to 1, a reszta jest zakodowana jako 100. Ten kod jest powtarzany ponownie w celu utworzenia strumienia bitowego 01000100. Powstały strumień bitowy jest zakodowany z użyciem małej wartości endian jako 00100010. Wynika to z tych danych:

rice_parameter: 3
entries_count: 2
encoded_data: "\x22"

Po wykonaniu powyższego etapu dekodowania 32-bitowych liczb całkowitych wynik można wykorzystać bezpośrednio jako indeksy usuwania lub dodawanie. W przeciwieństwie do wersji 4 nie ma potrzeby późniejszego zamiany bajtów.

Dostępne listy

W wersji 5alfa1 zalecamy użycie tych list:

Nazwa listy	Odpowiadające jej wyliczenie (wersja 4): `ThreatType`	Opis
`gc`	Brak	Jest to lista globalnej pamięci podręcznej. Jest to specjalna lista używana tylko w trybie działania w czasie rzeczywistym.
`se`	`SOCIAL_ENGINEERING`	Ta lista zawiera zagrożenia typu SOCIAL_ENGINEERING.
`mw`	`MALWARE`	Ta lista zawiera zagrożenia typu MALWARE dla platform komputerowych.
`uws`	`UNWANTED_SOFTWARE`	Ta lista zawiera zagrożenia typu UNWANTED_SOFTWARE dla platform komputerowych.
`uwsa`	`UNWANTED_SOFTWARE`	Ta lista zawiera zagrożenia typu UNWANTED_SOFTWARE dla platform Android.
`pha`	`POTENTIALLY_HARMFUL_APPLICATION`	Ta lista zawiera zagrożenia typu POTENTIALLY_HARMFUL_APPLICATION na platformach Android.

Dodatkowe listy będą dostępne w późniejszym czasie, po czym poszerzymy powyższą tabelę.

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. Ta wartość może wynosić zero i wtedy klient powinien od razu przeprowadzić kolejną aktualizację.

Przykładowe żądania

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

Oto przykładowe żądanie HTTP z użyciem metody hashes.search:

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

Treść odpowiedzi to ładunek sformatowany w formacie bufora protokołu, który możesz później zdekodować.

Oto przykładowe żądanie HTTP przy użyciu metody hashLists.batchGet:

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

Treść odpowiedzi jest ponownie ładunkiem w formacie bufora protokołu, który możesz później zdekodować.

Przewodnik po migracji

Jeśli obecnie używasz interfejsu API do aktualizacji wersji 4, możesz płynnie przejść z wersji 4 na 5 bez konieczności resetowania ani usuwania lokalnej bazy danych. Z tej sekcji dowiesz się, jak to zrobić.

Konwertuję aktualizacje listy

W wersji 4 do pobierania list służy metodathreatListUpdates.fetch. W wersji 5 trzeba przełączyć się na metodę hashLists.batchGet.

W prośbie należy wprowadzić te zmiany:

Usuń całkowicie obiekt ClientInfo w wersji 4. Zamiast podawać identyfikator klienta w specjalnym polu, użyj dobrze znanego nagłówka User-Agent. Chociaż nie ma określonego formatu, w którym identyfikatory klienta powinny być podawane w tym nagłówku, zalecamy podanie pierwotnego identyfikatora klienta i jego wersji, oddzielając je spacją lub ukośnikiem.
Dla każdego obiektu ListUpdateRequest w wersji 4:
- Odszukaj odpowiednią nazwę listy w wersji 5 w tabeli powyżej i podaj ją w żądaniu w wersji 5.
- Usuń niepotrzebne pola, takie jak threat_entry_type czy 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że zostać po prostu wysłany w wersji 5 za pomocą pola versions.
- W przypadku ograniczeń wersji 4 wersja 5 używa uproszczonej wersji o nazwie SizeConstraints. Pola dodatkowe, takie jak region, powinny zostać pominięte.

W odpowiedzi musisz wprowadzić te zmiany:

Wyliczenie ResponseType wersji 4 zostało po prostu zastąpione polem wartości logicznej o nazwie partial_update.
Pole minimum_wait_duration może mieć wartość zero lub być pominięte. Jeśli tak, klient zostanie poproszony o natychmiastowe wysłanie kolejnego żądania. Dzieje się tak tylko wtedy, gdy klient określi w elemencie SizeConstraints ograniczenie maksymalnego rozmiaru aktualizacji niż maksymalny rozmiar bazy danych.
Trzeba będzie zmienić algorytm dekodowania 32-bitowych liczb całkowitych. Różnica polega na tym, że dane są kodowane z inną metodą endian. Zarówno w wersji 4, jak i 5 32-bitowe prefiksy skrótów są sortowane leksykograficznie. W wersji 4 prefiksy te są posortowane jako małe wyrazy endian, natomiast w wersji 5 są one po posortowane jako big endian. Oznacza to, że klient nie musi wykonywać żadnego sortowania, ponieważ sortowanie leksykograficzne jest takie samo jak sortowanie numeryczne z wykorzystaniem big endian. Przykłady tego rodzaju w Chromium w wersji 4 znajdziesz tutaj. Takie sortowanie można usunąć.
W przypadku innych długości haszowania trzeba wdrożyć algorytm dekodowania ryżu.

Konwersja wyszukiwań haszowanych

W wersji 4 można użyć metody fullHashes.find, aby uzyskać pełne hasze. Odpowiednią metodą w wersji 5 jest metoda hashes.search.

W prośbie należy wprowadzić te zmiany:

Utwórz taką strukturę kodu, aby wysyłać tylko prefiksy haszujące o długości dokładnie 4 bajtów.
Usuń całkowicie obiekty ClientInfo w wersji 4. Zamiast podawać identyfikator klienta w specjalnym polu, użyj dobrze znanego nagłówka User-Agent. Chociaż nie ma określonego formatu, w którym identyfikatory klienta powinny być podawane w tym nagłówku, zalecamy podanie pierwotnego identyfikatora klienta i jego wersji, oddzielając je spacją lub ukośnikiem.
Usuń pole client_states. Nie jest już potrzebna.
Nie trzeba już uwzględniać pola threat_types ani podobnych.

W odpowiedzi musisz wprowadzić te zmiany:

Pole minimum_wait_duration zostało usunięte. W razie potrzeby klient może zawsze wysłać nowe żądanie.
Obiekt ThreatMatch w wersji 4 został uproszczony do formatu FullHash.
Pamięć podręczna została uproszczona do jednego czasu trwania pamięci podręcznej. Zapoznaj się z powyższymi procedurami dotyczącymi korzystania z pamięci podręcznej.