Pamięć podręczna

Ten dokument obejmuje następujące metody:

• Lookup API (v4): threatMATCH.find.
• Zaktualizuj interfejs API (wersja 4): fullHashes.find

Informacje o pamięci podręcznej

Aby zmniejszyć wykorzystanie przepustowości klienta i chronić Google przed gwałtownymi skokami ruchu, klienci zarówno interfejsu Lookup API, jak i Update API muszą utworzyć i przechowywać lokalną pamięć podręczną z danymi zagrożeń. W przypadku interfejsu Lookup API pamięć podręczna służy do zmniejszenia liczby żądań threatMatches wysyłanych przez klientów do Google. W przypadku interfejsu API aktualizacji pamięć podręczna służy do zmniejszenia liczby żądań fullHashes wysyłanych przez klientów do Google. Protokół buforowania każdego interfejsu API został opisany poniżej.

Lookup API

Klienty interfejsu API Lookup powinny przechowywać w pamięci podręcznej każdy zwracany element ThreatMatch przez czas zdefiniowany w polu cacheDuration. Następnie klienci muszą sprawdzić pamięć podręczną przed wysłaniem kolejnego żądania threatMatches do serwera. Jeśli czas przechowywania w pamięci podręcznej danych zwróconych wcześniej ThreatMatch nie minął, klient powinien uznać, że element nadal jest niebezpieczny. Buforowanie ThreatMatch elementów może zmniejszyć liczbę żądań do interfejsu API wysyłanych przez klienta.

Przykład: ThreatMATCH.find

Kliknij link żądania i odpowiedzi w nagłówku tabeli, aby zobaczyć pełne przykłady.

Sprawdzanie adresu URL Żądanie threatMATCH	Dopasowanie adresu URL odpowiedź ThreatMATCH	Przechowywanie w pamięci podręcznej
"threatEntries": [ {"url": "http://www.urltocheck.org/"} ]	"matches": [{ "threat": {"url": "http://www.urltocheck.org/"}, "cacheDuration": "300.000s" }]	Dopasowanie. Klient musi odczekać 5 minut, zanim wyśle nowe żądanie threatMatches z adresem URL http://www.urltocheck.org/.

Zaktualizuj interfejs API

Aby zmniejszyć łączną liczbę żądań fullHashes wysyłanych do Google przy użyciu interfejsu Update API, klienci muszą utrzymywać lokalną pamięć podręczną. Interfejs API tworzy 2 rodzaje pamięci podręcznej: pozytywne i negatywne.

Pozytywne buforowanie

Aby zapobiec wielokrotnemu pytaniu klienta o stan konkretnego niebezpiecznego pełnego skrótu, każdy zwrócony ciąg ThreatMatch zawiera dodatni czas trwania w pamięci podręcznej (zdefiniowany w polu cacheDuration), który wskazuje, jak długo pełny hasz jest uznawany za niebezpieczny.

Negatywna pamięć podręczna

Aby zapobiec powtarzaniu się pytań o konkretny bezpieczny pełny hasz, każda odpowiedź fullHashes określa ujemny czas przechowywania w pamięci podręcznej żądanych prefiksów (zdefiniowany w polu negativeCacheDuration). Ten czas wskazuje, jak długo wszystkie pełne wartości hash z żądanym prefiksem mają być uważane za bezpieczne dla żądanych list, z wyjątkiem tych zwracanych przez serwer jako niebezpieczne. Takie buforowanie jest szczególnie ważne, bo pozwala uniknąć przeciążenia ruchem, które może być spowodowane kolizacją prefiksów skrótów z bezpiecznym adresem URL, który generuje dużo ruchu.

Konsultowanie pamięci podręcznej

Gdy klient chce sprawdzić stan adresu URL, najpierw oblicza pełny hasz. Jeśli w lokalnej bazie danych znajduje się prefiks pełnego znaku hash, klient powinien sprawdzić pamięć podręczną przed wysłaniem żądania fullHashes do serwera.

Najpierw klienci powinni sprawdzić, czy działanie pamięci podręcznej zostało dodatnie. Jeśli w pamięci podręcznej znajduje się wpis o pełnym rozmiarze, który jest ważny, należy uznać go za niebezpieczny. Jeśli dodatnia wartość pamięci podręcznej wygasła, klient musi wysłać żądanie fullHashes dla powiązanego lokalnego prefiksu. Zgodnie z protokołem, jeśli serwer zwraca pełny hasz, jest uważany za niebezpieczny. W przeciwnym razie jest uważany za bezpieczny.

Jeśli w przypadku pełnego skrótu nie ma dodatnich wpisów w pamięci podręcznej, klient powinien sprawdzić, czy występuje ujemne działanie pamięci podręcznej. Jeśli w powiązanym lokalnym prefiksie znajduje się niewykluczający wpis w pamięci podręcznej, pełny hasz jest uznawany za bezpieczny. Jeśli ujemny wpis pamięci podręcznej wygasł lub nie istnieje, klient musi wysłać żądanie fullHashes dla powiązanego lokalnego prefiksu i zinterpretować odpowiedź w zwykły sposób.

Aktualizuję pamięć podręczną

Pamięć podręczna klienta powinna być aktualizowana po otrzymaniu odpowiedzi fullHashes. Utwórz lub zaktualizuj dodatni wpis w pamięci podręcznej na potrzeby pełnego skrótu zgodnie z polem cacheDuration. Należy też utworzyć lub zaktualizować ujemny czas przechowywania prefiksu pamięci podręcznej zgodnie z polem negativeCacheDuration odpowiedzi.

Jeśli kolejne żądanie fullHashes nie zwraca pełnego skrótu, który jest aktualnie zapisany w pamięci podręcznej, klient nie musi usuwać dodatniego wpisu z pamięci podręcznej. W praktyce nie ma to powodu, ponieważ dodatnie czasy przechowywania w pamięci podręcznej są zwykle krótkie (kilka minut), co pozwala szybko poprawić nieprawidłowe wyniki.

Przykładowy scenariusz

W tym przykładzie załóżmy, że H(url) to prefiks adresu URL, a H(url) to pełna długość skrótu adresu URL. Czyli h(url) = SHA256(url).substr(4), H(url) = SHA256(url).

Załóżmy teraz, że klient (z pustą pamięcią podręczną) odwiedza example.com/ i zauważa, że h(example.com/) znajduje się w lokalnej bazie danych. Klient prosi o podanie skrótów o pełnej długości dla prefiksu h(example.com/) i zwraca pełną długość skrótu H(example.com/) z dodatnim czasem przechowywania w pamięci podręcznej wynoszącym 5 minut i ujemnym czasem przechowywania w pamięci podręcznej wynoszącym 1 godzinę.

Dodatni czas przechowywania w pamięci podręcznej wynoszący 5 minut informuje klienta, jak długo hasło o pełnej długości(H.example.com/) musi być uznane za niebezpieczne bez wysyłania kolejnego żądania fullHashes. Po 5 minutach klient musi ponownie wysłać żądanie fullHashes dla tego prefiksu h(example.com/), jeśli ponownie odwiedzi stronę example.com/. Klient powinien zresetować ujemny czas przechowywania prefiksu pamięci podręcznej dla nowej odpowiedzi.

Negatywny czas trwania pamięci podręcznej wynoszący 1 godzinę informuje klienta, jak długo należy używać wszystkich innych skrótów klawiszowych oprócz H(example.com/) o takim samym prefiksie h(example.com/). Przez 1 godzinę każdy adres URL w postaci h(URL) = h(example.com/) musi być bezpieczny i dlatego nie może spowodować wyświetlenia żądania fullHashes (przy założeniu, że H(URL) != H(example.com/).

Jeśli odpowiedź fullHashes zawiera zero dopasowań, a ujemny czas przechowywania w pamięci podręcznej, klient nie może wysyłać żadnych żądań fullHashes dla żadnego z żądanych prefiksów dla danego ujemnego czasu przechowywania w pamięci podręcznej.

Jeśli odpowiedź fullHashes zawiera co najmniej 1 pasujący wynik, to dla całej odpowiedzi jest ustawiany ujemny czas przechowywania w pamięci podręcznej. W takim przypadku czas przechowywania w pamięci podręcznej pojedynczego pojedynczego ciągu z pełną wartością wskazuje, jak długo dany klient musi być uznany za niebezpieczny. Po upłynięciu czasu przechowywania w pamięci podręcznej ThreatMatch klient musi odświeżyć pełną długość za pomocą skrótu, wysyłając żądanie fullHashes dla tego prefiksu, jeśli żądany adres URL pasuje do istniejącego ciągu znaków o pełnej długości w pamięci podręcznej. W takim przypadku ujemny czas przechowywania w pamięci podręcznej nie ma zastosowania. Wykluczający czas przechowywania w pamięci podręcznej ma zastosowanie tylko do skrótów o pełnej długości, których nie było w odpowiedzi fullHashes. W przypadku skrótów o pełnej długości, które nie znajdują się w odpowiedzi, klient musi przestać wysyłać żądania fullHashes do czasu negatywnego czasu przechowywania w pamięci podręcznej.

Przykład: fullHashes.find

Kliknij link żądania i odpowiedzi w nagłówku tabeli, aby zobaczyć pełne przykłady.

Prefiksy skrótów Żądanie FullHash	Pełne hasze dopasowujące pełna odpowiedź	Przechowywanie w pamięci podręcznej
"threatEntries": [ {"hash": "0xaaaaaaaa"} ]	"matches": [], "negativeCacheDuration": "3600.000s"	Brak dopasowań Klient nie może wysyłać żądań fullHashes z prefiksem skrótu 0xaaaaaaa przez co najmniej godzinę. Hasz z prefiksem 0xaaaaaa jest uznawany za bezpieczny przez godzinę.
"threatEntries": [ {"hash": "0xbbbbbbbb"} ]	"matches": [ "threat": {"hash": "0xbbbbbbbb0000..."} "cacheDuration": "600.000s", ], "negativeCacheDuration": "300.000s"	Możliwe dopasowania. Klient powinien sprawdzać adres URL z pełnym haszem 0xbbbbbb0000... przez 10 minut. Wszystkie inne adresy URL z prefiksem 0xbbbbbbbb powinny być bezpieczne przez 5 minut. Po 5 minutach prefiks z negatywną pamięcią podręczną straci ważność. Pozytywny wpis pamięci podręcznej dla 0xbbbbbbbb0000 nie wygasł, więc klient powinien wysłać fullHashes żądań dotyczących wszystkich skrótów oprócz tego.
"threatEntries": [ {"hash": "0xcccccccc"} ]	"matches": [ "threat": {"hash": "0xccccccccdddd..."}, "cacheDuration": "600.000s" ], "negativeCacheDuration": "3600.000s"	Możliwe dopasowania. Klient nie może wysyłać żądań fullHashes z prefiksem 0xcccccccc przez co najmniej 1 godzinę i zakładać, że prefiks jest bezpieczny, chyba że pełny hasz URL odpowiada pełnemu haszowaniu 0xccccccdddd.... W takim przypadku klient powinien uznać ten adres URL za niebezpieczny przez 10 minut. Po 10 minutach pełna długość skrótu wygaśnie. Kolejne wyszukiwania w przypadku tego pełnego skrótu powinny uruchamiać nowe żądanie fullHashes.