Diese Seite wurde von der Cloud Translation API übersetzt.

Safe Browsing Update API (v4)

Ü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

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).