Dieses Dokument gilt für die Update API (Version 4): threatListUpdates.fetch.
Datenbank einrichten
Clients, die die Update API verwenden, müssen eine lokale Datenbank einrichten und zum ersten Mal die Safe Browsing-Listen herunterladen, mit denen sie arbeiten möchten. Zuerst können Sie das Go-Paket safebrowsing erstellen und bereitstellen (oder das Paket verwenden, um Ihre eigene Implementierung zu modellieren). Weitere Informationen finden Sie unter https://github.com/google/safebrowsing/.
Aktualisierungen der Datenbank
Zum Schutz vor den neuesten Bedrohungen wird Clients dringend empfohlen, ihre lokalen Safe Browsing-Listen regelmäßig mit der Methode threatListUpdates.fetch zu aktualisieren. Die threatListUpdates.fetch-Anfrage gibt die zu aktualisierenden Listen an. Wenn Clients Speicher- oder Bandbreitenbeschränkungen haben, können sie die Anfrage auch zum Festlegen von Aktualisierungseinschränkungen verwenden (siehe Updatebeschränkungen). Die threatListUpdates.fetch-Antwort gibt für jede Liste entweder eine vollständige oder eine Teilaktualisierung zurück, wie unten erläutert.Vollständige Updates
Vollständige Aktualisierungen werden zurückgegeben, wenn der Client das Feld state in der threatListUpdates.fetch-Anfrage leer lässt oder wenn der Server feststellt, dass eine vollständige Aktualisierung erforderlich ist. Bei vollständigen Aktualisierungen werden nur Ergänzungen zurückgegeben. Es wird erwartet, dass der Client die lokale Datenbank löscht, bevor die Aktualisierungen angewendet und die Validierungsprüfung durchgeführt wird.
Vollständige Aktualisierungen werden zurückgegeben, wenn der Client die erste Anfrage für eine Liste sendet. In diesem Fall bleibt das Feld state in der Anfrage leer, da kein Wert angegeben werden muss, und das Feld newClientState in der Antwort gibt den Anfangszustand für die lokale Liste zurück. Vollständige Aktualisierungen werden auch zurückgegeben, wenn der Client das Feld state bei nachfolgenden Anfragen absichtlich leer lässt. Dadurch wird eine vollständige Aktualisierung erzwungen und ein neuer Status im Feld newClientState der Antwort zurückgegeben.
Gelegentlich gibt der Safe Browsing-Server ein vollständiges Update zurück, wenn vom Client nur ein Teilupdate angefordert wurde. Dies kann passieren, wenn der Client zuerst eine kleine Version der Liste herunterlädt und dann auf eine größere Version der Liste aktualisiert. Der Server gibt dann einfach ein vollständiges Update mit der gesamten Liste zurück. Dies kann auch der Fall sein, wenn der Client lange keine Daten heruntergeladen hat und eine Teilaktualisierung anfordert. Auch hier gibt der Server einfach ein vollständiges Update mit der gesamten Liste zurück.
Partielle Updates
Teilaktualisierungen werden zurückgegeben, wenn der Client einen Wert für das Feld state in der Anfrage „threatListUpdates.fetch“ angibt. Die oben erwähnte Ausnahme liegt vor, wenn der Server feststellt, dass eine vollständige Aktualisierung erforderlich ist. Bei teilweisen Aktualisierungen werden sowohl Ergänzungen als auch Entfernungen zurückgegeben. Der Client aktualisiert die Listen in der lokalen Datenbank, wendet die Löschungen vor dem Hinzufügen an und führt dann die Validierungsprüfung durch.
Hinzufügungen
Hinzufügungen sind SHA 256-Hash-Präfixe, die der lokalen Datenbank hinzugefügt werden sollten. Die überwiegende Mehrheit der Hash-Präfixe ist 4 Byte lang. Einige Hash-Präfixe können jedoch eine beliebige Länge zwischen 4 und 32 Byte haben. Daher können mehrere Sätze von Additionen zurückgegeben werden, z. B. einer mit 4-Byte-Präfixen und einer mit 5-Byte-Präfixen.
Wenn der Client die Komprimierung unterstützt, kann die Antwort mit Rice-Komprimierung komprimiert werden. Allerdings werden nur 4-Byte-Hash-Präfixe komprimiert. Längere Hash-Präfixe werden immer in unkomprimiertem Rohformat gesendet (siehe Komprimierung).
Entfernen
Das Entfernen sind nullbasierte Indizes in der lexikografisch sortierten Clientdatenbank, die auf Einträge verweisen, die aus der lokalen Datenbank entfernt werden sollen. Es wird nur ein Satz von Entfernungen zurückgegeben.
Wenn der Client die Komprimierung unterstützt, werden „Reis-Hashes“ und „Reis-Indizes“ zurückgegeben. Wenn die Komprimierung nicht unterstützt wird, werden „Roh-Hashes“ und „Rohindexe“ zurückgegeben (siehe Komprimierung).
Validierungsprüfungen
Wenn die threatListUpdates.fetch-Antwort entweder mit einer vollständigen oder einer teilweisen Aktualisierung zurückgegeben wird, wird erwartet, dass der Client eine Validierungsprüfung durchführt.
Der Client aktualisiert zuerst die Listen in der lokalen Datenbank und wendet die Löschungen vor dem Hinzufügen an. Der Client berechnet dann den SHA256-Hash der (lexikografisch sortierten) lokalen Liste und vergleicht ihn mit der Prüfsumme, die in der Antwort zurückgegeben wird. Wenn die beiden Werte gleich sind, gilt die Safe Browsing-Liste als „richtig“.
Wenn die beiden Werte nicht gleich sind, gilt die Safe Browsing-Liste als „beschädigt“. Der Client muss die Liste aus der Datenbank löschen und eine zweite Aktualisierung durchführen, wobei das Feld state auf den leeren String festgelegt ist. Dadurch wird eine vollständige Aktualisierung erzwungen und eine ganz neue Liste und ein neuer Status zurückgegeben.