Überblick
Mit der Update API können Clientanwendungen Hash-Versionen der Safe Browsing-Listen herunterladen, um sie in einer lokalen Datenbank zu speichern. URLs können dann lokal geprüft werden. Nur wenn eine Übereinstimmung mit der lokalen Datenbank gefunden wird, muss der Client eine Anfrage an die Safe Browsing-Server senden, um zu prüfen, ob sich die URL auf den Safe Browsing-Listen befindet.
Bevor Sie die Update API verwenden können, müssen Sie eine lokale Datenbank einrichten. Safe Browsing bietet ein Go-Paket für den Einstieg. Weitere Informationen finden Sie im Abschnitt "Datenbankeinrichtung" unter Lokale Datenbanken.
Lokale Datenbank aktualisieren
Um auf dem neuesten Stand zu bleiben, müssen Clients die Safe Browsing-Listen in ihrer lokalen Datenbank regelmäßig aktualisieren. Um Bandbreite zu sparen, laden Clients die Hash-Präfixe von URLs statt der Roh-URLs herunter. Wenn sich beispielsweise "www.badurl.com/" auf einer Safe Browsing-Liste befindet, laden Clients das SHA256-Hash-Präfix dieser URL und nicht die URL selbst herunter. In den meisten Fällen sind die Hash-Präfixe 4 Byte lang. Das bedeutet, dass die durchschnittlichen Bandbreitenkosten für das Herunterladen eines einzelnen Listeneintrags 4 Byte vor der Komprimierung betragen.
Zum Aktualisieren der Safe Browsing-Listen in der lokalen Datenbank senden Sie eine HTTP-POST
-Anfrage an die Methode threatListUpdates.fetch:
- Die HTTP-
POST
-Anfrage enthält die Namen der zu aktualisierenden Listen sowie verschiedene Clienteinschränkungen, um Speicher- und Bandbreitenbeschränkungen zu berücksichtigen. - Die HTTP-
POST
-Anfrage gibt entweder eine vollständige Aktualisierung oder eine teilweise Aktualisierung zurück. Die Antwort kann auch eine Mindestwartedauer zurückgeben.
Beispiel: threatListUpdates.fetch
HTTP POST-Anfrage
Im folgenden Beispiel werden die Aktualisierungen für eine einzelne Safe Browsing-Liste angefordert.
Anfrageheader
Der Anfrageheader enthält die Anfrage-URL und den Inhaltstyp. Denken Sie daran, API_KEY
in der URL durch Ihren API-Schlüssel zu ersetzen.
POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1 Content-Type: application/json
Anfragetext
Der Anfragetext enthält die Clientinformationen (ID und Version) und die Aktualisierungsinformationen (Listenname, Listenstatus und Clienteinschränkungen). Weitere Informationen finden Sie im Anfragetext von threatListUpdates.fetch und in den Erläuterungen zu diesem Codebeispiel.
{ "client": { "clientId": "yourcompanyname", "clientVersion": "1.5.2" }, "listUpdateRequests": [{ "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "state": "Gg4IBBADIgYQgBAiAQEoAQ==", "constraints": { "maxUpdateEntries": 2048, "maxDatabaseEntries": 4096, "region": "US", "supportedCompressions": ["RAW"] } }] }
Kundeninformationen
Die Felder clientID
und clientVersion
sollten eine Clientimplementierung eindeutig identifizieren, nicht einen einzelnen Nutzer. (Clientinformationen werden beim serverseitigen Logging verwendet. Sie können einen beliebigen Namen für die Client-ID wählen. Wir empfehlen jedoch, einen Namen zu wählen, der die wahre Identität des Clients darstellt, z. B. den Namen Ihres Unternehmens, der aus einem Wort besteht und nur Kleinbuchstaben enthält.
Safe Browsing-Listen
Die Felder threatType
, platformType
und threatEntryType
werden kombiniert, um die Safe Browsing-Listen zu identifizieren (zu benennen). Im Beispiel wird eine Liste identifiziert: MALWARE/WINDOWS/URL. Prüfen Sie vor dem Senden einer Anfrage, ob die angegebenen Typkombinationen gültig sind (siehe Safe Browsing-Listen).
Clientstatus
Das Feld „state
“ enthält den aktuellen Clientstatus der Safe Browsing-Liste.
(Clientstatus werden im Feld newClientState
der Antwort „threatListUpdates.fetch“ zurückgegeben.)
Lassen Sie bei ersten Aktualisierungen das Feld state
leer.
Größenbeschränkungen
Das Feld maxUpdateEntries
gibt die Gesamtzahl der Updates an, die der Client verwalten kann (im Beispiel 2.048). Das Feld maxDatabaseEntries
gibt die Gesamtzahl der Einträge an, die die lokale Datenbank verwalten kann (im Beispiel 4.096). Clients sollten Größenbeschränkungen festlegen, um Speicher- und Bandbreitenbeschränkungen zu schützen und ein größeres Listenwachstum zu verhindern. Weitere Informationen finden Sie unter Einschränkungen aktualisieren.
Unterstützte Komprimierungen
Im Feld supportedCompressions
sind die vom Client unterstützten Komprimierungstypen aufgeführt. In diesem Beispiel unterstützt der Client nur unkomprimierte Rohdaten. Safe Browsing unterstützt jedoch zusätzliche Komprimierungstypen (siehe Komprimierung).
HTTP POST-Antwort
In diesem Beispiel gibt die Antwort ein Teilupdate für die Safe Browsing-Liste mit dem angeforderten Komprimierungstyp zurück.
Antwortheader
Der Antwortheader enthält den HTTP-Statuscode und den Inhaltstyp. Clients, die einen anderen Statuscode als HTTP/200 erhalten, müssen in den Backoff-Modus wechseln (siehe Anfragehäufigkeit).
HTTP/1.1 200 OK Content-Type: application/json
Antworttext
Der Antworttext enthält die Aktualisierungsinformationen (den Listennamen, den Antworttyp, die auf die lokale Datenbank anzuwendenden Ergänzungen und Entfernungen, den neuen Clientstatus und eine Prüfsumme). In diesem Beispiel enthält die Antwort auch eine Mindestwartezeit. Weitere Informationen finden Sie im Antworttext von ThreatListUpdates.fetch und in den Erläuterungen zu diesem Codebeispiel.
{ "listUpdateResponses": [{ "threatType": "MALWARE", "threatEntryType": "URL", "platformType": "WINDOWS", "responseType" : "PARTIAL_UPDATE", "additions": [{ "compressionType": "RAW", "rawHashes": { "prefixSize": 4, "rawHashes": "rnGLoQ==" } }], "removals": [{ "compressionType": "RAW", "rawIndices": { "indices": [0, 2, 4] } }], "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd", "checksum": { "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM=" } }], "minimumWaitDuration": "593.440s" }
Aktualisierungen der Datenbank
Im Feld responseType
wird eine teilweise oder vollständige Aktualisierung angegeben. Im Beispiel wird eine Teilaktualisierung zurückgegeben, d. h. die Antwort enthält sowohl Hinzufügungen als auch Entfernungen. Es kann mehrere Gruppen von Hinzufügungen, aber nur eine Gruppe von Entfernungen geben (siehe Datenbankaktualisierungen).
Neuer Clientstatus
Das Feld newClientState
enthält den neuen Clientstatus für die aktualisierte Safe Browsing-Liste.
Clients müssen den neuen Clientstatus für nachfolgende Aktualisierungsanfragen speichern (das Feld state
in der Anfrage threatListUpdates.fetch oder das Feld clientStates
in der Anfrage fullHashes.find).
Prüfsummen
Anhand der Prüfsumme können Clients überprüfen, ob die lokale Datenbank beschädigt ist. Wenn die Prüfsumme nicht übereinstimmt, muss der Client die Datenbank löschen und mit einem leeren Feld state
eine Aktualisierung noch einmal ausführen. Clients müssen in diesem Fall dennoch die Zeitintervalle für Aktualisierungen einhalten (siehe Anfragehäufigkeit).
Mindestwartedauer
Das Feld minimumWaitDuration
gibt an, dass der Client 593,44 Sekunden (9,89 Minuten) warten muss, bevor er eine weitere Aktualisierungsanfrage sendet. Beachten Sie, dass die Antwort eine Wartezeit enthalten kann oder nicht (siehe Anfragehäufigkeit).
URLs prüfen
Um zu prüfen, ob sich eine URL auf einer Safe Browsing-Liste befindet, muss der Client zuerst den Hash und das Hash-Präfix der URL berechnen (siehe URLs und Hash-Technologie). Der Client fragt dann die lokale Datenbank ab, um festzustellen, ob es eine Übereinstimmung gibt. Wenn das Hash-Präfix in der lokalen Datenbank nicht vorhanden ist, gilt die URL als sicher (nicht auf den Safe Browsing-Listen).
Wenn das Hash-Präfix in der lokalen Datenbank vorhanden ist (eine Hash-Präfix-Kollision), muss der Client es zur Überprüfung an die Safe Browsing-Server senden. Die Server geben alle SHA-256-Hashes in voller Länge zurück, die das angegebene Hash-Präfix enthalten. Wenn einer dieser Hashes in voller Länge mit dem Hash in voller Länge der betreffenden URL übereinstimmt, wird die URL als unsicher eingestuft. Wenn keiner der Hashes in voller Länge mit dem Hash der vollständigen Länge übereinstimmt, gilt diese URL als sicher.
Google erfährt zu keinem Zeitpunkt, welche URLs Sie untersuchen. Google lernt zwar die Hash-Präfixe von URLs, liefern aber nicht viele Informationen zu den tatsächlichen URLs.
Wenn Sie prüfen möchten, ob sich eine URL auf einer Safe Browsing-Liste befindet, senden Sie eine HTTP-POST
-Anfrage an die Methode fullHashes.find:
- Die HTTP-
POST
-Anfrage kann bis zu 500 Bedrohungseinträge enthalten. - Die HTTP-
POST
-Anfrage enthält die Hash-Präfixe der zu prüfenden URLs. Clients werden empfohlen, mehrere Bedrohungseinträge in einer einzigen Anfrage zusammenzufassen, um die Bandbreitennutzung zu verringern. - Die HTTP-Antwort
POST
gibt die übereinstimmenden Hashes in voller Länge sowie die positive und negative Cache-Dauer zurück. Die Antwort kann auch eine Mindestwartedauer zurückgeben.
Beispiel: fullHashes.find
HTTP POST-Anfrage
Im folgenden Beispiel werden die Namen von zwei Safe Browsing-Listen und drei Hash-Präfixen zum Vergleich und zur Überprüfung gesendet.
Anfrageheader
Der Anfrageheader enthält die Anfrage-URL und den Inhaltstyp. Denken Sie daran, API_KEY
in der URL durch Ihren API-Schlüssel zu ersetzen.
POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1 Content-Type: application/json
Anfragetext
Der Anfragetext enthält die Clientinformationen (ID und Version), die Clientstatus und die Bedrohungsinformationen (Listennamen und Hash-Präfixe). Bei JSON-Anfragen müssen Hash-Präfixe in base64-codierter Form gesendet werden. Weitere Informationen finden Sie im Anfragetext für FullHashes.find und in den Erläuterungen zu diesem Codebeispiel.
{ "client": { "clientId": "yourcompanyname", "clientVersion": "1.5.2" }, "clientStates": [ "ChAIARABGAEiAzAwMSiAEDABEAE=", "ChAIAhABGAEiAzAwMSiAEDABEOgH" ], "threatInfo": { "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"], "platformTypes": ["WINDOWS"], "threatEntryTypes": ["URL"], "threatEntries": [ {"hash": "WwuJdQ=="}, {"hash": "771MOg=="}, {"hash": "5eOrwQ=="} ] } }
Kundeninformationen
Die Felder clientID
und clientVersion
sollten eine Clientimplementierung eindeutig identifizieren, nicht einen einzelnen Nutzer. (Clientinformationen werden beim serverseitigen Logging verwendet. Sie können einen beliebigen Namen für die Client-ID wählen. Wir empfehlen jedoch, einen Namen zu wählen, der die wahre Identität des Clients darstellt, z. B. den Namen Ihres Unternehmens, der aus einem Wort besteht und nur Kleinbuchstaben enthält.
Alle Clientstatus
Das Feld clientStates
enthält die Clientstatus für alle Safe Browsing-Listen in der lokalen Datenbank des Clients. (Clientstatus werden im Feld newClientState
der Antwort „threatListUpdates.fetch“ zurückgegeben.)
Safe Browsing-Listen
Mit den Feldern threatTypes
, platformTypes
und threatEntryTypes
werden die Safe Browsing-Listen zusammen mit dem Namen identifiziert. Im Beispiel werden zwei Listen identifiziert: MALWARE/WINDOWS/URL und SOCIAL_ENGINEERING/WINDOWS/URL. Prüfen Sie vor dem Senden einer Anfrage, ob die angegebenen Typkombinationen gültig sind (siehe Safe Browsing-Listen).
Bedrohungs-Hash-Präfixe
Das threatEntries-Array enthält die Hash-Präfixe der URLs, die Sie prüfen möchten.
Das Feld hash
muss genau das Hash-Präfix enthalten, das in der lokalen Datenbank vorhanden ist. Wenn das lokale Hash-Präfix 4 Byte lang ist, muss der Bedrohungseintrag beispielsweise 4 Byte lang sein. Wenn das lokale Hash-Präfix auf 7 Byte verlängert wurde, muss der Bedrohungseintrag 7 Byte lang sein.
In diesem Beispiel enthält die Anfrage drei Hash-Präfixe. Alle drei Präfixe werden mit jeder Safe Browsing-Liste verglichen, um festzustellen, ob ein übereinstimmender Hash in voller Länge vorhanden ist.
Hinweis:Die Update API und die Methode "fullHashes.find" sollten immer das Feld hash
und nicht das Feld URL
verwenden (siehe ThreatEntry).
HTTP POST-Antwort
Im folgenden Beispiel gibt die Antwort die übereinstimmenden Daten, sortiert nach Safe Browsing-Liste, zusammen mit dem Cache und der Wartezeit zurück.
Antwortheader
Der Antwortheader enthält den HTTP-Statuscode und den Inhaltstyp. Clients, die einen anderen Statuscode als HTTP/200 erhalten, müssen einen Backoff durchführen (siehe Anfragehäufigkeit).
HTTP/1.1 200 OK Content-Type: application/json
Antworttext
Der Antworttext enthält die Übereinstimmungsinformationen (die Listennamen und die Hashes in voller Länge, die Metadaten, falls verfügbar, und die Cache-Dauer). Im Beispiel enthält der Antworttext auch eine Mindestwartezeit. Weitere Informationen finden Sie im Antworttext von FullHashes.find und in den Erläuterungen zu diesem Codebeispiel.
{ "matches": [{ "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": { "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4=" }, "threatEntryMetadata": { "entries": [{ "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==", // base64-encoded "malware_threat_type" "value": "TEFORElORw==" // base64-encoded "LANDING" }] }, "cacheDuration": "300.000s" }, { "threatType": "SOCIAL_ENGINEERING", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": { "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA=" }, "threatEntryMetadata": { "entries": [] }, "cacheDuration": "300.000s" }], "minimumWaitDuration": "300.000s", "negativeCacheDuration": "300.000s" }
Übereinstimmungen
Das Matches-Objekt gibt für zwei der Hash-Präfixe einen übereinstimmenden Hash in voller Länge zurück. Die URLs, die diesen Hashes entsprechen, werden als unsicher eingestuft. Für das dritte Hash-Präfix wurde keine Übereinstimmung gefunden. Daher wird nichts zurückgegeben. Die URL, die diesem Hash-Präfix entspricht, wird als sicher angesehen.
Beachten Sie, dass in diesem Beispiel ein Hash in voller Länge einem Hash-Präfix zugeordnet wird. Es können jedoch mehrere vollständige Hashes vorhanden sein, die demselben Hash-Präfix zugeordnet sind.
Metadaten
Das Feld threatEntryMetadata
ist optional und enthält zusätzliche Informationen zur Bedrohungsübereinstimmung. Derzeit sind Metadaten für die Safe Browsing-Liste MALWARE/WINDOWS/URL verfügbar (siehe Metadaten).
Cache-Dauer
Die Felder cacheDuration
und negativeCacheDuration
geben an, wie lange die Hashes als entweder unsicher oder sicher gelten müssen (siehe Caching).
Mindestwartedauer
Das Feld minimumWaitDuration
gibt an, dass der Client 300 Sekunden (5 Minuten) warten muss, bevor er eine weitere FullHashes-Anfrage sendet. Die Antwort kann eine Wartezeit enthalten oder nicht (siehe Anfragehäufigkeit).