Einführung
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. Falls wir das tun, werden wir Sie mit einer Frist von mindestens einem Jahr ankündigen. Auf dieser Seite werden v5 beschrieben sowie eine Migrationsanleitung von v4 zu v5. Die vollständige Dokumentation für Version 4 bleibt 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 verbreiteten sich Phishing-Angriffe schnell: Bis 2021 waren es 60% der Angriffe auf 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 IP-Adressen von Google. 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 können die IP-Adressen werden 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. Sollten Sie damit rechnen, mehr als Ihr derzeit zugeteiltes Kontingent zu nutzen, 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 die Prüfung auf untergeordnete Ressourcen (wie JavaScript oder Bild, auf das eine HTML-Datei verweist, oder eine von JavaScript initiierte WebSocket-URL) gedacht. 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 klargestellt 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. Die folgenden Links werden vorgeschlagen:
<ph type="x-smartling-placeholder">
- </ph>
- 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 durch Einfügen der Zeile „Advisory provided by Google“ benennen. mit einem Link zu den Safe Browsing-Hinweisen. 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 informiert werden, dass die Möglichkeit sowohl falsch positiver Websites (sichere Websites, die als riskant markiert) als auch falsch negativer Ergebnisse (nicht als riskant gekennzeichnete Websites) gemeldet werden kann. 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: Immer wenn der Client eine bestimmte URL überprüfen möchte, wird mithilfe des globalen Caches eine lokale Prüfung durchgeführt. Wenn diese Prüfung bestanden wird, wird eine lokale Prüfung auf 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 zurück, 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 für 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: <ph type="x-smartling-placeholder">- </ph>
- Eine IPv4-zugeordnete IPv6-Adresse wie
[::ffff:1.2.3.4]
, die in1.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 in1.2.3.4
umgewandelt werden sollte.
- Eine IPv4-zugeordnete IPv6-Adresse wie
- 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 vonexample.com
sowie zum Host mit einer zusätzlichen Hostkomponenteb.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 sollten 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 URLu
generiert wurden. - Lass
expressionHashes
eine Liste sein, wobei die Elemente SHA256-Hashes der einzelnen Ausdrücke inexpressions
sind. - Für jeden
hash
vonexpressionHashes
: <ph type="x-smartling-placeholder">- </ph>
- Wenn
hash
im globalen Cache gefunden wird, geben SieUNSURE
zurück.
- Wenn
- Lass
expressionHashPrefixes
eine Liste sein, wobei die Elemente die ersten 4 Byte jedes Hashs inexpressionHashes
sind. - Für jeden
expressionHashPrefix
vonexpressionHashPrefixes
: <ph type="x-smartling-placeholder">- </ph>
- Suchen Sie im lokalen Cache nach
expressionHashPrefix
. - Wenn der im Cache gespeicherte Eintrag gefunden wird:
<ph type="x-smartling-placeholder">
- </ph>
- Ermittle, ob die aktuelle Zeit größer als die Ablaufzeit ist.
- Wenn der Wert größer ist:
<ph type="x-smartling-placeholder">
- </ph>
- Entfernen Sie den gefundenen im Cache gespeicherten Eintrag aus dem lokalen Cache.
- Fahre mit der Schleife fort.
- Ist der Wert nicht größer:
<ph type="x-smartling-placeholder">
- </ph>
- Entferne diesen
expressionHashPrefix
ausexpressionHashPrefixes
. - Prüfen Sie, ob der entsprechende vollständige Hash innerhalb von
expressionHashes
im im Cache gespeicherten Eintrag enthalten ist. - Wenn gefunden, wird
UNSAFE
zurückgegeben. - Wenn sie nicht gefunden wird, fahre mit der Schleife fort.
- Entferne diesen
- Wenn der im Cache gespeicherte Eintrag nicht gefunden wird, fahren Sie mit der Schleife fort.
- Suchen Sie im lokalen Cache nach
- 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.), wirdUNSURE
zurückgegeben. Andernfalls lassen Sie die Antwort die vom SB-Server empfangeneresponse
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ür jeden
fullHash
vonresponse
: <ph type="x-smartling-placeholder">- </ph>
- Fügen Sie
fullHash
zusammen mitexpiration
in den lokalen Cache ein.
- Fügen Sie
- Für jeden
fullHash
vonresponse
: <ph type="x-smartling-placeholder">- </ph>
- Lass
isFound
das Ergebnis der Suche nachfullHash
inexpressionHashes
sein. - Wenn
isFound
„False“ ist, fahre mit der Schleife fort. - Wenn
isFound
„True“ ist, wirdUNSAFE
zurückgegeben.
- Lass
- Rückflug
SAFE
.
Während dieses Protokoll angibt, wann der Client expressionHashPrefixes
an den Server sendet, gibt dieses Protokoll absichtlich nicht genau an, wie die Daten 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 geschehen. 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 „Lokale Listenliste“ auswählt. 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 URLu
generiert wurden. - Lass
expressionHashes
eine Liste sein, wobei die Elemente SHA256-Hashes der einzelnen Ausdrücke inexpressions
sind. - Lass
expressionHashPrefixes
eine Liste sein, wobei die Elemente die ersten 4 Byte jedes Hashs inexpressionHashes
sind. - Für jeden
expressionHashPrefix
vonexpressionHashPrefixes
: <ph type="x-smartling-placeholder">- </ph>
- Suchen Sie im lokalen Cache nach
expressionHashPrefix
. - Wenn der im Cache gespeicherte Eintrag gefunden wird:
<ph type="x-smartling-placeholder">
- </ph>
- Ermittle, ob die aktuelle Zeit größer als die Ablaufzeit ist.
- Wenn der Wert größer ist:
<ph type="x-smartling-placeholder">
- </ph>
- Entfernen Sie den gefundenen im Cache gespeicherten Eintrag aus dem lokalen Cache.
- Fahre mit der Schleife fort.
- Ist der Wert nicht größer:
<ph type="x-smartling-placeholder">
- </ph>
- Entferne diesen
expressionHashPrefix
ausexpressionHashPrefixes
. - Prüfen Sie, ob der entsprechende vollständige Hash innerhalb von
expressionHashes
im im Cache gespeicherten Eintrag enthalten ist. - Wenn gefunden, wird
UNSAFE
zurückgegeben. - Wenn sie nicht gefunden wird, fahre mit der Schleife fort.
- Entferne diesen
- Wenn der im Cache gespeicherte Eintrag nicht gefunden wird, fahren Sie mit der Schleife fort.
- Suchen Sie im lokalen Cache nach
- Für jeden
expressionHashPrefix
vonexpressionHashPrefixes
: <ph type="x-smartling-placeholder">- </ph>
- Suchen Sie
expressionHashPrefix
in der lokalen Bedrohungslisten-Datenbank. - Wenn die
expressionHashPrefix
nicht in der lokalen Bedrohungslisten-Datenbank gefunden werden kann, entfernen Sie sie ausexpressionHashPrefixes
.
- Suchen Sie
- 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.), wirdSAFE
zurückgegeben. Andernfalls lassen Sie die Antwort die vom SB-Server empfangeneresponse
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ür jeden
fullHash
vonresponse
: <ph type="x-smartling-placeholder">- </ph>
- Fügen Sie
fullHash
zusammen mitexpiration
in den lokalen Cache ein.
- Fügen Sie
- Für jeden
fullHash
vonresponse
: <ph type="x-smartling-placeholder">- </ph>
- Lass
isFound
das Ergebnis der Suche nachfullHash
inexpressionHashes
sein. - Wenn
isFound
„False“ ist, fahre mit der Schleife fort. - Wenn
isFound
„True“ ist, wirdUNSAFE
zurückgegeben.
- Lass
- 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 URLu
generiert wurden. - Lass
expressionHashes
eine Liste sein, wobei die Elemente SHA256-Hashes der einzelnen Ausdrücke inexpressions
sind. - Lass
expressionHashPrefixes
eine Liste sein, wobei die Elemente die ersten 4 Byte jedes Hashs inexpressionHashes
sind. - Für jeden
expressionHashPrefix
vonexpressionHashPrefixes
: <ph type="x-smartling-placeholder">- </ph>
- Suchen Sie im lokalen Cache nach
expressionHashPrefix
. - Wenn der im Cache gespeicherte Eintrag gefunden wird:
<ph type="x-smartling-placeholder">
- </ph>
- Ermittle, ob die aktuelle Zeit größer als die Ablaufzeit ist.
- Wenn der Wert größer ist:
<ph type="x-smartling-placeholder">
- </ph>
- Entfernen Sie den gefundenen im Cache gespeicherten Eintrag aus dem lokalen Cache.
- Fahre mit der Schleife fort.
- Ist der Wert nicht größer:
<ph type="x-smartling-placeholder">
- </ph>
- Entferne diesen
expressionHashPrefix
ausexpressionHashPrefixes
. - Prüfen Sie, ob der entsprechende vollständige Hash innerhalb von
expressionHashes
im im Cache gespeicherten Eintrag enthalten ist. - Wenn gefunden, wird
UNSAFE
zurückgegeben. - Wenn sie nicht gefunden wird, fahre mit der Schleife fort.
- Entferne diesen
- Wenn der im Cache gespeicherte Eintrag nicht gefunden wird, fahren Sie mit der Schleife fort.
- Suchen Sie im lokalen Cache nach
- 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.), wirdSAFE
zurückgegeben. Andernfalls lassen Sie die Antwort die vom SB-Server empfangeneresponse
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ür jeden
fullHash
vonresponse
: <ph type="x-smartling-placeholder">- </ph>
- Fügen Sie
fullHash
zusammen mitexpiration
in den lokalen Cache ein.
- Fügen Sie
- Für jeden
fullHash
vonresponse
: <ph type="x-smartling-placeholder">- </ph>
- Lass
isFound
das Ergebnis der Suche nachfullHash
inexpressionHashes
sein. - Wenn
isFound
„False“ ist, fahre mit der Schleife fort. - Wenn
isFound
„True“ ist, wirdUNSAFE
zurückgegeben.
- Lass
- 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 geschehen. 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 die Methode 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 ermitteln, wird erwartet, dass diese benachbarte Differenz „klein“ ist. in gewisser Weise. 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 ist 0xbe9003a. für die zweite Zahl ist der Quotiententeil 3, da die höchstwertigen zwei Bits im Binärformat 11 sind und der Rest 0xe893da3 ist. Ein gegebener Quotient q
wird mit genau 1 + q
Bit in (1 << q) - 1
codiert. der Rest wird direkt mit k Bits codiert. Der Quotiententeil der ersten Zahl ist als 0 codiert, der Rest ist als Binärcode 001011111010010000000000111010 codiert. Der Quotiententeil der zweiten Zahl ist als 0111 codiert und der Rest ist 001110100010010011110110100011.
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 dem Rest der ersten Zahl voran. stellen wir der zweiten Zahl den Quotienten voran und stellen den Rest voran. Daraus ergibt sich folgende hohe Anzahl (Zeilenumbrüche und Kommentare wurden 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:
01110100
00000000
11010010
10010111
00011011
11101101
01001001
01110100
00000000
Da wir der großen Zahl auf der linken Seite konzeptionell neue Teile voranstellen (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 Entfernungen werden genau nach derselben 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 |
Keine | 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. In Zukunft kann diese Cache-Dauer über den standardmäßigen Cache-Control
-HTTP-Header übermittelt werden.
Aktualisierungshä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. Im Allgemeinen wird 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: <ph type="x-smartling-placeholder">- </ph>
- 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
oderplatform_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 Feldstate
an den Server gesendet wird, kann in Version 5 einfach mit dem Feldversions
gesendet werden. - Für die Einschränkungen von Version 4 wird die vereinfachte Version
SizeConstraints
verwendet. Zusätzliche Felder wieregion
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 Namenpartial_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 inSizeConstraints
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 ObjektFullHash
vereinfacht. - Das Caching wurde zu einer einzigen Cache-Dauer vereinfacht. Gehen Sie wie oben beschrieben vor, um mit dem Cache zu interagieren.