Caching läuft...

Dieses Dokument bezieht sich auf die folgenden Methoden:

Caching

Um die Bandbreitennutzung von Clients zu reduzieren und Google vor Zugriffsspitzen zu schützen, müssen die Clients der Lookup API und der Update API einen lokalen Cache mit Bedrohungsdaten erstellen und verwalten. Für die Lookup API wird der Cache verwendet, um die Anzahl der threatMatches-Anfragen zu reduzieren, die Clients an Google senden. Für die Update API wird der Cache verwendet, um die Anzahl der fullHashes-Anfragen zu reduzieren, die Clients an Google senden. Das Caching-Protokoll für jede API wird unten beschrieben.

Lookup API

Clients der Lookup API sollten jedes zurückgegebene ThreatMatch-Element für die Dauer im Cache speichern, die im entsprechenden Feld „cacheDuration“ festgelegt ist. Clients müssen dann den Cache prüfen, bevor sie eine nachfolgende threatMatches-Anfrage an den Server senden. Wenn die Cache-Dauer für eine zuvor zurückgegebene ThreatMatch noch nicht abgelaufen ist, sollte der Client davon ausgehen, dass das Element immer noch unsicher ist. Durch das Caching von ThreatMatch-Elementen kann die Anzahl der vom Client gestellten API-Anfragen reduziert werden.

Beispiel: threatMatches.find

Klicken Sie auf die Links für Anfrage und Antwort in der Kopfzeile der Tabelle, um vollständige Beispiele zu erhalten.

URL-Prüfung
threatMatches-Anfrage 		URL-Übereinstimmung
threatMatches-Antwort 		Caching-Verhalten 
"threatEntries": [
 {"url": "http://www.urltocheck.org/"}
]

"matches": [{
 "threat": {"url": "http://www.urltocheck.org/"},
 "cacheDuration": "300.000s"
}]
Übereinstimmung
Der Client muss 5 Minuten warten, bevor er eine neue threatMatches-Anfrage mit der URL http://www.urltocheck.org/ senden kann.

Update API

Clients müssen einen lokalen Cache verwalten, um die Gesamtzahl der fullHashes-Anfragen zu reduzieren, die über die Update API an Google gesendet werden. Die API setzt zwei Arten von Caching ein: positive und negative.

Positives Caching

Damit Clients nicht wiederholt nach dem Status eines bestimmten unsicheren vollständigen Hashs fragen, enthält jeder zurückgegebene ThreatMatch eine positive Cache-Dauer (definiert durch das Feld cacheDuration), die angibt, wie lange der vollständige Hash als unsicher gilt.

Negatives Caching

Damit Clients nicht wiederholt nach dem Status eines bestimmten sicheren vollständigen Hashs fragen, definiert jede fullHashes-Antwort eine negative Cache-Dauer für das angeforderte Präfix (definiert durch das Feld negativeCacheDuration). Diese Dauer gibt an, wie lange alle vollständigen Hashes mit dem angeforderten Präfix für die angeforderten Listen als sicher gelten, mit Ausnahme der vom Server als unsicher zurückgegebenen Listen. Dieses Caching ist besonders wichtig, da es eine Traffic-Überlastung verhindert, die durch eine Kollision des Hash-Präfix mit einer sicheren URL mit hohem Traffic verursacht werden könnte.

Cache prüfen

Wenn der Client den Status einer URL überprüfen möchte, berechnet er zuerst den vollständigen Hashwert. Wenn das vollständige Präfix des Hash in der lokalen Datenbank vorhanden ist, sollte der Client seinen Cache konsultieren, bevor eine fullHashes-Anfrage an den Server gesendet wird.

Zuerst sollten Clients nach einem positiven Cache-Treffer suchen. Wenn für den gesamten relevanten Hash ein nicht abgelaufener positiver Cache-Eintrag vorhanden ist, sollte er als unsicher eingestuft werden. Wenn der positive Cache-Eintrag abgelaufen ist, muss der Client eine fullHashes-Anfrage für das zugehörige lokale Präfix senden. Wenn der Server den vollständigen Hashwert zurückgibt, gilt er laut Protokoll als unsicher. Andernfalls gilt er als sicher.

Wenn für den vollständigen Hash keine positiven Cache-Einträge vorhanden sind, sollte der Client nach einem negativen Cache-Treffer suchen. Wenn für das zugehörige lokale Präfix ein nicht abgelaufener negativer Cache-Eintrag vorhanden ist, wird der vollständige Hash als sicher betrachtet. Wenn der negative Cache-Eintrag abgelaufen oder nicht vorhanden ist, muss der Client eine fullHashes-Anfrage für das zugehörige lokale Präfix senden und die Antwort als normal interpretieren.

Cache aktualisieren

Der Client-Cache sollte bei jedem Empfang einer fullHashes-Antwort aktualisiert werden. Erstellen oder aktualisieren Sie einen positiven Cache-Eintrag für den vollständigen Hash gemäß dem Feld cacheDuration. Die negative Cache-Dauer des Hash-Präfix sollte ebenfalls gemäß dem Feld negativeCacheDuration der Antwort erstellt oder aktualisiert werden.

Wenn eine nachfolgende fullHashes-Anfrage keinen vollständigen Hash zurückgibt, der derzeit positiv im Cache gespeichert ist, muss der Client den positiven Cache-Eintrag nicht entfernen. In der Praxis ist dies kein Grund zur Sorge, da positive Cache-Dauer in der Regel kurz (wenige Minuten) ist, um falsch positive Ergebnisse schnell zu korrigieren.

Beispielszenario

Im folgenden Beispiel wird angenommen, dass h(url) das Hash-Präfix der URL und H(url) der Hash-Wert der URL in voller Länge ist. Das heißt, h(url) = SHA256(url).substr(4), H(url) = SHA256(url).

Angenommen, ein Client (mit leerem Cache) besucht example.com/ und sieht, dass sich h(example.com/) in der lokalen Datenbank befindet. Der Client fordert die Hashes in voller Länge für das Hash-Präfix h(beispiel.de/) an und erhält den Hash-Wert H(beispiel.de/) in voller Länge zusammen mit einer positiven Cache-Dauer von 5 Minuten und einer negativen Cache-Dauer von 1 Stunde.

Die positive Cache-Dauer von 5 Minuten teilt dem Client mit, wie lange der Hash-Wert H(beispiel.de/) in voller Länge als unsicher gelten muss, ohne eine weitere fullHashes-Anfrage zu senden. Nach 5 Minuten muss der Client eine weitere fullHashes-Anfrage für das Präfix h(example.com/) senden, wenn der Client example.com/ noch einmal besucht. Der Client sollte die negative Cache-Dauer des Hash-Präfixes gemäß der neuen Antwort zurücksetzen.

Die negative Cache-Dauer von 1 Stunde teilt dem Client mit, wie lange alle anderen Hashes in voller Länge außer H(beispiel.de/) mit demselben Präfix h(beispiel.de/) als sicher gelten müssen. Für die Dauer von 1 Stunde muss jede URL mit h(URL) = h(beispiel.de/) als sicher betrachtet werden. Daher darf keine fullHashes-Anfrage ausgelöst werden (vorausgesetzt, dass H(URL) != H(beispiel.de/)).

Wenn die fullHashes-Antwort keine Übereinstimmungen enthält und eine negative Cache-Dauer festgelegt ist, darf der Client für die angegebene negative Cache-Dauer keine fullHashes-Anfragen für eines der angeforderten Präfixe senden.

Wenn die fullHashes-Antwort eine oder mehrere Übereinstimmungen enthält, wird trotzdem eine negative Cache-Dauer für die gesamte Antwort festgelegt. In diesem Fall gibt die Cache-Dauer eines einzelnen vollständigen Hash an, wie lange dieser bestimmte Hash in voller Länge vom Client als unsicher eingestuft werden muss. Nach Ablauf der Cache-Dauer von ThreatMatch muss der Client den Hash in voller Länge aktualisieren. Dazu sendet er eine fullHashes-Anfrage für das Hash-Präfix, wenn die angeforderte URL mit dem vorhandenen Hashwert in voller Länge im Cache übereinstimmt. In diesem Fall gilt die negative Cache-Dauer nicht. Die negative Cache-Dauer der Antwort gilt nur für Hashes in voller Länge, die in der fullHashes-Antwort nicht vorhanden waren. Bei Hashes in voller Länge, die nicht in der Antwort vorhanden sind, darf der Client keine fullHashes-Anfragen senden, bis die negative Cache-Dauer abgelaufen ist.

Beispiel: fullHashes.find

Klicken Sie auf die Links für Anfrage und Antwort in der Kopfzeile der Tabelle, um vollständige Beispiele zu erhalten.

Hash-Präfixe
fullHashes-Anfrage 		Hash-Übereinstimmungen in voller Länge
fullHashes-Antwort 		Caching-Verhalten 
"threatEntries": [
  {"hash": "0xaaaaaaaa"}
]

"matches": [],
"negativeCacheDuration": "3600.000s"
Keine Übereinstimmung.
Der Client darf mindestens eine Stunde lang keine fullHashes-Anfragen für das Hash-Präfix 0xaaaaaaaa senden. Jeder Hash mit dem Präfix 0xaaaaaaaa gilt eine Stunde lang als sicher.		 
"threatEntries": [
  {"hash": "0xbbbbbbbb"}
]

"matches": [
 "threat": {"hash": "0xbbbbbbbb0000..."}
 "cacheDuration": "600.000s",
],
"negativeCacheDuration": "300.000s"
Mögliche Übereinstimmungen.
Der Client sollte die URL mit dem vollständigen Hash 0xbbbbbbbb0000... 10 Minuten lang als unsicher betrachten. Alle anderen URLs mit dem Hash-Präfix „0xbbbbbbbb“ sollten vom Client fünf Minuten lang als sicher betrachtet werden. Nach 5 Minuten würde der negative Cache-Eintrag der Hash-Präfixe ablaufen. Da der positive Cache-Eintrag für 0xbbbbbbbb0000... noch nicht abgelaufen ist, sollte der Client fullHashes-Anfragen für alle Hashes außer diesem senden.		 
"threatEntries": [
  {"hash": "0xcccccccc"}
]

"matches": [
 "threat": {"hash": "0xccccccccdddd..."},
 "cacheDuration": "600.000s"
],
"negativeCacheDuration": "3600.000s"
Mögliche Übereinstimmungen.
Der Client darf mindestens eine Stunde lang keine fullHashes-Anfrage für das Hash-Präfix 0xcccccc senden und davon ausgehen, dass das Präfix sicher ist. Eine Ausnahme gilt, wenn der vollständige Hash der URL mit dem im Cache gespeicherten vollständigen Hash 0xccccccccdd... übereinstimmt. In diesem Fall sollte der Client diese URL zehn Minuten lang als unsicher betrachten. Nach 10 Minuten läuft der Hash in voller Länge ab. Jede nachfolgende Suche für diesen vollständigen Hash sollte eine neue fullHashes-Anfrage auslösen.