Local Database
Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Bei Google Safe Browsing v5 muss der Client eine lokale Datenbank verwalten, es sei denn, er wählt den Echtzeitmodus ohne Speicher aus. Format und Speicherort dieser lokalen Datenbank liegen im Ermessen des Kunden. Der Inhalt dieser lokalen Datenbank kann als Ordner mit verschiedenen Listen als Dateien betrachtet werden. Der Inhalt dieser Dateien sind SHA256-Hashes oder die entsprechenden Präfixe. Das vier Byte lange Hash-Präfix ist die am häufigsten verwendete Hash-Länge.
Verfügbare Listen
Listen werden anhand ihrer eindeutigen Namen identifiziert, die einer Namenskonvention folgen. Der Name enthält ein Suffix, das die Länge des Hashwerts angibt, der in der Liste erwartet wird. Hash-Listen mit demselben Bedrohungstyp, aber unterschiedlicher Hash-Länge, werden in einer separat benannten Liste mit einem Suffix angegeben, das die Hash-Länge angibt.
Die folgenden Listen können mit den Hash-Listenmethoden verwendet werden.
| Name der Liste |
Entsprechendes ThreatType-Enum der Version 4 |
Beschreibung |
gc-32b |
Keine |
Diese Liste ist eine globale Cache-Liste. Es handelt sich um eine spezielle Liste, die nur im Echtzeitmodus verwendet wird. |
se-4b |
SOCIAL_ENGINEERING |
Diese Liste enthält Bedrohungen vom Typ SOCIAL_ENGINEERING. |
mw-4b |
MALWARE |
Diese Liste enthält Bedrohungen vom Typ MALWARE für Desktop-Plattformen. |
uws-4b |
UNWANTED_SOFTWARE |
Diese Liste enthält Bedrohungen vom Typ UNWANTED_SOFTWARE für Desktop-Plattformen. |
uwsa-4b |
UNWANTED_SOFTWARE |
Diese Liste enthält Bedrohungen vom Typ UNWANTED_SOFTWARE für Android-Plattformen. |
pha-4b |
POTENTIALLY_HARMFUL_APPLICATION |
Diese Liste enthält Bedrohungen vom Typ POTENTIALLY_HARMFUL_APPLICATION für Android-Plattformen. |
Weitere Listen können zu einem späteren Zeitpunkt verfügbar werden. In diesem Fall wird die obige Tabelle erweitert und die Ergebnisse der hashList.list-Methode zeigen ein ähnliches Ergebnis mit den aktuellsten Listen.
Datenbankaktualisierungen
Der Client ruft regelmäßig die Methode hashList.get oder die Methode hashLists.batchGet auf, um die Datenbank zu aktualisieren. Da der typische Kunde mehrere Listen gleichzeitig aktualisieren möchte, wird die Methode „hashLists.batchGet“ empfohlen.
Die Listennamen werden nie umbenannt. Außerdem wird eine Liste, die einmal angezeigt wurde, nie wieder entfernt. Wenn sie nicht mehr nützlich ist, wird sie leer, bleibt aber bestehen. Daher sollten diese Namen im Google Safe Browsing-Clientcode hartcodiert werden.
Sowohl die Methode „hashList.get“ als auch die Methode „hashLists.batchGet“ unterstützen inkrementelle Updates. Mit inkrementellen Updates wird Bandbreite gespart und die Leistung verbessert. Bei inkrementellen Updates wird ein Delta zwischen der Version der Liste des Clients und der neuesten Version der Liste gesendet. Wenn ein Client neu bereitgestellt wird und keine Versionen verfügbar sind, ist ein vollständiges Update verfügbar. Das inkrementelle Update enthält Indexe für Entfernungen und Ergänzungen. Der Client muss zuerst die Einträge an den angegebenen Indizes aus seiner lokalen Datenbank entfernen und dann die Ergänzungen anwenden.
Um Beschädigungen zu vermeiden, sollte der Client die gespeicherten Daten schließlich mit der vom Server bereitgestellten Prüfsumme vergleichen. Wenn die Prüfsumme nicht übereinstimmt, sollte der Client eine vollständige Aktualisierung durchführen.
Listeninhalte decodieren
Hashes und Hash-Präfixe decodieren
Alle Listen werden mit einer speziellen Codierung gesendet, 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 zu unterscheiden sind. Wenn wir diese ganzen Zahlen sortieren und den Differenzbetrag zwischen benachbarten Zahlen ermitteln, sollte dieser Differenzbetrag in gewissem Sinne „klein“ sein. Die Golomb-Rice-Codierung nutzt diese Kleinheit dann aus.
Angenommen, drei Host-Suffix-Pfadpräfixausdrücke, nämlich a.example.com/, b.example.com/ und y.example.com/, sollen mit 4‑Byte-Hash-Präfixen übertragen werden. Angenommen, der Rice-Parameter, der mit k bezeichnet wird, hat den Wert
- Der Server berechnet zuerst den vollständigen Hash für diese Strings:
291bc5421f1cd54d99afcc55d166e2b9fe42447025895bf09dd41b2110a687dc a.example.com/
1d32c5084a360e58f1b87109637a6810acad97a861a7769e8f1841410d2a960c b.example.com/
f7a502e56e8b01c6dc242b35122683c9d25d07fb1f532d9853eb0ef3ff334f03 y.example.com/
Der Server bildet dann für jedes der oben genannten Elemente 4-Byte-Hash-Präfixe. Das sind die ersten 4 Byte des 32-Byte-vollständigen Hashwerts, die als Big-Endian-32-Bit-Ganzzahlen interpretiert werden. Big-Endian-Format bezieht sich darauf, dass das erste Byte des vollständigen Hashes zum höchstwertigen 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 lexikalisch sortieren (entspricht der numerischen Sortierung in Big-Endian-Format). Das Ergebnis der Sortierung ist 0x1d32c508, 0x291bc542 und 0xf7a502e5. Das erste Hash-Präfix wird unverändert im Feld first_value gespeichert.
Der Server berechnet dann die beiden benachbarten Unterschiede, also 0xbe9003a und 0xce893da3. Da k = 30 ist, teilt der Server diese beiden Zahlen in Quotienten- und Restteile auf, die jeweils 2 und 30 Bit lang sind. Bei der ersten Zahl ist der Quotiententeil null und der Rest ist 0xbe9003a. Bei der zweiten Zahl ist der Quotiententeil 3, da die beiden höchstwertigen Bits im Binärformat 11 sind, und der Rest ist 0xe893da3. Bei einem bestimmten Quotienten q wird er mit genau 1 + q Bits in (1 << q) - 1 codiert. Der Rest wird direkt mit k Bits codiert. Der Quotiententeil der ersten Zahl ist als 0 codiert und der Restteil als Binärzahl 001011111010010000000000111010; der Quotiententeil der zweiten Zahl ist als 0111 codiert und der Restteil als 001110100010010011110110100011.
Wenn diese Zahlen zu einem Byte-String kombiniert werden, wird Little Endian verwendet. Es ist konzeptionell einfacher, sich einen langen Bitstring vorzustellen, der mit den niedrigstwertigen Bits beginnt: Wir nehmen den Quotiententeil der ersten Zahl und fügen den Restteil der ersten Zahl voran. Dann fügen wir den Quotiententeil der zweiten Zahl und den Restteil voran. Dies sollte zu der folgenden großen Zahl führen (Zeilentrennzeichen 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 Zeile würde das so aussehen:
00111010001001001111011010001101110010111110100100000000001110100
Diese Zahl übersteigt natürlich die 8 Bits, die in einem einzelnen Byte verfügbar sind. Bei der Little-Endian-Codierung werden dann die acht niedrigstwertigen Bits dieser Zahl als erstes Byte ausgegeben, also 01110100. Zur Verdeutlichung können wir den obigen Bitstring in Gruppen zu acht Bits gruppieren, beginnend mit den niedrigstwertigen Bits:
0 01110100 01001001 11101101 00011011 10010111 11010010 00000000 01110100
Bei der Little-Endian-Codierung wird dann jedes Byte von rechts in einen Bytestring eingefügt:
01110100
00000000
11010010
10010111
00011011
11101101
01001001
01110100
00000000
Da wir neue Teile konzeptionell voranstellen (d.h. mehr signifikante Bits hinzufügen), aber von rechts (d.h. von den weniger signifikanten Bits) codieren, können Codierung und Dekodierung inkrementell erfolgen.
Das führt letztendlich zu
additions_four_bytes {
first_value: 489866504
rice_parameter: 30
entries_count: 2
encoded_data: "t\000\322\227\033\355It\000"
}
Der Client führt einfach die oben beschriebenen Schritte in umgekehrter Reihenfolge aus, um die Hash-Präfixe zu decodieren.
Dekodierungsindexe für Entfernungen
Entfernungsindexe werden mit derselben Methode wie oben mit 32-Bit-Ganzzahlen codiert.
Aktualisierungshäufigkeit
Der Client sollte den vom Server zurückgegebenen Wert im Feld minimum_wait_duration prüfen und anhand dieses Werts die nächste Aktualisierung der Datenbank planen. Dieser Wert ist möglicherweise null (das Feld minimum_wait_duration fehlt vollständig). In diesem Fall MUSS der Client sofort eine weitere Aktualisierung ausführen.
Sofern nicht anders angegeben, sind die Inhalte dieser Seite unter der Creative Commons Attribution 4.0 License und Codebeispiele unter der Apache 2.0 License lizenziert. Weitere Informationen finden Sie in den Websiterichtlinien von Google Developers. Java ist eine eingetragene Marke von Oracle und/oder seinen Partnern.
Zuletzt aktualisiert: 2025-07-25 (UTC).
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Benötigte Informationen nicht gefunden","missingTheInformationINeed","thumb-down"],["Zu umständlich/zu viele Schritte","tooComplicatedTooManySteps","thumb-down"],["Nicht mehr aktuell","outOfDate","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Problem mit Beispielen/Code","samplesCodeIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-07-25 (UTC)."],[],[],null,["# Local Database\n\nGoogle Safe Browsing v5 expects the client to maintain a local database, except when the client chooses the [No-Storage Real-Time Mode](/safe-browsing/reference#no-storage-real-time-mode). It is up to the client the format and storage of this local database. The contents of this local database can conceptually be thought of as a folder containing various lists as files, and the contents of these files are SHA256 hashes, or their corresponding prefixes with four byte hash prefix being the most commonly used hash length.\n\n### Available Lists\n\nLists are identified by their distinct names which follows a naming convention where the name contains a suffix that signifies the length of the hash you should expect in the list. Hash lists with the same threat type but different hash length will be a separately named list that's qualified with a suffix that indicates the hash length.\n\nThe following lists are available for use with the hash list methods.\n\n| List Name | Corresponding v4 `ThreatType` Enum | Description |\n|-----------|------------------------------------|------------------------------------------------------------------------------------------------------|\n| `gc-32b` | None | This list is a Global Cache list. It is a special list only used in the Real-Time mode of operation. |\n| `se-4b` | `SOCIAL_ENGINEERING` | This list contains threats of the SOCIAL_ENGINEERING threat type. |\n| `mw-4b` | `MALWARE` | This list contains threats of the MALWARE threat type for desktop platforms. |\n| `uws-4b` | `UNWANTED_SOFTWARE` | This list contains threats of the UNWANTED_SOFTWARE threat type for desktop platforms. |\n| `uwsa-4b` | `UNWANTED_SOFTWARE` | This list contains threats of the UNWANTED_SOFTWARE threat type for Android platforms. |\n| `pha-4b` | `POTENTIALLY_HARMFUL_APPLICATION` | This list contains threats of the POTENTIALLY_HARMFUL_APPLICATION threat type for Android platforms. |\n\nAdditional lists can become available at a later date, at which time the above table will be expanded, and the results from the [hashList.list method](/safe-browsing/reference/rest/v5/hashList/list) will show a similar result with the most up to date lists.\n\n### Database Updates\n\nThe client will regularly call the [hashList.get method](/safe-browsing/reference/rest/v5/hashList/get) or the [hashLists.batchGet method](/safe-browsing/reference/rest/v5/hashLists/batchGet) to update the database. Since the typical client will want to update multiple lists at a time, it is recommended to use [hashLists.batchGet method](/safe-browsing/reference/rest/v5/hashLists/batchGet).\n\nThe list names will never be renamed. Furthermore, once a list has appeared, it will never be removed (if the list is no longer useful, it will become empty but will continue to exist). Therefore, it is appropriate to hard code these names in the Google Safe Browsing client code.\n\nBoth the [hashList.get method](/safe-browsing/reference/rest/v5/hashList/get) and the [hashLists.batchGet method](/safe-browsing/reference/rest/v5/hashLists/batchGet) support incremental updates. Using incremental updates saves bandwidth and improves performance. Incremental updates work by delivering a delta between client's version of the list and the latest version of the list. (If a client is newly deployed and does not have any versions available, a full update is available.) The incremental update contains removal indices and additions. The client is first expected to remove the entries at the specified indices from its local database, and then apply the additions.\n\nFinally, to prevent corruption, the client should check the stored data against the checksum provided by the server. Whenever the checksum does not match, the client should perform a full update.\n\n### Decoding the List Content\n\n#### Decoding Hashes and Hash Prefixes\n\nAll lists are delivered using a special encoding to reduce size. This encoding works by recognizing that Google Safe Browsing lists contain, conceptually, a set of hashes or hash prefixes, which are statistically indistinguishable from random integers. If we were to sort these integers and take their adjacent difference, such adjacent difference is expected to be \"small\" in a sense. [Golomb-Rice encoding](https://en.wikipedia.org/wiki/Golomb_coding) then exploits this smallness.\n\nSuppose that three host-suffix path-prefix expressions, namely `a.example.com/`, `b.example.com/`, and `y.example.com/`, are to be transmitted using 4-byte hash prefixes. Further suppose that the Rice parameter, denoted by k, is chosen to be\n\n1. The server would start by calculating the full hash for these strings, which are, respectively:\n\n 291bc5421f1cd54d99afcc55d166e2b9fe42447025895bf09dd41b2110a687dc a.example.com/\n 1d32c5084a360e58f1b87109637a6810acad97a861a7769e8f1841410d2a960c b.example.com/\n f7a502e56e8b01c6dc242b35122683c9d25d07fb1f532d9853eb0ef3ff334f03 y.example.com/\n\nThe server then forms 4-byte hash prefixes for each of the above, which is the first 4 bytes of the 32-byte full hash, interpreted as big-endian 32-bit integers. The big endianness refers to the fact that the first byte of the full hash becomes the most significant byte of the 32-bit integer. This step results in the integers 0x291bc542, 0x1d32c508, and 0xf7a502e5.\n\nIt is necessary for the server to sort these three hash prefixes lexicographically (equivalent to numerical sorting in big endian), and the result of the sorting is 0x1d32c508, 0x291bc542, 0xf7a502e5. The first hash prefix is stored unchanged in the `first_value` field.\n\nThe server then calculates the two adjacent differences, which are 0xbe9003a and 0xce893da3 respectively. Given that k is chosen to be 30, the server splits these two numbers into the quotient parts and remainder parts that are 2 and 30 bits long respectively. For the first number, the quotient part is zero and the remainder is 0xbe9003a; for the second number, the quotient part is 3 because the most significant two bits are 11 in binary and the remainder is 0xe893da3. For a given quotient `q` it is encoded into `(1 \u003c\u003c q) - 1` using exactly `1 + q` bits; the remainder is encoded directly using k bits. The quotient part of the first number is encoded as 0, and the remainder part is in binary 001011111010010000000000111010; the quotient part of the second number is encoded as 0111, and the remainder part is 001110100010010011110110100011.\n\nWhen these numbers are formed into a byte string, little endian is used. Conceptually it may be easier to imagine a long bitstring being formed starting from the least significant bits: we take the quotient part of the first number and prepend the remainder part of the first number; we then further prepend the quotient part of the second number and prepend the remainder part. This should result in the following large number (linebreaks and comments added for clarity): \n\n 001110100010010011110110100011 # Second number, remainder part\n 0111 # Second number, quotient part\n 001011111010010000000000111010 # First number, remainder part\n 0 # First number, quotient part\n\nWritten in a single line this would be \n\n 00111010001001001111011010001101110010111110100100000000001110100\n\nObviously this number far exceeds the 8 bits available in a single byte. The little endian encoding then takes the least significant 8 bits in that number, and outputs it as the first byte which is 01110100. For clarity, we can group the above bitstring into groups of eight starting from the least significant bits: \n\n 0 01110100 01001001 11101101 00011011 10010111 11010010 00000000 01110100\n\nThe little endian encoding then takes each byte from the right and puts that into a bytestring: \n\n 01110100\n 00000000\n 11010010\n 10010111\n 00011011\n 11101101\n 01001001\n 01110100\n 00000000\n\nIt can be seen that since we conceptually *prepend* new parts to the large number on the left (i.e. adding more significant bits) but we encode from the right (i.e. the least significant bits), the encoding and decoding can be performed incrementally.\n\nThis finally results in \n\n additions_four_bytes {\n first_value: 489866504\n rice_parameter: 30\n entries_count: 2\n encoded_data: \"t\\000\\322\\227\\033\\355It\\000\"\n }\n\nThe client simply follows the above steps in reverse to decode the hash prefixes.\n\n#### Decoding Removal Indices\n\nRemoval indices are encoded using the exact same technique as above using 32-bit integers.\n\n### Update Frequency\n\nThe client should inspect the server's returned value in the field `minimum_wait_duration` and use that to schedule the next update of the database. This value is possibly zero (the field `minimum_wait_duration` is completely missing), in which case the client SHOULD immediately perform another update."]]
