Caching

Dieses Dokument bezieht sich auf die folgenden Methoden:

• Lookup API (Version 4): threatMatches.find
• Update API (v4): fullHashes.find

Caching

Um die Bandbreitennutzung der Clients zu reduzieren und Google vor Traffic-Spitzen zu schützen, Die Lookup API und die Update API sind erforderlich, um einen lokalen Cache mit Bedrohungsdaten zu erstellen und zu verwalten. Für die Lookup API wird der Cache verwendet, um die Anzahl der threatMatches zu reduzieren -Anfragen, 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 ist wie unten beschrieben.

Lookup API

Clients der Lookup API sollten jedes zurückgegebene ThreatMatch-Element für die angegebene Dauer im Cache speichern durch sein Feld „cacheDuration“ angegeben. Clients müssen dann den Cache konsultieren, bevor sie eine weitere threatMatches-Anfrage an den Server. Wenn die Cache-Dauer für einen zuvor zurückgegebenen ThreatMatch-Wert noch nicht abgelaufen ist, sollte der Kunde davon ausgehen, dass der Artikel immer noch nicht sicher ist. ThreatMatch Elemente werden im Cache gespeichert kann die Anzahl der vom Client gestellten API-Anfragen verringern.

Beispiel: ThreatMatches.find

Die vollständigen Beispiele erhalten Sie, wenn Sie in der Kopfzeile der Tabelle auf die Anfrage- und Antwortlinks klicken.

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

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

Update API

Um die Gesamtzahl der fullHashes-Anfragen zu reduzieren, die über die Update API an Google gesendet werden, müssen Clients sind erforderlich, um einen lokalen Cache zu verwalten. Die API richtet zwei Arten des Cachings ein: positive und negative.

Positives Caching

So verhindern Sie, dass Clients wiederholt nach dem Status eines bestimmten unsicheren vollständigen Hashs fragen: Jede zurückgegebene ThreatMatch enthält eine positive Cache-Dauer (definiert durch das Feld cacheDuration). Dieser Wert gibt an, wie lange der vollständige Hashwert als unsicher gilt.

Negatives Caching

Um zu verhindern, dass Clients wiederholt nach dem Status eines bestimmten sicheren vollständigen Hashs fragen, Jede fullHashes-Antwort definiert eine negative Cache-Dauer für das angeforderte Präfix (definiert durch die negativeCacheDuration). Diese Dauer gibt an, wie lange alle vollständigen Hashes mit den angeforderten als sicher für die angeforderten Listen angesehen werden, außer für diejenigen, die vom Server als unsicher. Dieses Caching ist besonders wichtig, da es die Traffic-Überlastung verhindert, durch eine Hash-Präfix-Kollision mit einer sicheren URL, die viel Traffic erhält.

Cache prüfen

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

Zuerst sollten Clients nach einem positiven Cache-Treffer suchen. Wenn ein nicht abgelaufener positiver Cache vorhanden ist vollständigen Hash of Interest eingeben, sollte dieser als unsicher betrachtet werden. Wenn der positive Cache-Eintrag abgelaufen ist, muss der Client eine fullHashes-Anfrage für das zugehörige lokale Präfix senden. Gemäß der -Protokoll, gilt es als unsicher, wenn der Server den vollständigen Hash zurückgibt. Andernfalls gilt sie als zu schützen.

Wenn keine positiven Cache-Einträge für den vollständigen Hash vorhanden sind, sollte der Client nach einer negativen Cache-Treffer. Wenn für das verknüpfte lokale Präfix ein nicht abgelaufener negativer Cache-Eintrag vorhanden ist, wird der der vollständige Hash als sicher gilt. Wenn der Eintrag im negativen Cache abgelaufen ist oder nicht vorhanden ist, hat der Client muss 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. Ein positiver Cache muss für den vollständigen Hash gemäß dem Feld cacheDuration erstellt oder aktualisiert werden. Die Dauer von negativem Cache sollte auch gemäß der negativeCacheDuration der Antwort erstellt oder aktualisiert werden. ein.

Wenn eine nachfolgende fullHashes-Anfrage keinen vollständigen Hash zurückgibt, der derzeit positiv ist muss der Client den positiven Cache-Eintrag nicht entfernen. Dies gibt keinen Anlass zur Sorge da positive Cache-Daueren in der Regel kurz sind (wenige Minuten), Korrektur von falsch positiven Ergebnissen.

Beispielszenario

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

Angenommen, ein Client (mit leerem Cache) besucht example.com/ und stellt fest, dass h(example.com/) in der lokalen Datenbank. Der Client fordert die Hashes in voller Länge für das Hash-Präfix h(beispiel.de/) an und empfängt den vollständigen Hash H(beispiel.de/) zusammen mit einer positiven Cache-Dauer von 5 Minuten und eine negative Cache-Dauer von 1 Stunde.

Die positive Cache-Dauer von 5 Minuten teilt dem Client mit, wie lang der H(beispiel.de/) muss als unsicher eingestuft werden, ohne eine weitere fullHashes-Anfrage zu senden. Nach 5 Minuten, muss der Client eine weitere fullHashes-Anfrage für dieses Präfix h(beispiel.de/) ausgeben, wenn die besucht example.com/ erneut. Der Client sollte die negative Cache-Dauer des Hash-Präfixes zurücksetzen gemäß der neuen Antwort.

Die negative Cache-Dauer von 1 Stunde teilt dem Client mit, wie lange alle anderen Hashes in voller Länge mit Ausnahme von H(beispiel.de/) mit dem Präfix h(beispiel.de/) gelten als sicher. Für Dauer von 1 Stunde, jede URL, sodass h(URL) = h(beispiel.de/) als sicher gilt, und führt daher nicht zu einer fullHashes-Anfrage (vorausgesetzt, dass H(URL) != H(beispiel.de/) ist).

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

Wenn die fullHashes-Antwort eine oder mehrere Übereinstimmungen enthält, wird trotzdem eine negative Cache-Dauer festgelegt für die gesamte Antwort. In diesem Fall gibt die Cache-Dauer eines einzelnen vollständigen Hashs an, wie lange dass der Hash-Wert in voller Länge vom Client als unsicher angesehen werden muss. Nach dem ThreatMatch-Cache verstrichen ist, muss der Kunde den Hash-Wert in voller Länge aktualisieren, indem er eine fullHashes-Anfrage für dieses Hash-Präfix, wenn die angeforderte URL mit dem vorhandenen Hash-Wert in voller Länge im Cache übereinstimmt. Dabei Fall, dass die negative Cache-Dauer nicht zutrifft. Die negative Cache-Dauer der Antwort gilt nur in Hashes in voller Länge ein, die nicht in der fullHashes-Antwort vorhanden waren. Für Hashes in voller Länge, die nicht in der Antwort enthalten sind, darf der Client keine fullHashes-Anfragen senden. bis die Dauer des negativen Cache verstrichen ist.

Beispiel: fullHashes.find

Die vollständigen Beispiele erhalten Sie, wenn Sie in der Kopfzeile der Tabelle auf die Anfrage- und Antwortlinks klicken.

"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"