Diese Seite wurde von der Cloud Translation API übersetzt.

Overview

Einleitung

Hinweis: Diese Dokumentation befindet sich noch in der Entwicklungsphase. Verbesserungen sind schon in naher Zukunft zu erwarten.

Google Safe Browsing v5 ist eine Weiterentwicklung von Google Safe Browsing v4. Die beiden wichtigsten Änderungen in Version 5 sind Datenaktualität und IP-Datenschutz. Darüber hinaus wurde die API-Oberfläche verbessert, um die Flexibilität und Effizienz zu erhöhen und das Aufblähen zu reduzieren. Darüber hinaus wurde Google Safe Browsing v5 entwickelt, um die Migration von v4 einfach zu machen.

Derzeit bietet Google sowohl Version 4 als auch Version 5 an und beide gelten als produktionsreif. Sie können v4 oder v5 verwenden. Wir haben noch kein Datum für die Einstellung von Version 4 bekannt gegeben. Wenn dies der Fall ist, werden wir Sie mit einer Frist von mindestens einem Jahr ankündigen. Auf dieser Seite finden Sie eine Beschreibung von Version 5 sowie eine Migrationsanleitung für Version 4 zu Version 5. Die vollständige Dokumentation für Version 4 ist weiterhin verfügbar.

Datenaktualität

Eine wesentliche Verbesserung von Google Safe Browsing Version 5 gegenüber Version 4 (insbesondere die Update API Version 4) ist die Datenaktualität und -abdeckung. Da der Schutz stark von der vom Client verwalteten lokalen Datenbank abhängt, sind die Verzögerung und die Größe der lokalen Datenbankaktualisierung hauptsächlich für den verpassten Schutz verantwortlich. In Version 4 benötigt der typische Client 20 bis 50 Minuten, um die aktuelle Version der Bedrohungslisten abzurufen. Leider breiten sich Phishing-Angriffe schnell aus: Bis 2021 hatten 60% der Angriffe auf Websites weniger als zehn Minuten. Unsere Analysen zeigen, dass etwa 25 bis 30% des fehlenden Phishing-Schutzes auf diese veralteten Daten zurückzuführen sind. Darüber hinaus sind einige Geräte nicht dafür geeignet, die gesamten Bedrohungslisten von Google Safe Browsing zu verwalten, die im Laufe der Zeit immer umfangreicher werden.

In Version 5 wird ein Betriebsmodus eingeführt, der als Echtzeitschutz bezeichnet wird. Dadurch wird das obige Problem mit veralteten Daten umgangen. In Version 4 wird erwartet, dass Clients eine lokale Datenbank herunterladen und verwalten, Prüfungen anhand der lokal heruntergeladenen Bedrohungslisten durchführen und bei einer teilweisen Präfixübereinstimmung eine Anfrage zum Herunterladen des vollständigen Hashs ausführen. Auch wenn die Clients weiterhin eine lokale Datenbank mit Bedrohungslisten herunterladen und verwalten sollten, müssen sie jetzt auch eine Liste wahrscheinlich harmloser Websites (dem so genannten globalen Cache) herunterladen und sowohl eine lokale Prüfung für diesen globalen Cache als auch eine lokale Überprüfung der Bedrohungsliste durchführen. Wenn schließlich eine teilweise Präfixübereinstimmung für Bedrohungslisten oder eine Nichtübereinstimmung im globalen Cache vorliegt, wird eine Anfrage zum Herunterladen der vollständigen Hashes ausgeführt. Weitere Informationen über die vom Kunden geforderte lokale Verarbeitung finden Sie unten. Dies stellt einen Wechsel von „Standardmäßig zulassen“ zu „Standardmäßig prüfen“ dar, was den Schutz angesichts der schnelleren Verbreitung von Bedrohungen im Web verbessern kann. Mit anderen Worten: Dieses Protokoll wurde entwickelt, um Schutz nahezu in Echtzeit zu bieten. Unser Ziel ist es, dass unsere Kunden von aktuelleren Google Safe Browsing-Daten profitieren.

IP-Datenschutz

Google Safe Browsing (v4 oder v5) verarbeitet bei der Verarbeitung von Anfragen keine Daten, die mit der Identität eines Nutzers in Verbindung stehen. Gesendete Cookies werden ignoriert. Die ursprünglichen IP-Adressen der Anfragen sind Google bekannt, aber Google verwendet die IP-Adressen nur für grundlegende Netzwerkanforderungen (z.B. zum Senden von Antworten) und für Anti-DoS-Zwecke.

Parallel zu Version 5 führen wir eine sogenannte Safe Browsing Oblivious HTTP Gateway API ein. Dabei wird Oblivious HTTP verwendet, um die IP-Adressen von Endnutzern vor Google auszublenden. Dabei wird eine verschlüsselte Version der Nutzeranfrage von einem nicht kollidierenden Dritten verarbeitet und dann an Google weitergeleitet. Der Drittanbieter hat also nur Zugriff auf die IP-Adressen und Google hat nur Zugriff auf den Inhalt der Anfrage. Der Drittanbieter betreibt einen Oblivious HTTP Relay (wie diesen Dienst von Fastly) und Google betreibt das Oblivious HTTP Gateway. Dies ist eine optionale Companion-API. Bei Verwendung in Verbindung mit Google Safe Browsing werden die IP-Adressen der Endnutzer nicht mehr an Google gesendet.

Angemessene Nutzung

Zulässige Nutzung

Die Safe Browsing API ist nur für nicht kommerzielle Zwecke bestimmt, d. h. nicht zu Umsatz- oder Umsatzgenerierungszwecken. Wenn Sie eine Lösung für kommerzielle Zwecke benötigen, lesen Sie Web Risk.

Preise

Alle Google Safe Browsing APIs sind kostenlos.

Kontingente

Entwicklern wird beim Aktivieren der Safe Browsing API ein Standardnutzungskontingent zugewiesen. Die aktuelle Zuweisung und Nutzung finden Sie in der Google Developer Console. Wenn Sie davon ausgehen, dass Sie Ihr derzeit zugeteiltes Kontingent überschreiten, können Sie auf der Seite „Kontingente“ der Developer Console ein zusätzliches Kontingent anfordern. Wir prüfen diese Anfragen und benötigen einen Kontakt, wenn wir ein höheres Kontingent beantragen, um sicherzustellen, dass unsere Dienstverfügbarkeit den Anforderungen aller Nutzer entspricht.

Geeignete URLs

Google Safe Browsing reagiert auf URLs, die normalerweise in der Adressleiste eines Browsers angezeigt werden. Sie ist nicht für den Abgleich mit Unterressourcen vorgesehen (wie JavaScript-Code oder Bild, auf das eine HTML-Datei verweist, oder eine von JavaScript initiierte WebSocket-URL). Solche Unterressourcen-URLs sollten nicht mit Google Safe Browsing abgeglichen werden.

Wenn der Besuch einer URL zu einer Weiterleitung führt (z. B. HTTP 301), muss die weitergeleitete URL mit Google Safe Browsing abgeglichen werden. Durch clientseitige URL-Manipulationen wie History.pushState werden neue URLs nicht mit Google Safe Browsing abgeglichen.

Nutzerwarnungen

Wenn Sie Google Safe Browsing verwenden, um Nutzer vor Risiken bestimmter Webseiten zu warnen, gelten die folgenden Richtlinien.

Diese Richtlinien tragen dazu bei, Sie und Google vor Missverständnissen zu schützen, indem deutlich wird, dass die Seite nicht zu 100% sicher ist, dass es sich um eine unsichere Webressource handelt, und dass die Warnungen lediglich ein mögliches Risiko aufzeigen.

In Ihrer für Nutzer sichtbaren Warnung dürfen Sie Nutzer nicht glauben, dass die betreffende Seite ohne Zweifel eine unsichere Webressource ist. Wenn Sie auf die identifizierte Seite oder auf die potenziellen Risiken verweisen, die sie für Nutzer darstellen kann, müssen Sie die Warnung mit Begriffen wie „verdächtig“, „potenziell“, „möglich“, „wahrscheinlich“ definieren.
Ihre Warnung muss dem Nutzer ermöglichen, mehr zu erfahren, indem er die Definition von Google zu den verschiedenen Bedrohungen liest. Wir empfehlen Ihnen die folgenden Links:
- Social Engineering: https://developers.google.com/search/docs/monitor-debug/security/social-engineering
- Malware und unerwünschte Software: https://developers.google.com/search/docs/monitor-debug/security/malware
- Potenziell schädliche Apps (nur Android): https://developers.google.com/android/play-protect/potentially-harmful-applications
Wenn Sie Warnungen für Seiten anzeigen, die vom Safe Browsing-Dienst als riskant eingestuft werden, müssen Sie Google eine entsprechende Quellenangabe machen. Fügen Sie dazu die Zeile „Advisory provided by Google“ mit einem Link zu den Safe Browsing-Hinweisen ein. Wenn für Ihr Produkt Warnungen aufgrund anderer Quellen angezeigt werden, dürfen Sie die Google-Quellenangabe nicht in Warnungen aufnehmen, die aus nicht von Google stammenden Daten abgeleitet werden.
In Ihrer Produktdokumentation müssen Sie einen Hinweis an die Nutzer enthalten, dass der Schutz von Google Safe Browsing nicht perfekt ist. Sie muss darüber informieren, dass die Möglichkeit sowohl falsch positive (sichere Websites, die als riskant gekennzeichnet) als auch falsch negativer Ergebnisse (nicht als riskant gekennzeichnete Websites) auftreten können. Wir empfehlen die Verwendung der folgenden Sprache:

Google arbeitet daran, möglichst genaue und aktuelle Informationen zu unsicheren Webressourcen zur Verfügung zu stellen. Google kann jedoch nicht garantieren, dass die Informationen vollständig und fehlerfrei sind: Einige riskante Websites werden möglicherweise nicht identifiziert und einige sichere Websites werden fälschlicherweise identifiziert.

Betriebsmodi

Mit Google Safe Browsing v5 können Clients 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, der als SHA256-Hashes von URL-Ausdrücken mit Hostsuffix/Pfadpräfix formatiert ist, (ii) eine Reihe von Bedrohungslisten im Format SHA256-Hash-Präfixe von URL-Ausdrücken mit Hostsuffix/Pfadpräfix. Grundsätzlich gilt, dass immer dann, wenn der Client eine bestimmte URL überprüfen möchte, eine lokale Prüfung mithilfe des globalen Cache durchgeführt wird. Wenn diese Prüfung bestanden wird, wird eine Prüfung auf lokale Bedrohungslisten durchgeführt. Andernfalls fährt der Client wie unten beschrieben mit der Hash-Prüfung in Echtzeit fort.

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

Eine detaillierte Beschreibung der Vorgehensweise finden Sie unten.

Modus für lokale Liste

Wenn Clients Google Safe Browsing v5 in diesem Modus verwenden, verhält sich das Client ähnlich wie die Update API v4, außer dass die verbesserte API-Oberfläche von v5 verwendet wird. Clients führen in ihrer lokalen Datenbank eine Reihe von Bedrohungslisten, die als SHA256-Hash-Präfixe von URL-Ausdrücken mit Hostsuffix/Pfadpräfix formatiert sind. Immer wenn der Client eine bestimmte URL überprüfen möchte, wird eine Prüfung anhand der lokalen Bedrohungsliste durchgeführt. Falls eine Übereinstimmung vorliegt, stellt der Client eine Verbindung zum Server her, um die Prüfung fortzusetzen.

Wie im obigen Beispiel unterhält der Client auch einen lokalen Cache, der sich nicht im nichtflüchtigen Speicher befinden muss.

Echtzeitmodus ohne Speicher

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

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

Im Vergleich zum Echtzeitmodus benötigt dieser Modus unter Umständen mehr Netzwerkbandbreite. Er eignet sich jedoch besser, wenn es für den Client unpraktisch ist, den dauerhaften lokalen Zustand beizubehalten.

URLs prüfen

Dieser Abschnitt enthält detaillierte Spezifikationen dazu, wie Clients URLs prüfen.

Kanonisierung von URLs

Bevor URLs geprüft werden, sollte der Client eine Kanonisierung für diese URL durchführen.

Zunächst nehmen wir an, dass der Client die URL geparst und gemäß RFC 2396 gültig gemacht hat. Wenn die URL einen internationalisierten Domainnamen (IDN) verwendet, sollte der Client die URL in ASCII-Punycode-Darstellung umwandeln. Die URL muss eine Pfadkomponente enthalten, das heißt, nach der Domain muss mindestens ein Schrägstrich folgen (http://google.com/ statt http://google.com).

Entfernen Sie zuerst die Tabulatorzeichen (0x09), CR (0x0d) und LF (0x0a) aus der URL. Entfernen Sie keine Escapesequenzen für diese Zeichen (z.B. %0a).

Zweitens: Wenn die URL in einem Fragment endet, entfernen Sie das Fragment. Kürzen Sie beispielsweise http://google.com/#frag auf http://google.com/.

Setzen Sie drittens wiederholt Prozentzeichen für die URL aus dem Escape-Format, bis sie keine weiteren Escapezeichen enthält. Dies kann dazu führen, dass die URL ungültig wird.

So kanonisieren Sie den Hostnamen:

Extrahieren Sie den Hostnamen aus der URL und führen Sie dann folgende Schritte aus:

Entfernen Sie alle vor- und nachgestellten Punkte.
Ersetzen Sie aufeinanderfolgende Punkte durch einen einzelnen Punkt.
Wenn der Hostname als IPv4-Adresse geparst werden kann, normalisieren Sie ihn auf vier durch Punkte getrennte Dezimalwerte. Der Client sollte alle zulässigen Codierungen von IP-Adressen verarbeiten können, einschließlich Oktal-, Hex- und weniger als vier Komponenten.
Wenn der Hostname als in Klammern gesetzte IPv6-Adresse geparst werden kann, normalisieren Sie ihn, indem Sie unnötige führende Nullen in den Komponenten entfernen und Null-Komponenten mithilfe der Double-Doppel-Syntax minimieren. Beispielsweise sollte [2001:0db8:0000::1] in [2001:db8::1] umgewandelt werden. Wenn der Hostname einer der folgenden speziellen IPv6-Adresstypen ist, wandeln Sie ihn in IPv4 um:
- Eine IPv4-zugeordnete IPv6-Adresse wie [::ffff:1.2.3.4], die in 1.2.3.4 umgewandelt werden sollte.
- Eine NAT64-Adresse mit dem bekannten Präfix 64:ff9b::/96, z. B. [64:ff9b::1.2.3.4], das in 1.2.3.4 umgewandelt werden sollte.
Verwenden Sie Kleinbuchstaben für den gesamten String.

So kanonisieren Sie den Pfad:

Lösen Sie die Sequenzen /../ und /./ im Pfad auf, indem Sie /./ durch / ersetzen und /../ zusammen mit der vorherigen Pfadkomponente entfernen.
Ersetzen Sie aufeinanderfolgende Schrägstriche durch einen Schrägstrich.

Wenden Sie diese Pfadkanonisierung nicht auf die Suchparameter an.

Stellen Sie in der URL ein Escapezeichen (%) für alle Zeichen ein, die <= ASCII 32, >= 127, # oder % sind. Die Escape-Zeichen müssen aus Großbuchstaben bestehen.

Host-Suffix-Pfad-Präfix-Ausdrücke

Nachdem die URL kanonisiert wurde, besteht der nächste Schritt darin, die Suffix-/Präfixausdrücke zu erstellen. Jeder Suffix-/Präfixausdruck besteht aus einem Hostsuffix (oder vollständigen Host) und einem Pfadpräfix (oder vollständigem Pfad).

Der Client kann bis zu 30 verschiedene Kombinationen aus Host-Suffix und Pfadpräfix bilden. Bei diesen Kombinationen werden nur die Host- und Pfadkomponenten der URL verwendet. Schema, Nutzername, Passwort und Port werden verworfen. Wenn die URL Suchparameter enthält, enthält mindestens eine Kombination den vollständigen Pfad und die Suchparameter.

Für den Host versucht der Client höchstens fünf verschiedene Strings. Sie sind:

Wenn der Hostname kein IPv4- oder IPv6-Literal ist, werden bis zu vier Hostnamen gebildet, indem sie mit der Domain eTLD+1 beginnen und nachfolgende führende Komponenten hinzufügen. eTLD+1 sollte anhand der öffentlichen Suffixliste bestimmt werden. Zum Beispiel würde a.b.example.com zur eTLD+1-Domain von example.com sowie zum Host mit einer zusätzlichen Hostkomponente b.example.com führen.
Der genaue Hostname in der URL. Nach dem vorherigen Beispiel würde a.b.example.com geprüft werden.

Für den Pfad versucht der Client höchstens sechs verschiedene Strings. Sie sind:

Der genaue Pfad der URL, einschließlich der Suchparameter.
Der genaue Pfad der URL ohne Abfrageparameter.
Die vier Pfade, die gebildet werden, indem am Stamm (/) begonnen und die Pfadkomponenten nacheinander angehängt werden, einschließlich eines nachgestellten Schrägstrichs.

Die folgenden Beispiele veranschaulichen das Überprüfungsverhalten:

Für die URL http://a.b.com/1/2.html?param=1 versucht der Client diese möglichen Strings:

a.b.com/1/2.html?param=1
a.b.com/1/2.html
a.b.com/
a.b.com/1/
b.com/1/2.html?param=1
b.com/1/2.html
b.com/
b.com/1/

Für die URL http://a.b.c.d.e.f.com/1.html versucht der Client diese möglichen Strings:

a.b.c.d.e.f.com/1.html
a.b.c.d.e.f.com/
c.d.e.f.com/1.html
c.d.e.f.com/
d.e.f.com/1.html
d.e.f.com/
e.f.com/1.html
e.f.com/
f.com/1.html
f.com/

Hinweis: Überspringen Sie b.c.d.e.f.com, da wir nur die letzten fünf Hostnamenkomponenten und den vollständigen Hostnamen verwenden.

Für die URL http://1.2.3.4/1/ versucht der Client diese möglichen Strings:

1.2.3.4/1/
1.2.3.4/

Für die URL http://example.co.uk/1 versucht der Client diese möglichen Strings:

example.co.uk/1
example.co.uk/

Hashing

Google Safe Browsing verwendet ausschließlich SHA256 als Hash-Funktion. Diese Hash-Funktion sollte auf die oben genannten Ausdrücke angewendet werden.

Der vollständige 32-Byte-Hash wird je nach Situation auf 4 Byte, 8 Byte oder 16 Byte gekürzt:

Bei Verwendung der hashes.search-Methode müssen die Hashes in der Anfrage derzeit auf genau 4 Byte gekürzt werden. Wenn Sie in dieser Anfrage zusätzliche Byte senden, wird der Datenschutz für Nutzer beeinträchtigt.
Beim Herunterladen der Listen für die lokale Datenbank mithilfe der hashList.get-Methode oder der hashLists.batchGet-Methode wird die Länge der vom Server gesendeten Hashes sowohl von der Art der Liste als auch von der vom Client bevorzugten Hash-Länge beeinflusst, die über den Parameter desired_hash_length übermittelt wird.

URL-Prüfung in Echtzeit

Dieses Verfahren wird verwendet, wenn der Client den Echtzeitmodus auswählt.

Dieser Vorgang verwendet eine einzelne URL u und gibt SAFE, UNSAFE oder UNSURE zurück. Wenn SAFE zurückgegeben wird, gilt die URL von Google Safe Browsing als sicher. Wenn UNSAFE zurückgegeben wird, wird die URL von Google Safe Browsing als potenziell unsicher eingestuft und es müssen entsprechende Maßnahmen ergriffen: So wird dem Endnutzer beispielsweise eine Warnung angezeigt, eine empfangene Nachricht in den Spamordner verschoben oder eine zusätzliche Bestätigung durch den Nutzer erforderlich, bevor der Vorgang fortgesetzt werden kann. Wenn UNSURE zurückgegeben wird, sollte im Anschluss die lokale Prüfung wie folgt durchgeführt werden.

Lass expressions eine Liste von Suffix-/Präfixausdrücken sein, die von der URL u generiert wurden.
Lass expressionHashes eine Liste sein, wobei die Elemente SHA256-Hashes der einzelnen Ausdrücke in expressions sind.
Führen Sie für jeden hash von expressionHashes folgende Schritte aus:
1. Wenn hash im globalen Cache gefunden wird, geben Sie UNSURE zurück.
Lass expressionHashPrefixes eine Liste sein, wobei die Elemente die ersten 4 Byte jedes Hashs in expressionHashes sind.
Führen Sie für jeden expressionHashPrefix von expressionHashPrefixes folgende Schritte aus:
1. Suchen Sie im lokalen Cache nach expressionHashPrefix.
2. Wenn der im Cache gespeicherte Eintrag gefunden wird:
  1. Ermittle, ob die aktuelle Zeit größer als die Ablaufzeit ist.
  2. Ist der Wert größer:
    1. Entfernen Sie den gefundenen im Cache gespeicherten Eintrag aus dem lokalen Cache.
    2. Fahre mit der Schleife fort.
  3. Ist der Wert nicht größer:
    1. Entferne diesen expressionHashPrefix aus expressionHashPrefixes.
    2. Prüfen Sie, ob der entsprechende vollständige Hash innerhalb von expressionHashes im im Cache gespeicherten Eintrag enthalten ist.
    3. Wenn gefunden, wird UNSAFE zurückgegeben.
    4. Wenn sie nicht gefunden wird, fahre mit der Schleife fort.
3. Wenn der im Cache gespeicherte Eintrag nicht gefunden wird, fahren Sie mit der Schleife fort.
Senden Sie expressionHashPrefixes mit RPC-SearchHashes oder der REST-Methode hashes.search an den Google Safe Browsing-Server von Version 5. Wenn ein Fehler aufgetreten ist (einschließlich Netzwerkfehlern, HTTP-Fehlern usw.), wird UNSURE zurückgegeben. Andernfalls lassen Sie die Antwort die vom SB-Server empfangene response enthalten. Sie enthält eine Liste der vollständigen Hashes mit einigen Zusatzinformationen, die die Art der Bedrohung (Social Engineering, Malware usw.) identifizieren, sowie die Ablaufzeit des Cache (expiration).
Führen Sie für jeden fullHash von response folgende Schritte aus:
1. Fügen Sie fullHash zusammen mit expiration in den lokalen Cache ein.
Führen Sie für jeden fullHash von response folgende Schritte aus:
1. Lass isFound das Ergebnis der Suche nach fullHash in expressionHashes sein.
2. Wenn isFound „False“ ist, fahre mit der Schleife fort.
3. Wenn isFound „True“ ist, wird UNSAFE zurückgegeben.
Rückflug SAFE.

Während dieses Protokoll angibt, wann der Client expressionHashPrefixes an den Server sendet, gibt dieses Protokoll absichtlich nicht genau an, wie sie gesendet werden. Beispielsweise ist es für den Client akzeptabel, alle expressionHashPrefixes in einer einzigen Anfrage zu senden, und es ist auch akzeptabel, wenn der Client jedes einzelne Präfix in expressionHashPrefixes in separaten Anfragen an den Server sendet. Dies kann beispielsweise parallel erfolgen. Es ist auch zulässig, dass der Client irrelevante oder zufällig generierte Hash-Präfixe zusammen mit den Hash-Präfixen in expressionHashPrefixes sendet, solange die Anzahl der Hash-Präfixe, die in einer einzelnen Anfrage gesendet werden, 30 nicht überschreitet.

URL-Überprüfungsverfahren für die LocalThreat-Liste

Dieses Verfahren wird verwendet, wenn der Client den Betriebsmodus „Lokaler Listen“ verwenden möchte. Sie wird auch verwendet, wenn der Client mit der obigen RealTimeCheck-Prozedur den Wert UNSURE zurückgibt.

Bei diesem Vorgang wird für eine einzelne URL u der Wert SAFE oder UNSAFE zurückgegeben.

Lass expressions eine Liste von Suffix-/Präfixausdrücken sein, die von der URL u generiert wurden.
Lass expressionHashes eine Liste sein, wobei die Elemente SHA256-Hashes der einzelnen Ausdrücke in expressions sind.
Lass expressionHashPrefixes eine Liste sein, wobei die Elemente die ersten 4 Byte jedes Hashs in expressionHashes sind.
Führen Sie für jeden expressionHashPrefix von expressionHashPrefixes folgende Schritte aus:
1. Suchen Sie im lokalen Cache nach expressionHashPrefix.
2. Wenn der im Cache gespeicherte Eintrag gefunden wird:
  1. Ermittle, ob die aktuelle Zeit größer als die Ablaufzeit ist.
  2. Ist der Wert größer:
    1. Entfernen Sie den gefundenen im Cache gespeicherten Eintrag aus dem lokalen Cache.
    2. Fahre mit der Schleife fort.
  3. Ist der Wert nicht größer:
    1. Entferne diesen expressionHashPrefix aus expressionHashPrefixes.
    2. Prüfen Sie, ob der entsprechende vollständige Hash innerhalb von expressionHashes im im Cache gespeicherten Eintrag enthalten ist.
    3. Wenn gefunden, wird UNSAFE zurückgegeben.
    4. Wenn sie nicht gefunden wird, fahre mit der Schleife fort.
3. Wenn der im Cache gespeicherte Eintrag nicht gefunden wird, fahren Sie mit der Schleife fort.
Führen Sie für jeden expressionHashPrefix von expressionHashPrefixes folgende Schritte aus:
1. Suchen Sie expressionHashPrefix in der lokalen Bedrohungslisten-Datenbank.
2. Wenn die expressionHashPrefix nicht in der lokalen Bedrohungslisten-Datenbank gefunden werden kann, entfernen Sie sie aus expressionHashPrefixes.
Senden Sie expressionHashPrefixes mit RPC-SearchHashes oder der REST-Methode hashes.search an den Google Safe Browsing-Server von Version 5. Wenn ein Fehler aufgetreten ist (einschließlich Netzwerkfehlern, HTTP-Fehlern usw.), wird SAFE zurückgegeben. Andernfalls lassen Sie die Antwort die vom SB-Server empfangene response enthalten. Sie enthält eine Liste der vollständigen Hashes mit einigen Zusatzinformationen, die die Art der Bedrohung (Social Engineering, Malware usw.) identifizieren, sowie die Ablaufzeit des Cache (expiration).
Führen Sie für jeden fullHash von response folgende Schritte aus:
1. Fügen Sie fullHash zusammen mit expiration in den lokalen Cache ein.
Führen Sie für jeden fullHash von response folgende Schritte aus:
1. Lass isFound das Ergebnis der Suche nach fullHash in expressionHashes sein.
2. Wenn isFound „False“ ist, fahre mit der Schleife fort.
3. Wenn isFound „True“ ist, wird UNSAFE zurückgegeben.
Rückflug SAFE.

URL-Prüfung in Echtzeit ohne lokale Datenbank

Dieses Verfahren wird verwendet, wenn der Client den Echtzeitmodus ohne Speicher auswählt.

Bei diesem Vorgang wird für eine einzelne URL u der Wert SAFE oder UNSAFE zurückgegeben.

Lass expressions eine Liste von Suffix-/Präfixausdrücken sein, die von der URL u generiert wurden.
Lass expressionHashes eine Liste sein, wobei die Elemente SHA256-Hashes der einzelnen Ausdrücke in expressions sind.
Lass expressionHashPrefixes eine Liste sein, wobei die Elemente die ersten 4 Byte jedes Hashs in expressionHashes sind.
Führen Sie für jeden expressionHashPrefix von expressionHashPrefixes folgende Schritte aus:
1. Suchen Sie im lokalen Cache nach expressionHashPrefix.
2. Wenn der im Cache gespeicherte Eintrag gefunden wird:
  1. Ermittle, ob die aktuelle Zeit größer als die Ablaufzeit ist.
  2. Ist der Wert größer:
    1. Entfernen Sie den gefundenen im Cache gespeicherten Eintrag aus dem lokalen Cache.
    2. Fahre mit der Schleife fort.
  3. Ist der Wert nicht größer:
    1. Entferne diesen expressionHashPrefix aus expressionHashPrefixes.
    2. Prüfen Sie, ob der entsprechende vollständige Hash innerhalb von expressionHashes im im Cache gespeicherten Eintrag enthalten ist.
    3. Wenn gefunden, wird UNSAFE zurückgegeben.
    4. Wenn sie nicht gefunden wird, fahre mit der Schleife fort.
3. Wenn der im Cache gespeicherte Eintrag nicht gefunden wird, fahren Sie mit der Schleife fort.
Senden Sie expressionHashPrefixes mit RPC-SearchHashes oder der REST-Methode hashes.search an den Google Safe Browsing-Server von Version 5. Wenn ein Fehler aufgetreten ist (einschließlich Netzwerkfehlern, HTTP-Fehlern usw.), wird SAFE zurückgegeben. Andernfalls lassen Sie die Antwort die vom SB-Server empfangene response enthalten. Sie enthält eine Liste der vollständigen Hashes mit einigen Zusatzinformationen, die die Art der Bedrohung (Social Engineering, Malware usw.) identifizieren, sowie die Ablaufzeit des Cache (expiration).
Führen Sie für jeden fullHash von response folgende Schritte aus:
1. Fügen Sie fullHash zusammen mit expiration in den lokalen Cache ein.
Führen Sie für jeden fullHash von response folgende Schritte aus:
1. Lass isFound das Ergebnis der Suche nach fullHash in expressionHashes sein.
2. Wenn isFound „False“ ist, fahre mit der Schleife fort.
3. Wenn isFound „True“ ist, wird UNSAFE zurückgegeben.
Rückflug SAFE.

Genau wie bei der URL-Prüfung in Echtzeit gibt dieses Verfahren nicht genau an, wie die Hash-Präfixe an den Server gesendet werden. Beispielsweise ist es für den Client akzeptabel, alle expressionHashPrefixes in einer einzigen Anfrage zu senden, und es ist auch akzeptabel, wenn der Client jedes einzelne Präfix in expressionHashPrefixes in separaten Anfragen an den Server sendet. Dies kann beispielsweise parallel erfolgen. Es ist auch zulässig, dass der Client irrelevante oder zufällig generierte Hash-Präfixe zusammen mit den Hash-Präfixen in expressionHashPrefixes sendet, solange die Anzahl der Hash-Präfixe, die in einer einzelnen Anfrage gesendet werden, 30 nicht überschreitet.

Wartung lokaler Datenbanken

Google Safe Browsing v5 erwartet, dass der Client eine lokale Datenbank verwaltet, es sei denn, der Client wählt den Echtzeitmodus „Kein Speicher“ aus. Der Client richtet sich nach dem Format und der Speicherung dieser lokalen Datenbank. Der Inhalt dieser lokalen Datenbank kann man sich als einen Ordner vorstellen, der verschiedene Listen als Dateien enthält. Der Inhalt dieser Dateien ist SHA256-Hashes oder Hash-Präfixe.

Datenbankaktualisierungen

Der Client ruft regelmäßig die Methode hashList.get oder hashLists.batchGet auf, um die Datenbank zu aktualisieren. Da ein typischer Client mehrere Listen gleichzeitig aktualisieren möchte, empfiehlt sich die Verwendung der hashLists.batchGet-Methode.

Listen werden durch ihre eindeutigen Namen identifiziert. Die Namen sind kurze, einige Zeichen lange ASCII-Strings.

Im Gegensatz zu V4, wo Listen durch das Tupel des Bedrohungstyps, Plattformtyps und Bedrohungseintragstyps identifiziert werden, werden in v5 Listen einfach durch den Namen identifiziert. Das bietet Flexibilität, wenn mehrere V5-Listen denselben Bedrohungstyp verwenden können. Plattform- und Bedrohungseintragstypen wurden in Version 5 entfernt.

Sobald ein Name für eine Liste ausgewählt wurde, wird dieser nicht mehr umbenannt. Sobald eine Liste angezeigt wird, wird sie nie entfernt. Ist die Liste nicht mehr nützlich, wird sie leer bleiben, bleibt aber bestehen. Daher ist es sinnvoll, diese Namen hart im Code des Google Safe Browsing-Clients zu codieren.

Sowohl die Methode hashList.get als auch die Methode hashLists.batchGet unterstützen inkrementelle Aktualisierungen. Mit inkrementellen Updates können Sie Bandbreite sparen und die Leistung verbessern. Bei inkrementellen Updates wird eine Abweichung zwischen der Version der Liste für den Kunden und der neuesten Version der Liste erzeugt. Wenn ein Client neu bereitgestellt wird und keine Versionen verfügbar sind, ist ein vollständiges Update verfügbar. Das inkrementelle Update enthält Entfernungsindexe und Ergänzungen. Es wird zuerst erwartet, dass der Client die Einträge an den angegebenen Indexen aus seiner lokalen Datenbank entfernt und dann die Ergänzungen anwendet.

Um Beschädigungen zu vermeiden, sollte der Client schließlich die gespeicherten Daten mit der vom Server bereitgestellten Prüfsumme vergleichen. Wenn die Prüfsumme nicht übereinstimmt, sollte der Client eine vollständige Aktualisierung durchführen.

Listeninhalte entschlüsseln

Hashes und Hashpräfixe decodieren

Alle Listen werden mit einer speziellen Codierung bereitgestellt, um die Größe zu reduzieren. Bei dieser Codierung wird erkannt, dass Google Safe Browsing-Listen konzeptionell eine Reihe von Hashes oder Hash-Präfixen enthalten, die statistisch nicht von zufälligen Ganzzahlen unterschieden werden können. Wenn wir diese Ganzzahlen sortieren und ihre benachbarte Differenz nehmen, ist diese benachbarte Differenz in gewisser Weise „klein“. Die Golomb-Rice-Codierung nutzt diese Kleinigkeit dann aus.

Angenommen, drei Hostsuffix-Pfadpräfixausdrücke, nämlich a.example.com/, b.example.com/ und y.example.com/, werden mit 4-Byte-Hash-Präfixen übertragen. Nehmen wir weiter an, dass der mit k bezeichnete Rice-Parameter 30 ausgewählt wird. Der Server würde zunächst den vollständigen Hash für diese Strings berechnen. Diese sind:

291bc5421f1cd54d99afcc55d166e2b9fe42447025895bf09dd41b2110a687dc  a.example.com/
1d32c5084a360e58f1b87109637a6810acad97a861a7769e8f1841410d2a960c  b.example.com/
f7a502e56e8b01c6dc242b35122683c9d25d07fb1f532d9853eb0ef3ff334f03  y.example.com/

Der Server bildet dann 4-Byte-Hash-Präfixe für jedes der oben genannten Punkte, wobei es sich um die ersten 4 Bytes des vollständigen 32-Byte-Hash-Werts handelt, die als Big-Endian-32-Bit-Ganzzahlen interpretiert werden. Der große Endianness bedeutet, dass das erste Byte des vollständigen Hash-Werts das höchstwertige Byte der 32-Bit-Ganzzahl wird. Dieser Schritt führt zu den Ganzzahlen 0x291bc542, 0x1d32c508 und 0xf7a502e5.

Der Server muss diese drei Hash-Präfixe lexikografisch sortieren (entspricht der numerischen Sortierung in Big Endian). Das Ergebnis der Sortierung ist 0x1d32c508, 0x291bc542, 0xf7a502e5. Das erste Hash-Präfix wird unverändert im Feld first_value gespeichert.

Der Server berechnet dann die beiden benachbarten Unterschiede, die jeweils 0xbe9003a und 0xce893da3 sind. Da k als 30 ausgewählt wird, teilt der Server diese beiden Zahlen in die Quotiententeile und Restteile mit einer Länge von 2 bzw. 30 Bit auf. Bei der ersten Zahl ist der Quotiententeil null und der Rest 0xbe9003a; für die zweite Zahl ist der Quotiententeil 3, da die höchstwertigen zwei Bits 11 im Binärsystem und der Rest 0xe893da3 sind. Für einen bestimmten Quotienten q wird er mit genau 1 + q Bit in (1 << q) - 1 codiert. Der Rest wird direkt mit k Bit codiert. Der Quotiententeil der ersten Zahl ist als 0 codiert, der Rest ist im Binärformat 001011111010010000000000111010 codiert; der Quotiententeil der zweiten Zahl ist als 0111 codiert, der Rest ist 0011101000101010101010101010101010101010

Werden diese Zahlen in einen Bytestring umgewandelt, wird Little-Endian verwendet. Konzeptionell ist es einfacher, sich eine lange Bitfolge aus den niedrigstwertigen Bits vorzustellen: Wir nehmen den Quotienten der ersten Zahl und stellen den Rest der ersten Zahl voran. Dann stellen wir der zweiten Zahl den Quotienten und dem Restteil voran. Daraus ergibt sich die folgende große Anzahl (Zeilenumbrüche und Kommentare zur Verdeutlichung hinzugefügt):

001110100010010011110110100011 # Second number, remainder part
0111 # Second number, quotient part
001011111010010000000000111010 # First number, remainder part
0 # First number, quotient part

In einer einzigen Zeile lautet:

00111010001001001111011010001101110010111110100100000000001110100

Offensichtlich übersteigt diese Zahl bei Weitem die in einem einzelnen Byte verfügbaren 8 Bit. Die Little-Endian-Codierung nimmt dann die niedrigstwertigen 8 Bits in dieser Zahl und gibt sie als erstes Byte aus, nämlich 01110100. Zur Verdeutlichung können wir die obige Bitstrings in Gruppen von acht Gruppen zusammenfassen, beginnend mit den niedrigstwertigen Bits:

0 01110100 01001001 11101101 00011011 10010111 11010010 00000000 01110100

Die Little-Endian-Codierung nimmt dann jedes Byte von rechts in einen Bytestring:

Da wir der großen Zahl auf der linken Seite konzeptionell neue Teile prepend (also mehr signifikante Bits hinzufügen), aber wir von rechts codieren (d. h. die niedrigstwertigen Bits), kann die Codierung und Decodierung inkrementell durchgeführt werden.

Dies führt schließlich zu

additions_four_bytes {
  first_value: 489866504
  rice_parameter: 30
  entries_count: 2
  encoded_data: "t\000\322\227\033\355It\000"
}

Der Client decodiert die Hash-Präfixe einfach in umgekehrter Reihenfolge. Im Gegensatz zu Version 4 ist es nicht erforderlich, am Ende einen Byte-Austausch durchzuführen, da die Hash-Präfix-Ganzzahlen als Big-Endian interpretiert werden.

Entfernungsindexe decodieren

Die Indexe für die Entfernung werden genau nach der gleichen Technik wie oben unter Verwendung von 32-Bit-Ganzzahlen codiert. Die Codierung und Decodierung der Entfernungsindexe hat sich zwischen v4 und v5 nicht geändert.

Verfügbare Listen

Die folgenden Listen werden für die Verwendung in v5alpha1 empfohlen:

Name der Liste	Entsprechende Aufzählung für Version 4 (`ThreatType`)	Beschreibung
`gc`	Ohne	Dies ist eine Liste des globalen Cache. Es handelt sich um eine spezielle Liste, die nur im Echtzeitmodus verwendet wird.
`se`	`SOCIAL_ENGINEERING`	Diese Liste enthält Bedrohungen des Bedrohungstyps SOCIAL_ENGINEERING.
`mw`	`MALWARE`	Diese Liste enthält Bedrohungen des Bedrohungstyps MALWARE für Desktop-Plattformen.
`uws`	`UNWANTED_SOFTWARE`	Diese Liste enthält Bedrohungen des Bedrohungstyps UNWANTED_SOFTWARE für Desktop-Plattformen.
`uwsa`	`UNWANTED_SOFTWARE`	Diese Liste enthält Bedrohungen des Bedrohungstyps UNWANTED_SOFTWARE für Android-Plattformen.
`pha`	`POTENTIALLY_HARMFUL_APPLICATION`	Diese Liste enthält Bedrohungen des Bedrohungstyps POTENTIALLY_HARMFUL_APPLICATION für Android-Plattformen.

Weitere Listen werden zu einem späteren Zeitpunkt verfügbar sein. Dann wird auch die obige Tabelle erweitert.

Es ist dem Client gestattet, einen Caching-Proxy-Server zu betreiben, um einige oder alle der obigen Listen abzurufen, und den Client dann zu bitten, den Proxy-Server zu kontaktieren. Wenn dies implementiert ist, empfehlen wir eine kurze Cache-Dauer wie fünf Minuten. Zukünftig kann diese Cache-Dauer über den standardmäßigen Cache-Control-HTTP-Header übermittelt werden.

Updatehäufigkeit

Der Client sollte den vom Server zurückgegebenen Wert im Feld minimum_wait_duration prüfen und damit die nächste Aktualisierung der Datenbank planen. Dieser Wert ist möglicherweise null (das Feld minimum_wait_duration fehlt). In diesem Fall SOLLTE der Client sofort eine weitere Aktualisierung vornehmen.

Beispiele für Anforderungen

In diesem Abschnitt werden einige Beispiele für den direkten Zugriff auf Google Safe Browsing über die HTTP API dokumentiert. Es wird im Allgemeinen empfohlen, eine generierte Sprachbindung zu verwenden, da diese die Codierung und Decodierung automatisch auf bequeme Weise handhabt. Weitere Informationen finden Sie in der Dokumentation zu dieser Bindung.

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

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

Der Antworttext ist eine als Protokollpuffer formatierte Nutzlast, die Sie dann decodieren können.

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

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

Der Antworttext ist wieder eine Protokollpuffer-formatierte Nutzlast, die Sie dann decodieren können.

Migrationsanleitung

Wenn Sie derzeit die Update API v4 verwenden, können Sie nahtlos von v4 zu v5 migrieren, ohne die lokale Datenbank zurücksetzen oder löschen zu müssen. In diesem Abschnitt wird die Vorgehensweise beschrieben.

Listenaktualisierungen konvertieren

In Version 4 wird die Methode threatListUpdates.fetch zum Herunterladen von Listen verwendet. In Version 5 ist eine Umstellung auf die Methode hashLists.batchGet erforderlich.

Folgende Änderungen sollten an der Anfrage vorgenommen werden:

Entfernen Sie das ClientInfo-Objekt aus Version 4 vollständig. Anstatt die Client-ID über ein eigenes Feld bereitzustellen, können Sie einfach den bekannten User-Agent-Header verwenden. Obwohl es kein vorgeschriebenes Format für die Bereitstellung der Client-ID in diesem Header gibt, empfehlen wir, einfach die ursprüngliche Client-ID und Client-Version anzugeben, getrennt durch ein Leerzeichen oder einen Schrägstrich.
Führen Sie für jedes ListUpdateRequest-Objekt der Version 4 folgende Schritte aus:
- Suchen Sie in der Tabelle oben den entsprechenden Namen der v5-Liste und geben Sie diesen Namen in der v5-Anfrage an.
- Entfernen Sie nicht benötigte Felder wie threat_entry_type oder platform_type.
- Das Feld „state“ in Version 4 ist direkt mit dem Feld „versions“ in Version 5 kompatibel. Derselbe Bytestring, der in Version 4 über das Feld state an den Server gesendet wird, kann in Version 5 einfach mit dem Feld versions gesendet werden.
- Für die Einschränkungen von Version 4 wird die vereinfachte Version SizeConstraints verwendet. Zusätzliche Felder wie region sollten entfernt werden.

Nehmen Sie die folgenden Änderungen an der Antwort vor:

Das enum ResponseType von Version 4 wird einfach durch ein boolesches Feld mit dem Namen partial_update ersetzt.
Das Feld minimum_wait_duration kann jetzt null sein oder weggelassen werden. Ist dies der Fall, wird der Client aufgefordert, sofort eine weitere Anfrage zu stellen. Dies geschieht nur, wenn der Client in SizeConstraints eine kleinere Einschränkung für die maximale Updategröße als die maximale Datenbankgröße angibt.
Der Rice-Decodierungsalgorithmus für 32-Bit-Ganzzahlen muss angepasst werden. Der Unterschied besteht darin, dass die codierten Daten mit einer anderen Endianness codiert sind. Sowohl in v4 als auch in v5 werden 32-Bit-Hash-Präfixe lexikografisch sortiert. In v4 werden diese Präfixe beim Sortieren als Little-Endian behandelt, in v5 dagegen als Big-Endian. Das bedeutet, dass der Client keine Sortierung vornehmen muss, da die lexikografische Sortierung mit der numerischen Sortierung mit Big Endian identisch ist. Ein Beispiel dieser Art in der Chromium-Implementierung von Version 4 findest du hier. Eine solche Sortierung kann entfernt werden.
Für andere Hash-Längen muss der Rice-Decodierungsalgorithmus implementiert werden.

Hash-Suchanfragen konvertieren

In Version 4 wird die fullHashes.find-Methode verwendet, um vollständige Hashes abzurufen. Die entsprechende Methode in Version 5 ist die Methode hashes.search.

Folgende Änderungen sollten an der Anfrage vorgenommen werden:

Strukturieren Sie den Code so, dass nur Hash-Präfixe gesendet werden, die genau vier Byte lang sind.
Entfernen Sie die ClientInfo-Objekte von v4 vollständig. Anstatt die Client-ID über ein eigenes Feld bereitzustellen, können Sie einfach den bekannten User-Agent-Header verwenden. Obwohl es kein vorgeschriebenes Format für die Bereitstellung der Client-ID in diesem Header gibt, empfehlen wir, einfach die ursprüngliche Client-ID und Client-Version anzugeben, getrennt durch ein Leerzeichen oder einen Schrägstrich.
Entfernen Sie das Feld client_states. Es ist nicht mehr notwendig.
threat_types und ähnliche Felder sind nicht mehr erforderlich.

Nehmen Sie die folgenden Änderungen an der Antwort vor:

Das Feld „minimum_wait_duration“ wurde entfernt. Der Kunde kann bei Bedarf jederzeit eine neue Anfrage stellen.
Das ThreatMatch-Objekt der Version 4 wurde zum Objekt FullHash vereinfacht.
Das Caching wurde zu einer einzigen Cache-Dauer vereinfacht. Gehen Sie wie oben beschrieben vor, um mit dem Cache zu interagieren.