Übersicht
Mit der Update API können Ihre Client-Anwendungen Hash-Versionen der Safe Browsing-Listen herunterladen, in einer lokalen Datenbank. URLs können dann lokal geprüft werden. Nur wenn in der lokalen Datenbank eine Übereinstimmung gefunden wird, muss der Client eine Anfrage an die Safe Browsing-Server senden, um zu prüfen, ob die URL in den Safe Browsing-Listen enthalten ist.
Bevor Sie die Update API verwenden können, müssen Sie eine lokale Datenbank einrichten. Safe Browsing bietet ein Go-Paket, mit dem Sie loslegen können. Weitere Informationen finden Sie im Abschnitt „Datenbankeinrichtung“ unter Lokale Datenbanken.
Lokale Datenbank aktualisieren
Um auf dem neuesten Stand zu bleiben, müssen Kunden regelmäßig die Safe Browsing-Listen in ihren lokale Datenbank. Um Bandbreite zu sparen, laden Clients die Hash-Präfixe von URLs und nicht unformatierte URLs. Beispiel: "www.badurl.com/" auf einer Safe Browsing-Liste steht, laden Clients die SHA256-Hash-Präfix dieser URL statt der URL selbst. In den meisten Fällen sind die Hash-Präfixe 4 Byte lang, was bedeutet, dass die durchschnittlichen Bandbreitenkosten für das Herunterladen eines einzelnen Listeneintrags vor der Komprimierung 4 Byte betragen.
Senden Sie zum Aktualisieren der Safe Browsing-Listen in der lokalen Datenbank 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 zur Berücksichtigung von Speicher- und Bandbreitenbeschränkungen. - Die HTTP-
POST-Anfrage gibt entweder eine vollständige Aktualisierung oder eine teilweise Aktualisierung zurück. Die Antwort kann auch eine Mindestwartezeit 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, die API zu ersetzen
Schlüssel für API_KEY in der URL.
POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1 Content-Type: application/json
Anfragetext
Der Anfragetext enthält die Kundeninformationen (ID und Version) und die Aktualisierungsinformationen (Listenname, Listenstatus und Kundeneinschränkungen). Weitere Informationen finden Sie in der threatListUpdates.fetch Anfragetext und die Erklärungen nach dem 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 für die serverseitige Protokollierung verwendet. Sie können einen beliebigen Namen für die Client-ID auswählen. Wir empfehlen jedoch, einen Namen zu wählen, der die wahre Identität des Kunden repräsentiert, z. B. den Namen Ihres Unternehmens, der aus einem einzigen Wort besteht und in Kleinbuchstaben geschrieben ist.
Safe Browsing-Listen
Die Felder threatType, platformType und threatEntryType
zur Identifizierung (Name) der Safe Browsing-Listen kombiniert. Im Beispiel wird eine Liste angegeben: 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 Aktualisierungen 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 berücksichtigen und ein zu starkes Wachstum der Liste 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. Im
Beispiel: Der Client unterstützt nur unkomprimierte Rohdaten. Safe Browsing unterstützt jedoch zusätzliche Komprimierungstypen (siehe Komprimierung).
HTTP POST-Antwort
In diesem Beispiel gibt die Antwort eine Teilaktualisierung 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 den Backoff-Modus aktivieren (siehe Anfragehäufigkeit).
HTTP/1.1 200 OK Content-Type: application/json
Antworttext
Der Antworttext enthält die Aktualisierungsinformationen (Listenname, Antworttyp, Ergänzungen und Löschungen auf die lokale Datenbank anzuwenden, Status und eine Prüfsumme). In diesem Beispiel enthält die Antwort auch eine Mindestwartezeit. Weitere Informationen finden Sie in der threatListUpdates.fetch-Antworttext und die Erklärungen nach dem 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
Das Feld responseType gibt eine teilweise oder vollständige Aktualisierung an. Im Beispiel wird eine teilweise Aktualisierung zurückgegeben, sodass die Antwort sowohl Hinzufügungen als auch Entfernungen enthält. Es können mehrere Sätze von
Ergänzungen, aber nur eine Gruppe von Löschungen
(siehe Datenbankaktualisierungen).
Neuer Clientstatus
Das Feld newClientState enthält den neuen Clientstatus für die neu aktualisierte Safe Browsing-Liste.
Clients müssen den Status des neuen Clients für nachfolgende Aktualisierungsanfragen speichern (das Feld state in der threatListUpdates.fetch-Anfrage oder das Feld clientStates in der fullHashes.find-Anfrage).
Prüfsummen
Anhand der Prüfsumme können Clients prüfen, ob die lokale Datenbank beschädigt ist. Wenn die Prüfsumme nicht übereinstimmt, muss der Client die Datenbank löschen und eine Aktualisierung mit einem leeren state-Feld noch einmal ausführen. Clients in dieser Situation müssen jedoch die Zeitintervalle für Aktualisierungen einhalten (siehe Anfragehäufigkeit).
Mindestwartezeit
Das Feld minimumWaitDuration gibt an, dass der Client 593,44 Sekunden (9,89 Minuten) warten muss
bevor eine weitere Aktualisierungsanfrage gesendet wird. Eine Wartezeit kann in der
(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 Hashing). Der Kunde fragt dann die lokale Datenbank ab, um festzustellen, ob es eine Übereinstimmung gibt. Wenn das Hash-Präfix ist nicht in der lokalen Datenbank vorhanden sind, gilt die URL als sicher und nicht im sicheren Listen durchsuchen).
Wenn das Hash-Präfix in der lokalen Datenbank vorhanden ist (eine Hash-Präfix-Kollision), muss der Client das Hash-Präfix 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 der betreffenden URL in voller Länge übereinstimmt, wird die URL als unsicher eingestuft. Wenn keiner der Hashes in voller Länge mit dem Hash in voller Länge der betreffenden URL übereinstimmt, wird diese URL als sicher betrachtet.
Google erfährt zu keinem Zeitpunkt, welche URLs Sie untersuchen. Google erfährt zwar die Hash-Präfixe von URLs, die Hash-Präfixe liefern jedoch nur wenige Informationen zu den tatsächlichen URLs.
Senden Sie eine HTTP-POST-Anfrage an die Methode fullHashes.find, um zu prüfen, ob sich eine URL auf einer Safe Browsing-Liste befindet:
- Die HTTP-
POST-Anfrage kann bis zu 500 Bedrohungseinträge enthalten. - Die HTTP-
POST-Anfrage enthält die Hash-Präfixe der zu überprüfenden URLs. Wir empfehlen Kunden, mehrere Bedrohungseinträge in einer einzigen Anfrage zusammenzufassen, um die Bandbreitennutzung zu senken. - Die HTTP-
POST-Antwort gibt die übereinstimmenden Hashes in voller Länge sowie die positive und negative Cache-Dauer zurück. Die Antwort kann auch eine Mindestwartezeit 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. Ersetzen Sie in der URL API_KEY durch Ihren API-Schlüssel.
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), den Clientstatus und Informationen zu Bedrohungen (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 nach dem 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, keine
einzelner Nutzer. (Client-Informationen werden beim serverseitigen Logging verwendet. Sie können einen beliebigen Namen für die Kunden-ID auswählen. Wir empfehlen jedoch, einen Namen zu wählen, der die wahre Identität des Kunden repräsentiert, z. B. den Namen Ihres Unternehmens, der aus einem einzigen Wort besteht und in Kleinbuchstaben geschrieben ist.
Alle Kundenstatus
Das Feld clientStates enthält die Clientstatus für alle Safe Browsing-Listen in
in der lokalen Datenbank der Kundschaft. (Client-Status werden im Feld newClientState der
threatListUpdates.fetch die Antwort enthält.)
Safe Browsing-Listen
Die Felder threatTypes, platformTypes und threatEntryTypes werden kombiniert, um die Safe Browsing-Listen zu identifizieren (zu benennen). In diesem Beispiel werden zwei Listen identifiziert: MALWARE/WINDOWS/URL und
SOCIAL_ENGINEERING/WINDOWS/URL. Bevor Sie eine Anfrage senden, sollten Sie sicherstellen,
angegebene sind gültig (siehe Safe Browsing-Listen).
Bedrohungs-Hash-Präfixe
Das ThreatEntries-Array enthält die Hash-Präfixe der URLs, die Sie überprüfen möchten.
Das Feld hash muss das genaue Hash-Präfix enthalten, das in der lokalen Datenbank vorhanden ist. Für
Wenn das lokale Hash-Präfix beispielsweise 4 Byte lang ist, muss der Bedrohungseintrag 4 Byte lang sein. Wenn der Parameter
Das lokale Hash-Präfix wurde auf 7 Byte verlängert, dann muss der Bedrohungseintrag 7 Byte lang sein.
In diesem Beispiel enthält die Anfrage drei Hash-Präfixe. Alle drei Präfixe werden verglichen gegen jede Safe Browsing-Liste, um festzustellen, ob ein übereinstimmender Hash in voller Länge vorhanden ist.
Hinweis:Für die Update API und die Methode „fullHashes.find“ sollte immer das Feld hash verwendet werden.
und niemals das Feld URL (siehe ThreatEntry).
HTTP POST-Antwort
Im folgenden Beispiel gibt die Antwort die übereinstimmenden Daten zurück, die nach Safe Browsing-Liste sortiert sind, sowie die Cache- und Wartedauer.
Antwortheader
Der Antwortheader enthält den HTTP-Statuscode und den Inhaltstyp. Clients, die einen anderen Statuscode als HTTP/200 erhalten, müssen einen Backoff ausfü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). In diesem Beispiel enthält der Antworttext auch eine minimale Wartezeit. Weitere Informationen finden Sie in der fullHashes.find-Antworttext und die Erklärungen nach dem 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 Objekt „Matches“ gibt für zwei der Hash-Präfixe einen übereinstimmenden Hash in voller Länge zurück. Die URLs die diesen Hashes entsprechen, als unsicher eingestuft werden. Für das dritte Hash-Präfix wurde keine Übereinstimmung gefunden. Es wird also nichts zurückgegeben. wird die URL, die diesem Hash-Präfix entspricht, als sicher angesehen.
In diesem Beispiel wird ein Hash in voller Länge einem Hash-Präfix zugeordnet. 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 Bedrohung
Übereinstimmung. Derzeit sind Metadaten für die Safe Browsing-Liste für MALWARE/WINDOWS/URL verfügbar.
(siehe Metadaten).
Cache-Dauer
In den Feldern cacheDuration und negativeCacheDuration wird angegeben, wie lange die Hashes als unsicher bzw. sicher gelten müssen (siehe Caching).
Mindestwartezeiten
Das Feld minimumWaitDuration gibt an, dass der Client 300 Sekunden (5 Minuten) warten muss, bevor er eine weitere Anfrage für vollständige Hash-Werte sendet. Beachten Sie, dass eine Wartezeit in der Antwort enthalten sein kann (siehe Anfragehäufigkeit).