Overview

Hinweis: Diese Dokumentation befindet sich derzeit noch in der Entwicklungsphase. Wir arbeiten an Verbesserungen.

Google Safe Browsing v5 ist eine Weiterentwicklung von Google Safe Browsing v4. Die beiden wichtigsten Änderungen in Version 5 betreffen die Datenaktualität und den Datenschutz bei IP-Adressen. Außerdem wurde die API-Oberfläche verbessert, um die Flexibilität und Effizienz zu erhöhen und unnötige Codezeilen zu reduzieren. Außerdem ist Google Safe Browsing v5 so konzipiert, dass die Migration von v4 einfach ist.

Derzeit bietet Google sowohl Version 4 als auch Version 5 an. Beide sind für die Produktion geeignet. Sie können entweder Version 4 oder Version 5 verwenden. Wir haben noch kein Datum für die Einstellung von Version 4 bekannt gegeben. Sollten wir dies tun, geben wir mindestens ein Jahr Vorabankündigung. Auf dieser Seite wird Version 5 beschrieben. Außerdem finden Sie hier einen Leitfaden zur Migration von Version 4 zu Version 5. Die vollständige Dokumentation zu Version 4 ist weiterhin verfügbar.

Datenaktualität

In Version 5 führen wir den Echtzeitschutz ein. So wird das Problem der Datenaktualität oben umgangen. In Version 4 müssen Clients eine lokale Datenbank herunterladen und verwalten, Prüfungen anhand der lokal heruntergeladenen Bedrohungslisten durchführen und dann, wenn eine teilweise Übereinstimmung des Präfixes vorliegt, eine Anfrage zum Herunterladen des vollständigen Hashwerts senden. In Version 5 sollten Clients zwar weiterhin eine lokale Datenbank mit Bedrohungslisten herunterladen und verwalten, aber jetzt auch eine Liste mit Websites herunterladen, die wahrscheinlich harmlos sind (Global Cache). Außerdem müssen sie sowohl eine lokale Prüfung für diesen Global Cache als auch eine lokale Prüfung der Bedrohungsliste durchführen. Wenn es entweder eine teilweise Übereinstimmung des Präfixes für Bedrohungslisten oder keine Übereinstimmung im Global Cache gibt, muss eine Anfrage zum Herunterladen der vollständigen Hash-Werte gesendet werden. Weitere Informationen zur vom Kunden erforderlichen lokalen Verarbeitung finden Sie unten im Verfahren. Das bedeutet eine Umstellung von „Standardmäßig zulassen“ zu „Standardmäßig prüfen“, was den Schutz angesichts der schnelleren Ausbreitung von Bedrohungen im Web verbessern kann. Mit anderen Worten: Dieses Protokoll wurde entwickelt, um nahezu in Echtzeit Schutz zu bieten. Wir möchten, dass Kunden von aktuelleren Google Safe Browsing-Daten profitieren.

IP-Datenschutz

Google Safe Browsing (Version 4 oder 5) verarbeitet beim Ausführen von Anfragen keine Daten, die mit der Identität eines Nutzers verknüpft sind. Gesendete Cookies werden ignoriert. Google kennt die IP-Adressen der Absender der Anfragen, verwendet sie aber nur für wichtige Netzwerkfunktionen (z.B. zum Senden von Antworten) und zur Abwehr von DoS-Angriffen.

Gleichzeitig mit Version 5 führen wir eine zugehörige API ein, die Safe Browsing Oblivious HTTP Gateway API. Dabei werden die IP-Adressen der Endnutzer mithilfe von Oblivious HTTP vor Google verborgen. Dabei wird ein nicht korrupter Drittanbieter damit beauftragt, eine verschlüsselte Version der Nutzeranfrage zu verarbeiten und an Google weiterzuleiten. Der Drittanbieter hat also nur Zugriff auf die IP-Adressen und Google nur auf den Inhalt der Anfrage. Der Drittanbieter betreibt ein Oblivious HTTP-Relay (z. B. diesen Dienst von Fastly) und Google betreibt das Oblivious HTTP-Gateway. Dies ist eine optionale Companion API. Wenn Sie die Funktion in Verbindung mit Google Safe Browsing verwenden, werden die IP-Adressen der Endnutzer nicht mehr an Google gesendet.

Betriebsarten

Bei Google Safe Browsing v5 können Kunden zwischen drei Betriebsmodi wählen.

Echtzeitmodus

Wenn Kunden Google Safe Browsing v5 im Echtzeitmodus verwenden, verwalten sie in ihrer lokalen Datenbank Folgendes: (i) einen globalen Cache mit wahrscheinlich harmlosen Websites, formatiert als SHA256-Hashes von URL-Ausdrücken mit Host-Suffix/Pfad-Präfix, (ii) eine Reihe von Bedrohungslisten, formatiert als SHA256-Hash-Präfixe von URL-Ausdrücken mit Host-Suffix/Pfad-Präfix. Wenn der Client eine bestimmte URL prüfen möchte, wird eine lokale Prüfung mit dem globalen Cache durchgeführt. Wenn diese Prüfung bestanden wird, wird eine Prüfung in lokalen Bedrohungslisten durchgeführt. Andernfalls fährt der Client mit der Echtzeit-Hash-Überprüfung fort, wie unten beschrieben.

Neben der lokalen Datenbank verwaltet der Client einen lokalen Cache. Ein solcher lokaler Cache muss sich nicht im nichtflüchtigen Speicher befinden und kann bei Speichermangel gelöscht werden.

Eine detaillierte Beschreibung des Verfahrens finden Sie unten.

Modus für lokale Listen

Wenn Clients Google Safe Browsing v5 in diesem Modus verwenden, ähnelt das Clientverhalten der Update API v4, mit der Ausnahme, dass die verbesserte API-Oberfläche von v5 verwendet wird. Kunden verwalten in ihrer lokalen Datenbank eine Reihe von Bedrohungslisten, die als SHA256-Hash-Präfixe von URL-Ausdrücken mit Host-Suffix/Pfad-Präfix formatiert sind. Wenn der Client eine bestimmte URL prüfen möchte, wird eine Prüfung anhand der lokalen Bedrohungsliste durchgeführt. Nur wenn eine Übereinstimmung gefunden wird, stellt der Client eine Verbindung zum Server her, um die Überprüfung fortzusetzen.

Wie oben beschrieben, verwaltet der Client auch einen lokalen Cache, der sich nicht im nichtflüchtigen Speicher befinden muss.

Echtzeitmodus ohne Speicherung

Wenn Clients Google Safe Browsing v5 im Echtzeitmodus ohne Speicher verwenden, muss der Client keine persistente lokale Datenbank verwalten. Der Client muss jedoch weiterhin einen lokalen Cache verwalten. Ein solcher lokaler Cache muss sich nicht im nichtflüchtigen Speicher befinden und kann bei Speichermangel gelöscht werden.

Wenn der Client eine bestimmte URL prüfen möchte, stellt er immer eine Verbindung zum Server her, um die Prüfung durchzuführen. Dieser Modus ähnelt dem, was Clients der Lookup API v4 implementieren können.

Im Vergleich zum Echtzeitmodus kann dieser Modus mehr Netzwerkbandbreite verbrauchen, ist aber möglicherweise besser geeignet, wenn es für den Client nicht praktisch ist, einen dauerhaften lokalen Status aufrechtzuerhalten.

Ablauf der URL-Prüfung in Echtzeit

Dieser Vorgang wird verwendet, wenn der Client den Echtzeitbetrieb auswählt.

Bei diesem Verfahren wird eine einzelne URL u übergeben und SAFE, UNSAFE oder UNSURE zurückgegeben. Wenn SAFE zurückgegeben wird, wird die URL von Google Safe Browsing als sicher eingestuft. Wenn UNSAFE zurückgegeben wird, wird die URL von Google Safe Browsing als potenziell unsicher eingestuft und es sollten entsprechende Maßnahmen ergriffen werden, z. B. eine Warnung für den Endnutzer anzeigen, eine empfangene Nachricht in den Spamordner verschieben oder eine zusätzliche Bestätigung des Nutzers vor dem Fortfahren verlangen. Wenn UNSURE zurückgegeben wird, sollte danach die folgende lokale Prüfung durchgeführt werden.

  1. Angenommen, expressions ist eine Liste von Suffix-/Präfixausdrücken, die von der URL u generiert wurden.
  2. Angenommen, expressionHashes ist eine Liste, deren Elemente die SHA256-Hashes der einzelnen Ausdrücke in expressions sind.
  3. Für jede hash von expressionHashes:
    1. Wenn hash im globalen Cache gefunden wird, gib UNSURE zurück.
  4. Angenommen, expressionHashPrefixes ist eine Liste, deren Elemente die ersten 4 Byte jedes Hashes in expressionHashes sind.
  5. Für jede expressionHashPrefix von expressionHashPrefixes:
    1. expressionHashPrefix im lokalen Cache nachschlagen
    2. Wenn der im Cache gespeicherte Eintrag gefunden wird:
      1. Prüfen, ob die aktuelle Zeit größer als die Ablaufzeit ist.
      2. Wenn er größer ist:
        1. Entfernen Sie den gefundenen Cache-Eintrag aus dem lokalen Cache.
        2. Fahren Sie mit dem Loop fort.
      3. Ist der Wert nicht höher:
        1. Entfernen Sie diese expressionHashPrefix aus expressionHashPrefixes.
        2. Prüfen Sie, ob der entsprechende vollständige Hashwert in expressionHashes im Cache-Eintrag gefunden wird.
        3. Wenn gefunden, gib UNSAFE zurück.
        4. Wenn nicht, fahren Sie mit der Schleife fort.
    3. Wenn der Eintrag im Cache nicht gefunden wird, fahren Sie mit der Schleife fort.
  6. Senden Sie expressionHashPrefixes mithilfe von RPC SearchHashes oder der REST-Methode hashes.search an den Google Safe Browsing v5-Server. Wenn ein Fehler aufgetreten ist (z. B. Netzwerk- oder HTTP-Fehler), gib UNSURE zurück. Andernfalls ist „response“ die vom SB-Server empfangene response, eine Liste mit vollständigen Hashes sowie einigen zusätzlichen Informationen zur Art der Bedrohung (Social Engineering, Malware usw.) und zum Ablaufzeitpunkt des Caches expiration.
  7. Für jede fullHash von response:
    1. Fügen Sie fullHash zusammen mit expiration in den lokalen Cache ein.
  8. Für jede fullHash von response:
    1. Angenommen, isFound ist das Ergebnis der Suche nach fullHash in expressionHashes.
    2. Wenn isFound auf „False“ (Falsch) gesetzt ist, fahren Sie mit der Schleife fort.
    3. Wenn isFound „wahr“ ist, wird UNSAFE zurückgegeben.
  9. Gib SAFE zurück.

Dieses Protokoll gibt zwar an, wann der Client expressionHashPrefixes an den Server sendet, aber nicht genau, wie sie gesendet werden. Es ist beispielsweise zulässig, dass der Client alle expressionHashPrefixes in einer einzigen Anfrage sendet. Es ist auch zulässig, dass der Client jedes einzelne Präfix in expressionHashPrefixes in separaten Anfragen an den Server sendet (ggf. parallel). Es ist auch zulässig, dass der Client zusammen mit den Hash-Präfixen in expressionHashPrefixes nicht zusammenhängende oder zufällig generierte Hash-Präfixe sendet, solange die Anzahl der in einer einzelnen Anfrage gesendeten Hash-Präfixe 30 nicht überschreitet.

URL-Prüfung der LocalThreat List

Dieser Vorgang wird verwendet, wenn der Kunde den lokalen Listenmodus auswählt. Sie wird auch verwendet, wenn der Client bei der oben beschriebenen RealTimeCheck-Prozedur den Wert UNSURE zurückgibt.

Bei diesem Verfahren wird eine einzelne URL u übergeben und SAFE oder UNSAFE zurückgegeben.

  1. Angenommen, expressions ist eine Liste von Suffix-/Präfixausdrücken, die von der URL u generiert wurden.
  2. Angenommen, expressionHashes ist eine Liste, deren Elemente die SHA256-Hashes der einzelnen Ausdrücke in expressions sind.
  3. Angenommen, expressionHashPrefixes ist eine Liste, deren Elemente die ersten 4 Byte jedes Hashwerts in expressionHashes sind.
  4. Für jede expressionHashPrefix von expressionHashPrefixes:
    1. expressionHashPrefix im lokalen Cache nachschlagen
    2. Wenn der im Cache gespeicherte Eintrag gefunden wird:
      1. Prüfen, ob die aktuelle Zeit größer als die Ablaufzeit ist.
      2. Wenn er größer ist:
        1. Entfernen Sie den gefundenen Cache-Eintrag aus dem lokalen Cache.
        2. Fahren Sie mit dem Loop fort.
      3. Ist der Wert nicht höher:
        1. Entfernen Sie diese expressionHashPrefix aus expressionHashPrefixes.
        2. Prüfen Sie, ob der entsprechende vollständige Hashwert in expressionHashes im Cache-Eintrag gefunden wird.
        3. Wenn gefunden, gib UNSAFE zurück.
        4. Wenn nicht, fahren Sie mit der Schleife fort.
    3. Wenn der Eintrag im Cache nicht gefunden wird, fahren Sie mit der Schleife fort.
  5. Für jede expressionHashPrefix von expressionHashPrefixes:
    1. Suchen Sie in der Datenbank der lokalen Bedrohungsliste nach expressionHashPrefix.
    2. Wenn die expressionHashPrefix nicht in der Datenbank der lokalen Bedrohungsliste gefunden werden kann, entfernen Sie sie aus expressionHashPrefixes.
  6. Senden Sie expressionHashPrefixes mithilfe von RPC SearchHashes oder der REST-Methode hashes.search an den Google Safe Browsing v5-Server. Wenn ein Fehler aufgetreten ist (z. B. Netzwerk- oder HTTP-Fehler), gib SAFE zurück. Andernfalls ist „response“ die vom SB-Server empfangene response, eine Liste mit vollständigen Hashes sowie einigen zusätzlichen Informationen zur Art der Bedrohung (Social Engineering, Malware usw.) und zum Ablaufzeitpunkt des Caches expiration.
  7. Für jede fullHash von response:
    1. Fügen Sie fullHash zusammen mit expiration in den lokalen Cache ein.
  8. Für jede fullHash von response:
    1. Angenommen, isFound ist das Ergebnis der Suche nach fullHash in expressionHashes.
    2. Wenn isFound auf „False“ (Falsch) gesetzt ist, fahren Sie mit der Schleife fort.
    3. Wenn isFound „wahr“ ist, wird UNSAFE zurückgegeben.
  9. Gib SAFE zurück.

URL-Prüfung in Echtzeit ohne lokale Datenbank

Dieser Vorgang wird verwendet, wenn der Client den Echtzeitmodus ohne Speicher auswählt.

Bei diesem Verfahren wird eine einzelne URL u übergeben und SAFE oder UNSAFE zurückgegeben.

  1. Angenommen, expressions ist eine Liste von Suffix-/Präfixausdrücken, die von der URL u generiert wurden.
  2. Angenommen, expressionHashes ist eine Liste, deren Elemente die SHA256-Hashes der einzelnen Ausdrücke in expressions sind.
  3. Angenommen, expressionHashPrefixes ist eine Liste, deren Elemente die ersten 4 Byte jedes Hashwerts in expressionHashes sind.
  4. Für jede expressionHashPrefix von expressionHashPrefixes:
    1. expressionHashPrefix im lokalen Cache nachschlagen
    2. Wenn der im Cache gespeicherte Eintrag gefunden wird:
      1. Prüfen, ob die aktuelle Zeit größer als die Ablaufzeit ist.
      2. Wenn er größer ist:
        1. Entfernen Sie den gefundenen Cache-Eintrag aus dem lokalen Cache.
        2. Fahren Sie mit dem Loop fort.
      3. Ist der Wert nicht höher:
        1. Entfernen Sie diese expressionHashPrefix aus expressionHashPrefixes.
        2. Prüfen Sie, ob der entsprechende vollständige Hashwert in expressionHashes im Cache-Eintrag gefunden wird.
        3. Wenn gefunden, gib UNSAFE zurück.
        4. Wenn nicht, fahren Sie mit der Schleife fort.
    3. Wenn der Eintrag im Cache nicht gefunden wird, fahren Sie mit der Schleife fort.
  5. Senden Sie expressionHashPrefixes mithilfe von RPC SearchHashes oder der REST-Methode hashes.search an den Google Safe Browsing v5-Server. Wenn ein Fehler aufgetreten ist (z. B. Netzwerk- oder HTTP-Fehler), gib SAFE zurück. Andernfalls ist „response“ die vom SB-Server empfangene response, eine Liste mit vollständigen Hashes sowie einigen zusätzlichen Informationen zur Art der Bedrohung (Social Engineering, Malware usw.) und zum Ablaufzeitpunkt des Caches expiration.
  6. Für jede fullHash von response:
    1. Fügen Sie fullHash zusammen mit expiration in den lokalen Cache ein.
  7. Für jede fullHash von response:
    1. Angenommen, isFound ist das Ergebnis der Suche nach fullHash in expressionHashes.
    2. Wenn isFound auf „False“ (Falsch) gesetzt ist, fahren Sie mit der Schleife fort.
    3. Wenn isFound „wahr“ ist, wird UNSAFE zurückgegeben.
  8. Gib SAFE zurück.

Genau wie bei der URL-Prüfung in Echtzeit wird hier nicht genau angegeben, wie die Hash-Präfixe an den Server gesendet werden sollen. Es ist beispielsweise zulässig, dass der Client alle expressionHashPrefixes in einer einzigen Anfrage sendet. Es ist auch zulässig, dass der Client jedes einzelne Präfix in expressionHashPrefixes in separaten Anfragen an den Server sendet (ggf. parallel). Es ist auch zulässig, dass der Client zusammen mit den Hash-Präfixen in expressionHashPrefixes nicht zusammenhängende oder zufällig generierte Hash-Präfixe sendet, solange die Anzahl der in einer einzelnen Anfrage gesendeten Hash-Präfixe 30 nicht überschreitet.

Beispiele für Anforderungen

In diesem Abschnitt werden einige Beispiele für die direkte Verwendung der HTTP API zum Zugriff auf Google Safe Browsing dokumentiert. Im Allgemeinen wird die Verwendung einer generierten Sprachbindung empfohlen, da sie die Codierung und Dekodierung auf bequeme Weise automatisch übernimmt. Weitere Informationen finden Sie in der Dokumentation für diese Bindung.

Hier ist ein Beispiel für eine HTTP-Anfrage mit der Methode „hashes.search“:

GET https://safebrowsing.googleapis.com/v5/hashes:search?key=INSERT_YOUR_API_KEY_HERE&hashPrefixes=WwuJdQ

Der Antworttext ist eine im Protokoll-Buffer-Format vorliegende Nutzlast, die du dann decodieren kannst.

Hier ist ein Beispiel für eine HTTP-Anfrage mit der Methode hashLists.batchGet:

GET https://safebrowsing.googleapis.com/v5alpha1/hashLists:batchGet?key=INSERT_YOUR_API_KEY_HERE&names=se&names=mw-4b

Der Antworttext ist wieder eine im Protokoll-Buffer-Format vorliegende Nutzlast, die Sie dann decodieren können.