Buforowanie

Niniejszy dokument dotyczy następujących metod:

• Interfejs API wyszukiwania (wersja 4): threatMatches.find
• Zaktualizuj interfejs API (v4): fullHashes.find

Informacje o buforowaniu

Aby zmniejszyć wykorzystanie przepustowości sieci przez klientów i chronić Google przed nagłymi wzrostami natężenia ruchu, klienci Do tworzenia i utrzymywania lokalnej pamięci podręcznej danych o zagrożeniach wymagane są interfejsy Wyszukiwanie API oraz interfejs Update API. W przypadku interfejsu lookup API pamięć podręczna jest używana do zmniejszania liczby threatMatches żądania wysyłane przez klientów do Google. W przypadku interfejsu Update API pamięć podręczna jest używana do zmniejszenia liczby Żądania fullHashes wysyłane przez klientów do Google. Protokół buforowania dla każdego interfejsu API to opisane poniżej.

Interfejs API wyszukiwania

Klienty interfejsu lookup API powinny buforować każdy zwrócony element ThreatMatch przez określony czas przez pole cacheDuration. Przed dokonaniem kolejnej Żądanie threatMatches do serwera. Jeśli pamięć podręczna dla wcześniej zwróconego ThreatMatch jeszcze nie wygasła, klient powinien założyć, że produkt nadal jest niebezpieczny. Buforuję ThreatMatch elementów może zmniejszyć liczbę żądań do interfejsu API wysyłanych przez klienta.

Przykład: threatMatch.find

Aby zobaczyć pełne przykłady, kliknij linki żądania i odpowiedzi w nagłówku tabeli.

"threatEntries": [
 {"url": "http://www.urltocheck.org/"}
]

"matches": [{
 "threat": {"url": "http://www.urltocheck.org/"},
 "cacheDuration": "300.000s"
}]

Aktualizowanie API

Aby zmniejszyć łączną liczbę żądań fullHashes wysyłanych do Google za pomocą interfejsu Update API, klienty są wymagane do obsługi lokalnej pamięci podręcznej. Interfejs API obsługuje 2 typy buforowania: pozytywne i negatywne.

Pozytywne buforowanie

Aby zapobiec wielokrotnemu pytaniu o stan konkretnego niebezpiecznego pełnego hasza, każda zwrócona wartość ThreatMatch zawiera dodatni czas trwania w pamięci podręcznej (zdefiniowany przez pole cacheDuration), , który wskazuje, przez jaki czas pełny hasz ma być uznawany za niebezpieczny.

Negatywna pamięć podręczna

Aby zapobiec wielokrotnemu pytaniu o stan konkretnego bezpiecznego pełnego hasza, każda odpowiedź fullHashes określa ujemny czas trwania w pamięci podręcznej dla żądanego prefiksu (zdefiniowany przez negativeCacheDuration). Ten czas trwania wskazuje, jak długo wszystkie pełne hasze z żądanymi uważane są za bezpieczne dla żądanych list, z wyjątkiem tych zwracanych przez serwer jako nie są bezpieczne. To buforowanie jest szczególnie ważne, ponieważ zapobiega przeciążeniu, które może być spowodowane przez konflikt prefiksu skrótu z bezpiecznym adresem URL, który generuje duży ruch.

Sprawdzanie pamięci podręcznej

Gdy klient chce sprawdzić stan adresu URL, najpierw oblicza pełny hasz. Jeśli pełne Prefiks skrótu znajduje się w lokalnej bazie danych, klient powinien następnie skonsultować się z pamięcią podręczną przed wysyłając żądanie fullHashes do serwera.

Najpierw klienty powinny sprawdzić, czy nie występuje dodatnie trafienie w pamięci podręcznej. Jeśli istnieje nieaktualna dodatnia pamięć podręczna pełny hasz zainteresowania, należy uznać za niebezpieczny. Jeśli wpis w dodatniej pamięci podręcznej wygasł, klient musi wysłać żądanie fullHashes dla powiązanego prefiksu lokalnego. Zgodnie z protokołu, jeśli serwer zwraca pełny hasz, jest uznawany za niebezpieczny; w przeciwnym razie uznaje się bezpieczeństwa.

Jeśli pełny hasz nie jest zapisany w pamięci podręcznej, klient powinien sprawdzić wartość ujemną w pamięci podręcznej. Jeśli istnieje niewygasły wpis ujemnej pamięci podręcznej dla powiązanego prefiksu lokalnego, pełny hasz jest uważany za bezpieczny. Jeśli wpis wykluczonej pamięci podręcznej wygasł lub nie istnieje, klient musi wysłać żądanie fullHashes dotyczące powiązanego prefiksu lokalnego i zinterpretować odpowiedź jak zwykle.

Aktualizowanie pamięci podręcznej

Pamięć podręczna klienta powinna być aktualizowana po każdym otrzymaniu odpowiedzi fullHashes. Pozytywna pamięć podręczna należy utworzyć lub zaktualizować wpis tak, aby uzyskać pełny hasz zgodnie z polem cacheDuration. Prefiks skrótu ujemny czas trwania pamięci podręcznej również należy utworzyć lub zaktualizować zgodnie z wartością negativeCacheDuration odpowiedzi .

Jeśli kolejne żądanie fullHashes nie zwraca pełnego hasza, który obecnie jest dodatni klient nie musi usuwać wpisu dodatniej pamięci podręcznej. To nie jest powodem do zmartwień w praktyce, ponieważ czas przechowywania dodatniego pamięci podręcznej jest zwykle krótki (kilka minut), aby umożliwić korekcja wyników fałszywie pozytywnych.

Przykładowy scenariusz

W poniższym przykładzie załóżmy, że h(url) to prefiks skrótu adresu URL, a H(url) to prefiks skrótu adresu URL pełnej długości. Oznacza to, że h(url) = SHA256(url).substr(4), H(url) = SHA256(url).

Teraz załóżmy, że klient (z pustą pamięcią podręczną) odwiedza stronę example.com/ i widzi, że adres h(example.com/) jest w lokalnej bazie danych. Klient żąda hasz pełnej długości prefiksu h(example.com/) i otrzymuje z powrotem skrót H(example.com/) o pełnej długości wraz z dodatnim czasem trwania pamięci podręcznej równym 5 min, a ujemny czas przechowywania w pamięci podręcznej to 1 godzinę.

5-minutowy czas trwania dodatniej pamięci podręcznej informuje klienta, jak długo hasz pełnej długości Domena H(example.com/) musi zostać uznana za niebezpieczną bez wysyłania kolejnego żądania fullHashes. Po 5 minut klient musi wysłać kolejne żądanie fullHashes dla tego prefiksu h(example.com/), jeśli klient ponownie odwiedza witrynę example.com/. Klient powinien zresetować ujemny czas trwania ujemnej pamięci podręcznej prefiksu skrótu zgodnie z nową odpowiedzią.

Ujemny czas przechowywania w pamięci podręcznej wynoszący 1 godzinę informuje klienta, na jak długo są używane wszystkie inne hasze pełnej długości. oprócz H(example.com/), które mają ten sam prefiks h(example.com/), muszą zostać uznane za bezpieczne. Dla: trwa 1 godzinę, każdy adres URL, tak aby h(URL) = h(example.com/), musi zostać uznany za bezpieczny; w związku z tym nie skutkują żądaniem fullHashes (zakładając, że H(URL) != H(example.com/)).

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

Jeśli odpowiedź fullHashes zawiera co najmniej 1 dopasowanie, ujemny czas trwania w pamięci podręcznej nadal jest ustawiony dla całej odpowiedzi. W takim przypadku czas przechowywania pojedynczego pełnego haszu w pamięci podręcznej wskazuje czas ten konkretny hasz pełnej długości musi zostać uznany przez klienta za niebezpieczny. Po załadowaniu pamięci podręcznej ThreatMatch gdy upłynie czas, klient musi odświeżyć pełną długość hasha, wysyłając żądanie fullHashes dla ten prefiks skrótu, jeśli żądany adres URL odpowiada istniejącemu haszowi pełnej długości w pamięci podręcznej. Pod tym kątem ujemny czas trwania pamięci podręcznej nie ma zastosowania. Ujemny czas trwania odpowiedzi w pamięci podręcznej ma zastosowanie tylko do skrótów pełnej długości, których nie było w odpowiedzi fullHashes. W przypadku pełnych haszów, nie występują w odpowiedzi, klient musi powstrzymać się od wysyłania żadnych żądań fullHashes .

Przykład: pełneHasze.find

Aby zobaczyć pełne przykłady, kliknij linki żądania i odpowiedzi w nagłówku tabeli.

"threatEntries": [
  {"hash": "0xaaaaaaaa"}
]

"matches": [],
"negativeCacheDuration": "3600.000s"

"threatEntries": [
  {"hash": "0xbbbbbbbb"}
]

"matches": [
 "threat": {"hash": "0xbbbbbbbb0000..."}
 "cacheDuration": "600.000s",
],
"negativeCacheDuration": "300.000s"

"threatEntries": [
  {"hash": "0xcccccccc"}
]

"matches": [
 "threat": {"hash": "0xccccccccdddd..."},
 "cacheDuration": "600.000s"
],
"negativeCacheDuration": "3600.000s"