Caching

Dieses Dokument bezieht sich auf die folgenden Methoden:

• Lookup API: uris.search
• Update API: hashes.search

Caching

Um die Bandbreitennutzung des Clients zu reduzieren und Google vor Trafficspitzen zu schützen, müssen Clients der Lookup API und der Update API einen lokalen Cache mit Bedrohungsdaten erstellen und verwalten. Die Lookup API verwendet den Cache, um die Anzahl der uris.search-Anfragen zu reduzieren, die Clients an Google senden. Für die Update API wird der Cache verwendet, um die Anzahl der hashes.search-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 ThreatUrl-Element bis zu der im Feld expireTime definierten Zeit im Cache speichern. Clients müssen dann den Cache prüfen, bevor sie eine nachfolgende uris.search-Anfrage an den Server senden. Wenn der Cache-Eintrag für eine zuvor zurückgegebene ThreatUrl noch nicht abgelaufen ist, sollte der Client davon ausgehen, dass das Element immer noch unsicher ist. Durch das Caching von ThreatUrl-Elementen kann die Anzahl der vom Client ausgeführten API-Anfragen reduziert werden.

Update API

Zur Reduzierung der Gesamtzahl der hashes.search-Anfragen, die über die Update API an Google gesendet werden, müssen Clients einen lokalen Cache führen. Die API richtet zwei Arten von Caching ein: positive und negative.

Positives Caching

Damit Clients nicht wiederholt den Status eines bestimmten unsicheren vollständigen Hashs abfragen, enthält jeder zurückgegebene ThreatHash eine positive Cache-Zeit (definiert durch das Feld expireTime). Der vollständige Hash kann bis zu diesem Zeitpunkt als unsicher angesehen werden.

Negatives Caching

Damit Clients nicht wiederholt nach dem Status eines bestimmten sicheren vollständigen Hashs fragen, definiert die Antwort eine negative Cache-Dauer für das angeforderte Präfix (durch das Feld negativeExpireTime definiert). Alle vollständigen Hashes mit dem angeforderten Präfix sind bis zu diesem Zeitpunkt für die angeforderten Bedrohungsarten als sicher anzusehen, mit Ausnahme derer, die vom Server als unsicher zurückgegeben werden. Dieses Caching ist besonders wichtig, da es eine Traffic-Überlastung verhindert, die durch eine Hash-Präfixkollision mit einer sicheren URL verursacht werden könnte, die viel Traffic erhält.

Cache prüfen

Wenn der Client den Status einer URL prüfen möchte, berechnet er zuerst den vollständigen Hash. Wenn das vollständige Präfix des Hashs in der lokalen Datenbank vorhanden ist, sollte der Client den Cache prüfen, bevor er eine hashes.search-Anfrage an den Server sendet.

Zuerst sollten Clients nach einem positiven Cache-Treffer suchen. Wenn ein nicht abgelaufener positiver Cache-Eintrag für den gesamten relevanten Hash vorhanden ist, sollte dieser als unsicher angesehen werden. Wenn der positive Cache-Eintrag abgelaufen ist, muss der Client eine hashes.search-Anfrage für das zugeordnete lokale Präfix senden. Wenn der Server gemäß dem Protokoll den vollständigen Hash zurückgibt, gilt dies als unsicher. Andernfalls gilt es als sicher.

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

Cache aktualisieren

Der Client-Cache sollte bei jedem Empfang einer hashes.search-Antwort aktualisiert werden. Im Feld expireTime sollte ein positiver Cache-Eintrag für den vollständigen Hash erstellt oder aktualisiert werden. Die negative Cache-Dauer des Hash-Präfixes sollte auch im Feld negativeExpireTime der Antwort erstellt oder aktualisiert werden.

Wenn eine nachfolgende hashes.search-Anfrage keinen vollständigen Hash zurückgibt, der derzeit positiv im Cache gespeichert ist, muss der Client den positiven Cache-Eintrag nicht entfernen. Dies ist in der Praxis kein Grund zur Sorge, da positive Cache-Zeiten in der Regel kurz sind (wenige Minuten), damit falsch positive Ergebnisse schnell korrigiert werden können.

Beispielszenario

Im folgenden Beispiel nehmen wir an, dass h(url) das Hash-Präfix der URL und H(url) der Hash 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(example.com/) an und empfängt den Hash in voller Länge H(example.com/) zusammen mit einer positiven Cache-Ablaufzeit von 5 Minuten und einem negativen Cache-Ablauf in einer Stunde.

Die positive Cache-Dauer von 5 Minuten teilt dem Client mit, wie lange der Hash in voller Länge H(example.com/) als unsicher angesehen werden muss, ohne eine weitere hashes.search-Anfrage zu senden. Nach fünf Minuten muss der Client eine weitere hashes.search-Anfrage für das Präfix h(example.com/) senden, wenn der Client example.com/ noch einmal aufruft. Der Client sollte die Ablaufzeit des negativen Caches für das Hash-Präfix gemäß der neuen Antwort zurücksetzen.

Die negative Cache-Dauer von 1 Stunde gibt dem Client an, wie lange alle anderen Hashes in voller Länge außer H(example.com/) mit demselben Präfix von h(example.com/) als sicher gelten müssen. Für die Dauer von 1 Stunde muss jede URL wie h(URL) = h(example.com/) als sicher betrachtet werden und führt daher nicht zu einer hashes.search-Anfrage (vorausgesetzt, H(URL) ! = H(example.com/)).

Wenn die Antwort fullHashes null Übereinstimmungen enthält und eine negative Cache-Ablaufzeit festgelegt ist, darf der Client keine hashes.search-Anfragen für die angeforderten Präfixe für die angegebene negative Cache-Zeit ausgeben.

Wenn die Antwort hashes.search eine oder mehrere Übereinstimmungen enthält, wird trotzdem eine negative Cache-Ablaufzeit für die gesamte Antwort festgelegt. In diesem Fall gibt die Cache-Ablaufzeit eines einzelnen vollständigen Hashs an, wie lange der Client davon ausgehen muss, dass der bestimmte Hash in voller Länge unsicher ist. Nach Ablauf der Cache-Dauer von ThreatHash muss der Client den Hash in voller Länge aktualisieren. Dazu sendet er eine hashes.search-Anfrage für dieses Hash-Präfix, wenn die angeforderte URL mit dem vorhandenen Hash 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 Antwort hashes.search nicht vorhanden waren. Bei Hashes in voller Länge, die in der Antwort nicht vorhanden sind, muss der Client keine hashes.search-Anfragen senden, bis die negative Cache-Dauer abgelaufen ist.