Einleitung
Hinweis: Diese Dokumentation befindet sich noch in der Entwicklungsphase. Es sind Verbesserungen in naher Zukunft zu erwarten.
Version 5 von Google Safe Browsing ist eine Weiterentwicklung von Version 4 von Google Safe Browsing. Die beiden wichtigsten Änderungen in Version 5 sind die Datenaktualität und der IP-Datenschutz. Darüber hinaus wurde die API-Oberfläche verbessert, um Flexibilität und Effizienz zu erhöhen und Blähungen zu reduzieren. Darüber hinaus wurde Google Safe Browsing Version 5 so entwickelt, dass die Migration von Version 4 einfach ist.
Derzeit bietet Google sowohl Version 4 als auch Version 5 an und gelten beide als produktionsreif. Sie können entweder v4 oder v5 verwenden. Wir haben noch kein Datum für die Einstellung von Version 4 bekannt gegeben. Sollte dies der Fall sein, informieren wir Sie mindestens ein Jahr im Voraus. Auf dieser Seite werden Informationen zu Version 5 sowie eine Migrationsanleitung von Version 4 zu Version 5 beschrieben. 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 V4 (insbesondere der v4 Update API) ist die Datenaktualität und -abdeckung. Da der Schutz stark von der vom Client verwalteten lokalen Datenbank abhängt, tragen die Verzögerung und die Größe der Aktualisierung der lokalen Datenbank zu dem verpassten Schutz bei. In Version 4 benötigt ein Client normalerweise 20 bis 50 Minuten, um die aktuelle Version der Bedrohungslisten abzurufen. Leider verbreiten sich Phishing-Angriffe schnell: 2021 hatten 60% der Websites, die Angriffe ausstrahlen, weniger als 10 Minuten. Unsere Analysen zeigen, dass etwa 25 bis 30% des fehlenden Phishing-Schutzes auf veraltete Daten zurückzuführen sind. Außerdem sind einige Geräte nicht für die Verwaltung der gesamten Google Safe Browsing-Bedrohungslisten ausgelegt, die im Laufe der Zeit immer größer werden.
In v5 führen wir einen Betriebsmodus ein, der als Echtzeitschutz bezeichnet wird. Dadurch wird das obige Problem bezüglich der Datenveralterung umgangen. In Version 4 wird erwartet, dass Clients eine lokale Datenbank herunterladen und verwalten und die lokal heruntergeladenen Bedrohungslisten prüfen. Bei einer teilweisen Präfixübereinstimmung wird dann eine Anfrage zum Herunterladen des vollständigen Hash gestellt. In Version 5 sollten Clients weiterhin eine lokale Datenbank mit Bedrohungslisten herunterladen und verwalten. Es wird nun aber erwartet, dass sie eine Liste wahrscheinlich ungefährlicher Websites herunterladen (den sogenannten globalen Cache), eine lokale Prüfung des globalen Cache und eine Prüfung der lokalen Bedrohungsliste durchführen. Wenn schließlich entweder 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. Einzelheiten zur lokalen Verarbeitung, die der Kunde vornimmt, finden Sie unten. Dies stellt eine Verschiebung von „allow-by-default“ zu „check-by-default“ dar, durch die der Schutz angesichts der schnelleren Verbreitung von Bedrohungen im Web verbessert werden kann. Mit anderen Worten, das Protokoll ist so konzipiert, dass es nahezu in Echtzeit Schutz bietet: Unsere Kunden sollen von aktuelleren Google Safe Browsing-Daten profitieren können.
IP-Datenschutz
Google Safe Browsing (Version 4 oder 5) verarbeitet bei der Verarbeitung von Anfragen keine Daten, die mit der Identität eines Nutzers in Verbindung stehen. Wenn Cookies gesendet werden, werden sie ignoriert. Die Ursprungs-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 v5 führen wir eine Companion-API ein, die als Safe Browsing Oblivious HTTP Gateway API bezeichnet wird. Dabei wird Oblivious HTTP verwendet, um die IP-Adressen von Endnutzern vor Google zu verbergen. Dabei wird eine verschlüsselte Version der Nutzeranfrage von einem Drittanbieter verarbeitet, der keine Kollision erfordert und an Google weitergeleitet wird. Der Drittanbieter hat also nur Zugriff auf die IP-Adressen und Google hat nur Zugriff auf den Inhalt der Anfrage. Der Drittanbieter betreibt ein Oblivious HTTP Relay (wie diesen Dienst von Fastly) und Google betreibt das Oblivious HTTP Gateway. Dies ist eine optionale Companion-API. Wenn Sie es zusammen mit Google Safe Browsing verwenden, werden die IP-Adressen der Endnutzer nicht mehr an Google gesendet.
Angemessene Nutzung
Zulässige Nutzung
Die Safe Browsing API ist nur für die nicht kommerzielle Nutzung vorgesehen, d. h. nicht für den Verkauf oder die Umsatzgenerierung. Falls du eine Lösung für kommerzielle Zwecke benötigst, lies bitte 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 können in der Google Developer Console eingesehen werden. Wenn Sie voraussichtlich ein größeres als das aktuell zugewiesene Kontingent nutzen werden, können Sie über die Kontingentoberfläche der Developer Console ein zusätzliches Kontingent anfordern. Wir prüfen diese Anfragen und benötigen bei der Beantragung eines höheren Kontingents einen Kontakt, damit wir sicherstellen können, dass unsere Dienste den Anforderungen aller Nutzer entsprechen.
Geeignete URLs
Google Safe Browsing ist auf URLs ausgelegt, die in der Adressleiste eines Browsers angezeigt werden. Es ist nicht für die Prüfung auf Unterressourcen vorgesehen, z. B. ein JavaScript oder ein Bild, auf das in einer HTML-Datei verwiesen wird, 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), kann die weitergeleitete URL mit Google Safe Browsing abgeglichen werden. Clientseitige URL-Manipulationen wie History.pushState
führen nicht dazu, dass neue URLs mit Google Safe Browsing abgeglichen werden.
Nutzerwarnungen
Wenn Sie Nutzer mithilfe von Google Safe Browsing vor Risiken für bestimmte Webseiten warnen, gelten die folgenden Richtlinien.
Diese Richtlinien tragen dazu bei, Sie und Google vor Missverständnissen zu schützen, indem deutlich gemacht wird, dass die Seite nicht mit 100-prozentiger Sicherheit als unsichere Webressource bekannt ist und dass die Warnungen lediglich das potenzielle Risiko aufdecken.
- Die für Nutzer sichtbare Warnung darf den Nutzern nicht den Eindruck vermitteln, dass die betreffende Seite zweifellos eine unsichere Webressource ist. Wenn Sie sich auf die identifizierte Seite oder die potenziellen Risiken beziehen, die sie für Nutzer darstellen könnte, müssen Sie die Warnung mit Begriffen wie vermutet, potenziell, möglich, wahrscheinlich, kennzeichnen.
- Ihre Warnung muss es dem Nutzer ermöglichen, mehr darüber zu erfahren. Lesen Sie dazu die Definition verschiedener Bedrohungen von Google. Folgende Links werden empfohlen:
- 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 namentlich erwähnen. Fügen Sie dazu die Zeile „Hinweis von Google“ mit einem Link zum Safe Browsing-Hinweis ein. Wenn für Ihr Produkt Warnungen aus anderen Quellen angezeigt werden, dürfen Sie die Google-Attribution nicht in Warnungen angeben, die aus Daten stammen, die nicht von Google stammen.
In Ihrer Produktdokumentation müssen Sie einen Hinweis hinzufügen, um Nutzer darüber zu informieren, dass der von Google Safe Browsing angebotene Schutz nicht perfekt ist. Es muss darüber informiert werden, dass die Wahrscheinlichkeit sowohl falsch positive (sichere Websites, die als risikobehaftet gekennzeichnet sind) als auch falsch negative (risikobehaftete Websites, nicht gekennzeichnet) auftreten können. Wir empfehlen die Verwendung der folgenden Sprache:
Google arbeitet daran, möglichst genaue und aktuelle Informationen zu unsicheren Webressourcen bereitzustellen. Google kann jedoch nicht dafür garantieren, dass die Informationen umfassend und fehlerfrei sind: Einige risikobehaftete Websites werden möglicherweise nicht identifiziert, während einige sichere Websites möglicherweise fälschlicherweise identifiziert werden.
Die Betriebsarten
Mit Google Safe Browsing Version 5 können Clients aus drei Betriebsmodi wählen.
Echtzeitmodus
Wenn Clients Google Safe Browsing v5 im Echtzeitmodus verwenden, verwalten die Clients in ihrer lokalen Datenbank Folgendes: (i) einen globalen Cache mit wahrscheinlich harmlosen Websites, der als SHA256-Hashes von Host-Suffix-/Pfad-Präfix-URL-Ausdrücken formatiert ist, (ii) eine Reihe von Bedrohungslisten, die als SHA256-Hash-Präfixe von Host-Suffix-/Pfadpräfix-URL-Ausdrücken formatiert sind. Das übergeordnete Konzept besteht darin, dass immer dann, wenn der Client eine bestimmte URL überprüfen möchte, eine lokale Prüfung mit dem 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 mit der Echtzeit-Hash-Prüfung wie unten beschrieben fort.
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 Speicherauslastung geleert 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 Verhalten der v4 Update API nur, wenn die verbesserte API-Oberfläche von Version 5 verwendet wird. Clients verwalten in ihrer lokalen Datenbank eine Reihe von Bedrohungslisten, die als SHA256-Hash-Präfixe von URL-Ausdrücken mit Host-Suffix/Pfadpräfix formatiert sind. Immer wenn der Client eine bestimmte URL überprüfen möchte, wird mithilfe der lokalen Bedrohungsliste eine Prüfung durchgeführt. Nur wenn es eine Übereinstimmung gibt, stellt der Client eine Verbindung zum Server her, um die Prüfung fortzusetzen.
Wie oben erwähnt, unterhält der Client auch einen lokalen Cache, der sich nicht im dauerhaften Speicher befinden muss.
Echtzeitmodus ohne Speicherplatz
Wenn sich Clients für die Verwendung von Google Safe Browsing Version 5 im Echtzeitmodus ohne Speicherung entscheiden, muss der Client keine lokale Datenbank pflegen. 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, den Clients der v4 Lookup API implementieren können.
URLs prüfen
Dieser Abschnitt enthält detaillierte Spezifikationen dazu, wie Clients URLs überprüfen.
Kanonisierung von URLs
Bevor URLs überprüft werden, wird erwartet, dass der Client eine Kanonisierung für diese URL durchführt.
Zunächst gehen wir davon aus, dass der Client die URL geparst und gemäß RFC 2396 gültig gemacht hat. Wird für die URL ein internationalisierter Domainname (IDN) verwendet, sollte der Client die URL in die ASCII-Punycode-Darstellung umwandeln. Die URL muss eine Pfadkomponente enthalten, also mindestens einen Schrägstrich nach der Domain (http://google.com/
statt http://google.com
).
Entfernen Sie zunächst die Tabulatorzeichen (0x09), die Antwortvorlage (0x0d) und die LF-Zeichen (0x0a) aus der URL. Entfernen Sie keine Escape-Sequenzen 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
zu http://google.com/
.
Drittens: Rufen Sie die URL so lange auf, dass sie keine Escape-Zeichen mehr hat. Dadurch wird die URL möglicherweise ungültig.
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 4 durch Punkte getrennte Dezimalwerte. Der Client sollte jede zulässige Codierung von IP-Adressen übernehmen, einschließlich Oktal-, Hex- und weniger als vier Komponenten.
- Wenn der Hostname als IPv6-Adresse in Klammern geparst werden kann, normalisieren Sie ihn, indem Sie unnötige führende Nullen in den Komponenten entfernen und Nullkomponenten mithilfe der doppelten Doppelpunkt-Syntax minimieren.
[2001:0db8:0000::1]
sollte beispielsweise in[2001:db8::1]
umgewandelt werden. Wenn der Hostname einer der beiden folgenden speziellen IPv6-Adresstypen ist, wandeln Sie sie in IPv4 um:- 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]
, die in1.2.3.4
umgewandelt werden sollte.
- Eine IPv4-zugeordnete IPv6-Adresse wie
- Verwenden Sie Kleinbuchstaben für den gesamten String.
So setzen Sie eine Kanonisierung des Pfades ein:
- 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.
Verwenden Sie in der URL alle Zeichen, die <= ASCII 32, >= 127, #
oder %
sind. Die Escape-Zeichen müssen aus Großbuchstaben bestehen.
Pfadpräfixausdrücke für Host-Suffix
Nach der Kanonisierung der URL besteht der nächste Schritt darin, die Suffix-/Präfix-Ausdrücke zu erstellen. Jeder Suffix-/Präfixausdruck besteht aus einem Hostsuffix (oder vollständigen Host) und einem Pfadpräfix (oder vollständigen Pfad).
Der Client bildet bis zu 30 verschiedene Kombinationen aus Hostsuffix und Pfadpräfixen. 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, können bis zu vier Hostnamen gebildet werden, indem mit der eTLD+1-Domain begonnen und aufeinanderfolgende führende Komponenten hinzugefügt werden. eTLD+1 sollte anhand der Liste der öffentlichen Suffixe 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. Gemäß dem vorherigen Beispiel wird
a.b.example.com
geprüft.
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 angefügt 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 nur die letzten fünf Komponenten des Hostnamens und der vollständige Hostname verwendet werden.
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 Fall auf 4 Byte, 8 Byte oder 16 Byte gekürzt:
Bei Verwendung der Methode hashes.search müssen die Hashes in der Anfrage derzeit auf genau 4 Byte gekürzt werden. Das Senden zusätzlicher Bytes in dieser Anfrage gefährdet den Datenschutz für Nutzer.
Beim Herunterladen der Listen für die lokale Datenbank mit der Methode hashList.get oder hashLists.batchGet wird die Länge der vom Server gesendeten Hashes sowohl von der Art der Liste als auch von der Einstellung der Hashlänge durch den Client beeinflusst, die durch den Parameter
desired_hash_length
übermittelt wird.
URL-Prüfung in Echtzeit
Dieses Verfahren wird verwendet, wenn der Client den Echtzeitmodus wählt.
Bei diesem Vorgang wird für eine einzelne URL u
verwendet und SAFE
, UNSAFE
oder UNSURE
zurückgegeben. Wenn SAFE
zurückgegeben wird, wird die URL von Google Safe Browsing als sicher eingestuft. Wird UNSAFE
zurückgegeben, wurde die URL von Google Safe Browsing als potenziell unsicher eingestuft. In diesem Fall müssen Sie entsprechende Maßnahmen ergreifen. Beispielsweise muss dem Endnutzer eine Warnung angezeigt werden, eine empfangene Nachricht wird in den Spamordner verschoben oder der Nutzer muss vor dem Fortfahren eine zusätzliche Bestätigung erhalten. Wenn UNSURE
zurückgegeben wird, sollte anschließend das folgende lokale Prüfverfahren verwendet werden.
- Lass
expressions
eine Liste von Suffix-/Präfix-Ausdrü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
:- Wenn
hash
im globalen Cache gefunden werden kann, wirdUNSURE
zurückgegeben.
- Wenn
- Lass
expressionHashPrefixes
eine Liste sein, bei der die Elemente die ersten 4 Byte jedes Hashwerts inexpressionHashes
sind. - Für jeden
expressionHashPrefix
vonexpressionHashPrefixes
:- Schlagen Sie
expressionHashPrefix
im lokalen Cache nach. - Wenn der im Cache gespeicherte Eintrag gefunden wird:
- Bestimmen Sie, ob die aktuelle Zeit nach der Ablaufzeit ist.
- Ist er höher:
- Entfernen Sie den im Cache gefundenen Eintrag aus dem lokalen Cache.
- Fahren Sie mit der Schleife fort.
- Ist er nicht größer:
- Entferne dieses bestimmte
expressionHashPrefix
ausexpressionHashPrefixes
. - Prüfe, ob der entsprechende vollständige Hash in
expressionHashes
im im Cache gespeicherten Eintrag enthalten ist. - Falls gefunden, wird
UNSAFE
zurückgegeben. - Wenn Sie ihn nicht finden, fahren Sie mit der Schleife fort.
- Entferne dieses bestimmte
- Wenn der im Cache gespeicherte Eintrag nicht gefunden wird, fahren Sie mit der Schleife fort.
- Schlagen Sie
- Senden Sie
expressionHashPrefixes
mithilfe von RPC SearchHashes oder der REST-Methode hashes.search an den Server von Google Safe Browsing Version 5. Wenn ein Fehler aufgetreten ist (einschließlich Netzwerkfehlern, HTTP-Fehlern usw.), geben SieUNSURE
zurück. Andernfalls kann die Antwort dieresponse
sein, die vom SB-Server empfangen wurde. Dabei handelt es sich um eine Liste mit vollständigen Hashes und einigen zusätzlichen Informationen zur Art der Bedrohung (Social Engineering, Malware usw.) sowie der Cache-Ablaufzeitexpiration
. - Für jeden
fullHash
vonresponse
:- Fügen Sie
fullHash
zusammen mitexpiration
in den lokalen Cache ein.
- Fügen Sie
- Für jeden
fullHash
vonresponse
:- Lass
isFound
das Ergebnis des Ergebnisses vonfullHash
inexpressionHashes
sein. - Wenn
isFound
auf „False“ gesetzt ist, wird die Schleife wiederholt. - Wenn
isFound
"True" ist, wirdUNSAFE
zurückgegeben.
- Lass
- Rückflug:
SAFE
.
URL-Prüfung für „LocalThreat List“
Dieses Verfahren wird verwendet, wenn der Client den Betriebsmodus „Lokale Liste“ auswählt. Sie wird auch verwendet, wenn der Client das oben beschriebene RealTimeCheck-Verfahren den Wert von UNSURE
zurückgibt.
Bei diesem Vorgang wird für eine einzelne URL u
verwendet und SAFE
oder UNSAFE
zurückgegeben.
- Lass
expressions
eine Liste von Suffix-/Präfix-Ausdrü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, bei der die Elemente die ersten 4 Byte jedes Hashwerts inexpressionHashes
sind. - Für jeden
expressionHashPrefix
vonexpressionHashPrefixes
:- Schlagen Sie
expressionHashPrefix
im lokalen Cache nach. - Wenn der im Cache gespeicherte Eintrag gefunden wird:
- Bestimmen Sie, ob die aktuelle Zeit nach der Ablaufzeit ist.
- Ist er höher:
- Entfernen Sie den im Cache gefundenen Eintrag aus dem lokalen Cache.
- Fahren Sie mit der Schleife fort.
- Ist er nicht größer:
- Entferne dieses bestimmte
expressionHashPrefix
ausexpressionHashPrefixes
. - Prüfe, ob der entsprechende vollständige Hash in
expressionHashes
im im Cache gespeicherten Eintrag enthalten ist. - Falls gefunden, wird
UNSAFE
zurückgegeben. - Wenn Sie ihn nicht finden, fahren Sie mit der Schleife fort.
- Entferne dieses bestimmte
- Wenn der im Cache gespeicherte Eintrag nicht gefunden wird, fahren Sie mit der Schleife fort.
- Schlagen Sie
- Für jeden
expressionHashPrefix
vonexpressionHashPrefixes
:- Schlagen Sie
expressionHashPrefix
in der lokalen Datenbank mit Bedrohungslisten nach. - Wenn die
expressionHashPrefix
nicht in der lokalen Bedrohungslistendatenbank gefunden werden kann, entfernen Sie sie ausexpressionHashPrefixes
.
- Schlagen Sie
- Senden Sie
expressionHashPrefixes
mithilfe von RPC SearchHashes oder der REST-Methode hashes.search an den Server von Google Safe Browsing Version 5. Wenn ein Fehler aufgetreten ist (einschließlich Netzwerkfehlern, HTTP-Fehlern usw.), geben SieSAFE
zurück. Andernfalls kann die Antwort dieresponse
sein, die vom SB-Server empfangen wurde. Dabei handelt es sich um eine Liste mit vollständigen Hashes und einigen zusätzlichen Informationen zur Art der Bedrohung (Social Engineering, Malware usw.) sowie der Cache-Ablaufzeitexpiration
. - Für jeden
fullHash
vonresponse
:- Fügen Sie
fullHash
zusammen mitexpiration
in den lokalen Cache ein.
- Fügen Sie
- Für jeden
fullHash
vonresponse
:- Lass
isFound
das Ergebnis des Ergebnisses vonfullHash
inexpressionHashes
sein. - Wenn
isFound
auf „False“ gesetzt ist, wird die Schleife wiederholt. - 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 „Kein Speicher“ auswählt.
Bei diesem Vorgang wird für eine einzelne URL u
verwendet und SAFE
oder UNSAFE
zurückgegeben.
- Lass
expressions
eine Liste von Suffix-/Präfix-Ausdrü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, bei der die Elemente die ersten 4 Byte jedes Hashwerts inexpressionHashes
sind. - Für jeden
expressionHashPrefix
vonexpressionHashPrefixes
:- Schlagen Sie
expressionHashPrefix
im lokalen Cache nach. - Wenn der im Cache gespeicherte Eintrag gefunden wird:
- Bestimmen Sie, ob die aktuelle Zeit nach der Ablaufzeit ist.
- Ist er höher:
- Entfernen Sie den im Cache gefundenen Eintrag aus dem lokalen Cache.
- Fahren Sie mit der Schleife fort.
- Ist er nicht größer:
- Entferne dieses bestimmte
expressionHashPrefix
ausexpressionHashPrefixes
. - Prüfe, ob der entsprechende vollständige Hash in
expressionHashes
im im Cache gespeicherten Eintrag enthalten ist. - Falls gefunden, wird
UNSAFE
zurückgegeben. - Wenn Sie ihn nicht finden, fahren Sie mit der Schleife fort.
- Entferne dieses bestimmte
- Wenn der im Cache gespeicherte Eintrag nicht gefunden wird, fahren Sie mit der Schleife fort.
- Schlagen Sie
- Senden Sie
expressionHashPrefixes
mithilfe von RPC SearchHashes oder der REST-Methode hashes.search an den Server von Google Safe Browsing Version 5. Wenn ein Fehler aufgetreten ist (einschließlich Netzwerkfehlern, HTTP-Fehlern usw.), geben SieSAFE
zurück. Andernfalls kann die Antwort dieresponse
sein, die vom SB-Server empfangen wurde. Dabei handelt es sich um eine Liste mit vollständigen Hashes und einigen zusätzlichen Informationen zur Art der Bedrohung (Social Engineering, Malware usw.) sowie der Cache-Ablaufzeitexpiration
. - Für jeden
fullHash
vonresponse
:- Fügen Sie
fullHash
zusammen mitexpiration
in den lokalen Cache ein.
- Fügen Sie
- Für jeden
fullHash
vonresponse
:- Lass
isFound
das Ergebnis des Ergebnisses vonfullHash
inexpressionHashes
sein. - Wenn
isFound
auf „False“ gesetzt ist, wird die Schleife wiederholt. - Wenn
isFound
"True" ist, wirdUNSAFE
zurückgegeben.
- Lass
- Rückflug:
SAFE
.
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 Speicherplatz“ aus. Format und Speicherung dieser lokalen Datenbank hängt vom Client ab. Der Inhalt dieser lokalen Datenbank kann man sich als 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 Client in der Regel mehrere Listen gleichzeitig aktualisieren möchte, empfiehlt es sich, die hashLists.batchGet-Methode zu verwenden.
Listen werden durch ihre eindeutigen Namen identifiziert. Die Namen sind kurze ASCII-Strings mit wenigen Zeichen.
Im Gegensatz zu V4, wo Listen durch das Tupel des Bedrohungstyps, des Plattformtyps und des Bedrohungseintragstyps identifiziert werden, werden in V5-Listen einfach namentlich angegeben. Das bietet Flexibilität, wenn mehrere V5-Listen denselben Bedrohungstyp verwenden können. Plattformtypen und Bedrohungseintragstypen wurden in Version 5 entfernt.
Sobald ein Name für eine Liste ausgewählt wurde, wird dieser nie wieder umbenannt. Sobald eine Liste angezeigt wurde, wird sie niemals entfernt. Wenn die Liste nicht mehr nützlich ist, ist sie leer, bleibt aber bestehen. Daher empfiehlt es sich, diese Namen im Google Safe Browsing-Clientcode hartzucodieren.
Sowohl die Methode hashList.get als auch die Methode hashLists.batchGet unterstützen inkrementelle Updates. Durch inkrementelle Updates wird Bandbreite gespart und die Leistung verbessert. Bei inkrementellen Aktualisierungen wird eine Differenz zwischen der vom Kunden angegebenen Version der Liste und der neuesten Version der Liste ausgegeben. (Wenn ein Client neu bereitgestellt wird und keine Versionen verfügbar sind, ist ein vollständiges Update verfügbar.) Das schrittweise Update enthält Indizes zur Entfernung von Inhalten und Ergänzungen. Vom Client wird zuerst erwartet, dass er die Einträge bei den angegebenen Indizes 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.
Listeninhalt 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 sich statistisch nicht von zufälligen Ganzzahlen unterscheiden. Wenn wir diese Ganzzahlen sortieren und ihre benachbarte Differenz erfassen würden, wird erwartet, dass die benachbarte Differenz in gewisser Weise „klein“ ist. Die Golomb-Rice-Codierung nutzt diese Kleinigkeit dann aus.
Google Safe Browsing v5 hat vier verschiedene Typen zur Verarbeitung von 4-Byte-, 8-Byte-, 16-Byte- und 32-Byte-Daten. Sehen wir uns ein Beispiel an, in dem drei numerisch aufeinanderfolgende 4-Byte-Ganzzahlen codiert sind. Der durch k gekennzeichnete Reis-Parameter sollte 3 sein. Der Quotiententeil der Codierung ist einfach der benachbarte Differenzwert, der um k Bit nach rechts verschoben wurde. Da die angegebenen Ganzzahlen fortlaufend sind, beträgt ihre benachbarte Differenz 1 und nach einer Verschiebung um 3 Bit ist der Quotiententeil null. Die niedrigstwertigen k Bit sind 001. Der Null-Quotient wird als einzelnes 0-Bit codiert. Der Rest ist 1 und wird mit 100 codiert. Dies wird erneut wiederholt, um den Bitstream 01000100 zu bilden. Der resultierende Bitstream wird mit Little-Endian als 00100010 codiert. Daher entspricht sie den folgenden Daten:
rice_parameter: 3
entries_count: 2
encoded_data: "\x22"
Nach dem obigen Decodierungsschritt für 32-Bit-Ganzzahlen kann das Ergebnis direkt als Entfernungsindexe oder Ergänzungen verwendet werden. Im Gegensatz zu v4 ist danach kein Byte-Swap erforderlich.
Verfügbare Listen
Die folgenden Listen werden für die Verwendung in v5alpha1 empfohlen:
Name der Liste | Entsprechende ThreatType -Enum der Version 4 |
Beschreibung |
---|---|---|
gc |
Keine | Diese Liste ist eine globale Cache-Liste. Dies ist 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 sind zu einem späteren Zeitpunkt verfügbar. Die oben stehende Tabelle wird dann erweitert.
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. In diesem Fall sollte der Client sofort eine weitere Aktualisierung durchführen.
Beispiele für Anforderungen
In diesem Abschnitt finden Sie einige Beispiele für die direkte Verwendung der HTTP API für den Zugriff auf Google Safe Browsing. Im Allgemeinen wird die Verwendung einer generierten Sprachbindung empfohlen, da sie die Codierung und Decodierung automatisch auf eine bequeme Weise handhabt. Weitere Informationen finden Sie in der Dokumentation zur jeweiligen Bindung.
Hier sehen Sie 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 mit Protokollpuffer formatierte Nutzlast, die Sie dann decodieren können.
Hier sehen Sie eine Beispiel-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 Version 4 Update API verwenden, können Sie nahtlos von Version 4 zu Version 5 migrieren, ohne die lokale Datenbank zurücksetzen oder löschen zu müssen. In diesem Abschnitt wird beschrieben, wie Sie dies tun.
Aktualisierungen von Konvertierungslisten
In Version 4 würde man die threatListUpdates.fetch-Methode zum Herunterladen von Listen verwenden. In v5 würde man zur hashLists.batchGet-Methode wechseln.
An der Anfrage sollten folgende Änderungen vorgenommen werden:
- Entfernen Sie das v4-Objekt vom Typ „
ClientInfo
“ vollständig. Anstatt die Identifizierung eines Kunden über ein spezielles Feld anzugeben, 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 die 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 obigen Tabelle nach dem entsprechenden V5-Listennamen und geben Sie ihn 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 Feldversions
von Version 5 kompatibel. Derselbe Bytestring, der in V4 über das Feldstate
an den Server gesendet wird, kann in V4 einfach über das Feldversions
gesendet werden. - Für die Einschränkungen von Version 4 wird in Version 5 eine vereinfachte Version namens
SizeConstraints
verwendet. Zusätzliche Felder wieregion
sollten entfernt werden.
An der Antwort sollten die folgenden Änderungen vorgenommen werden:
- Die Aufzählung
ResponseType
aus Version 4 wird einfach durch ein boolesches Feld namenspartial_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 senden. 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 jedoch beim Sortieren als Little-Endian behandelt, während in v5 diese Präfixe beim Sortieren als Big-Endian behandelt werden. Das bedeutet, dass der Client keine Sortierung vornehmen muss, da die lexikografische Sortierung mit der numerischen Sortierung mit Big-Endian identisch ist. Ein Beispiel für diese Art in der Chromium-Implementierung von Version 4 finden Sie hier. Solche Sortierungen können entfernt werden.
- Der Rice-Decodierungsalgorithmus muss für andere Hash-Längen implementiert werden.
Hash-Suchanfragen konvertieren
In v4 würde die fullHashes.find-Methode verwendet werden, um die vollständigen Hashes zu erhalten. Die entsprechende Methode in Version 5 ist die Methode hashes.search.
An der Anfrage sollten folgende Änderungen vorgenommen werden:
- Strukturieren Sie den Code so, dass nur Hash-Präfixe gesendet werden, die genau 4 Byte lang sind.
- Entfernen Sie die
ClientInfo
-Objekte aus Version 4 vollständig. Anstatt die Identifizierung eines Kunden über ein spezielles Feld anzugeben, 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 die Client-Version anzugeben, getrennt durch ein Leerzeichen oder einen Schrägstrich. - Entfernen Sie das Feld
client_states
. Es ist nicht mehr erforderlich. threat_types
und ähnliche Felder müssen nicht mehr enthalten sein.
An der Antwort sollten die folgenden Änderungen vorgenommen werden:
- Das Feld „
minimum_wait_duration
“ wurde entfernt. Der Kunde kann bei Bedarf jederzeit eine neue Anfrage stellen. - Das v4
ThreatMatch
-Objekt wurde zumFullHash
-Objekt vereinfacht. - Das Caching wurde auf eine einzige Cache-Dauer vereinfacht. Gehen Sie wie oben beschrieben vor, um mit dem Cache zu interagieren.