Overview

Introduction

Remarque: Cette documentation est en cours de développement. Nous prévoyons des améliorations prochainement.

La navigation sécurisée Google v5 est une évolution de la version 4 de la navigation sécurisée Google. Dans la version 5, les deux principales modifications apportées sont la fraîcheur des données et la confidentialité des adresses IP. De plus, la surface de l'API a été améliorée pour accroître la flexibilité et l'efficacité, et réduire la surcharge. De plus, la version 5 de la navigation sécurisée Google est conçue pour faciliter la migration depuis la version 4.

Actuellement, Google propose les versions 4 et 5, qui sont toutes deux considérées comme prêtes pour la production. Vous pouvez utiliser la version 4 ou 5. Nous n'avons pas encore annoncé la date d'arrêt de la version 4. Le cas échéant, nous vous enverrons un préavis d'au moins un an. Cette page présente la version 5, ainsi qu'un guide de migration de la version 4 à la version 5 (la documentation complète de cette version reste disponible).

Fraîcheur des données

La fraîcheur et la couverture des données constituent une amélioration significative de la version 5 de la navigation sécurisée Google par rapport à la version 4 (en particulier, l'API Update v4). Étant donné que la protection dépend en grande partie de la base de données locale gérée par le client, le délai et la taille de la mise à jour de la base de données locale sont les principaux facteurs de la perte de protection. Dans la version 4, il faut généralement entre 20 et 50 minutes à un client pour obtenir la version la plus récente des listes de menaces. Malheureusement, les attaques par hameçonnage se propagent rapidement: en 2021, 60% des sites qui en sont la cible ont une durée de vie inférieure à 10 minutes. Nos analyses montrent qu'environ 25 à 30% de l'absence de protection contre l'hameçonnage s'explique par l'obsolescence des données. De plus, certains appareils ne sont pas en mesure de gérer l'intégralité des listes des menaces liées à la navigation sécurisée Google, qui ne cessent de s'étoffer au fil du temps.

Dans la version 5, nous introduisons un mode de fonctionnement appelé "protection en temps réel". Cela permet de contourner le problème d'obsolescence des données décrit ci-dessus. Dans la version 4, les clients doivent télécharger et gérer une base de données locale, effectuer des vérifications par rapport aux listes de menaces téléchargées localement, puis, en cas de correspondance partielle de préfixe, exécuter une requête pour télécharger le hachage complet. Dans la version 5, même si les clients doivent continuer à télécharger et à gérer une base de données locale de listes de menaces, ils doivent aussi télécharger une liste de sites sans danger (appelé « Cache global »), effectuer une vérification locale de ce cache global ainsi qu’une vérification locale de la liste des menaces. Enfin, en cas de correspondance partielle des préfixes pour les listes de menaces ou d’absence de correspondance dans le cache global, exécutez une requête pour télécharger les hachages complets. (Pour en savoir plus sur le traitement local requis par le client, reportez-vous à la procédure ci-dessous.) Cela représente le passage de l'autorisation par défaut à la vérification par défaut, ce qui peut améliorer la protection compte tenu d'une propagation plus rapide des menaces sur le Web. En d'autres termes, il s'agit d'un protocole conçu pour offrir une protection en temps quasi réel: nous souhaitons que nos clients bénéficient de données de navigation sécurisée Google plus récentes.

Confidentialité des adresses IP

La navigation sécurisée Google (v4 ou v5) ne traite aucun élément associé à l'identité d'un utilisateur lors du traitement des demandes. S'ils sont envoyés, les cookies sont ignorés. Nous connaissons les adresses IP d'origine des requêtes, mais Google n'utilise ces adresses IP que pour les besoins réseau essentiels (pour l'envoi de réponses, par exemple) et pour lutter contre les attaques DoS.

Conjointement à la version 5, nous lançons une API associée : l'API Safe Browsing Oblivious HTTP Gateway. Le protocole Oblivious HTTP est utilisé pour masquer les adresses IP des utilisateurs finaux sur Google. Pour ce faire, un tiers non collaborant doit traiter une version chiffrée de la requête de l'utilisateur, puis la transmettre à Google. Ainsi, le tiers n'a accès qu'aux adresses IP et Google n'a accès qu'au contenu de la requête. Le tiers gère un relais HTTP Oblivious (tel que ce service de Fastly) et Google gère la passerelle HTTP Oblivious. Il s'agit d'une API associée facultative. Lorsque ce service est utilisé conjointement avec la navigation sécurisée Google, les adresses IP des utilisateurs finaux ne sont plus envoyées à Google.

Utilisation appropriée

Utilisation autorisée

L'API Safe Browsing est destinée à une utilisation non commerciale uniquement (c'est-à-dire non destinée à la vente ou à la génération de revenus). Si vous avez besoin d'une solution à des fins commerciales, veuillez consulter Web Risk.

Tarification

Toutes les API de navigation sécurisée Google sont sans frais.

Quotas

Un quota d'utilisation par défaut est attribué aux développeurs lors de l'activation de l'API Safe Browsing. Vous pouvez consulter l'allocation et l'utilisation actuelles dans la Google Play Console. Si vous prévoyez d'utiliser plus que le quota qui vous est actuellement alloué, vous pouvez demander un quota supplémentaire depuis l'interface des quotas de la Developer Console. Nous examinons ces demandes et avons besoin d'un contact pour nous assurer que la disponibilité de notre service répond aux besoins de tous les utilisateurs.

URL appropriées

La navigation sécurisée Google est conçue pour agir sur les URL qui sont affichées dans la barre d'adresse d'un navigateur. Il n'est pas conçu pour être utilisé pour comparer des sous-ressources (telles qu'un code JavaScript ou une image référencée par un fichier HTML, ou une URL WebSocket lancée par JavaScript). Ces URL de sous-ressources ne doivent pas être comparées à la navigation sécurisée Google.

Si l'accès à une URL entraîne une redirection (HTTP 301, par exemple), il convient de vérifier l'URL de redirection dans la navigation sécurisée Google. La manipulation des URL côté client, comme History.pushState, n'entraîne pas la vérification des nouvelles URL au regard de la navigation sécurisée Google.

Avertissements utilisateur

Si vous utilisez la navigation sécurisée Google pour avertir les utilisateurs des risques liés à certaines pages Web, les consignes suivantes s'appliquent.

Ces consignes aident à vous protéger, vous et Google, contre tout malentendu. En effet, elles indiquent clairement que la page n'est pas considérée à 100% comme étant une ressource Web non sécurisée, et que les avertissements ne font qu'identifier un risque potentiel.

• Dans l'avertissement visible pour l'utilisateur, vous ne devez pas faire croire aux utilisateurs que la page en question est, à l'évidence, une ressource Web dangereuse. Lorsque vous faites référence à la page identifiée ou aux risques potentiels qu'elle peut présenter aux internautes, vous devez qualifier l'avertissement à l'aide de termes tels que: suspicion, potentiellement, possible, probable.
• Votre avertissement doit permettre à l'utilisateur d'en savoir plus en examinant la définition Google des différentes menaces. Les liens suivants sont suggérés :
  • Ingénierie sociale: https://developers.google.com/search/docs/monitor-debug/security/social-engineering
  • Logiciels malveillants et indésirables: https://developers.google.com/search/docs/monitor-debug/security/malware
  • Applications potentiellement dangereuses (Android uniquement): https://developers.google.com/android/play-protect/potentially-harmful-applications
• Lorsque vous affichez des avertissements pour des pages identifiées comme dangereuses par le service de navigation sécurisée, vous devez mentionner le nom de Google en incluant la ligne "Conseil fourni par Google" avec un lien vers l'avis de navigation sécurisée. Si votre produit affiche également des avertissements basés sur d'autres sources, vous ne devez pas inclure l'attribution Google dans les avertissements provenant de données autres que Google.

• Dans la documentation de votre produit, vous devez informer les utilisateurs que la protection offerte par la navigation sécurisée Google n'est pas parfaite. Il doit leur faire savoir qu'il existe un risque de faux positifs (sites sécurisés signalés comme étant à risque) et de faux négatifs (sites à risque non signalés). Nous vous suggérons d'utiliser le langage suivant :

  Google s'efforce de fournir les informations les plus précises et les plus récentes sur les ressources Web non sécurisées. Toutefois, Google ne peut pas garantir que ses informations sont complètes et exemptes d'erreur: certains sites à risque peuvent ne pas être identifiés, et des sites sûrs peuvent être identifiés par erreur.

Modes de fonctionnement

La navigation sécurisée Google version 5 permet aux clients de choisir parmi trois modes de fonctionnement.

Mode "Temps réel"

Lorsque les clients choisissent d'utiliser la version 5 de la navigation sécurisée Google en mode en temps réel, ils conservent dans leur base de données locale: (i) un cache global de sites probablement inoffensifs sous la forme de hachages SHA256 des expressions d'URL du suffixe d'hôte/du préfixe de chemin d'accès, ou (ii) un ensemble de listes de menaces sous la forme de préfixes de hachage SHA256 d'expressions d'URL du suffixe d'hôte/préfixe de chemin d'accès. L'idée de haut niveau est que chaque fois que le client souhaite vérifier une URL particulière, une vérification locale est effectuée à l'aide du cache global. Si cette vérification réussit, une vérification des listes de menaces locales est effectuée. Sinon, le client poursuivra la vérification du hachage en temps réel, comme indiqué ci-dessous.

Outre la base de données locale, le client gérera un cache local. Un tel cache local n'a pas besoin de se trouver dans un espace de stockage persistant et peut être effacé en cas de saturation de la mémoire.

Vous trouverez ci-dessous une description détaillée de la procédure à suivre.

Mode Liste locale

Lorsque les clients choisissent d'utiliser la version 5 de la navigation sécurisée Google dans ce mode, leur comportement est semblable à celui de l'API Update v4, à l'exception de la surface d'API améliorée de la version 5. Les clients conserveront dans leur base de données locale un ensemble de listes de menaces sous forme de préfixes de hachage SHA256 d’expressions d’URL suffixe d’hôte/préfixe de chemin. Chaque fois que le client souhaite vérifier une URL particulière, une vérification est effectuée à l'aide de la liste de menaces locale. Si une correspondance est trouvée, le client se connecte au serveur pour poursuivre la vérification.

Comme pour ce qui précède, le client gère également un cache local qui n'a pas besoin de se trouver dans un espace de stockage persistant.

Mode temps réel sans stockage

Lorsque les clients choisissent d'utiliser la version 5 de la navigation sécurisée Google en mode en temps réel sans stockage, ils n'ont pas besoin de gérer de base de données locale. Chaque fois que le client souhaite vérifier une URL particulière, il se connecte toujours au serveur pour effectuer une vérification. Ce mode est semblable à ce que les clients de la version 4 de l'API Lookup peuvent implémenter.

Vérification des URL

Cette section contient des spécifications détaillées sur la façon dont les clients vérifient les URL.

Mise en forme canonique des URL

Avant de vérifier une URL, le client doit effectuer une mise en forme canonique sur cette URL.

Pour commencer, nous partons du principe que le client a analysé l'URL et l'a rendue valide conformément à la norme RFC 2396. Si l'URL utilise un nom de domaine internationalisé (IDN), le client doit la convertir en représentation Punycode ASCII. L'URL doit inclure un composant de chemin, c'est-à-dire qu'elle doit comporter au moins une barre oblique après le domaine (http://google.com/ au lieu de http://google.com).

Tout d'abord, supprimez de l'URL les caractères de tabulation (0x09), CR (0x0d) et LF (0x0a). Ne supprimez pas les séquences d'échappement pour ces caractères (par exemple, %0a).

Ensuite, si l'URL se termine par un fragment, supprimez-le. Par exemple, remplacez http://google.com/#frag par http://google.com/.

Troisièmement, supprimez plusieurs caractères d'échappement avec le signe "%" jusqu'à ce qu'il n'y ait plus d'échappements avec le signe "%" dans l'URL. (L'URL risque d'être non valide.)

Pour définir l'URL canonique du nom d'hôte:

Extrayez le nom d'hôte de l'URL, puis procédez comme suit :

1. Supprimez tous les points au début et à la fin.
2. Remplacez les points consécutifs par un seul point.
3. Si le nom d'hôte peut être analysé en tant qu'adresse IPv4, normalisez-le en 4 valeurs décimales séparées par des points. Le client doit gérer tout encodage des adresses IP légales, y compris les composants octal, hexadécimal et moins de quatre.
4. Si le nom d'hôte peut être analysé en tant qu'adresse IPv6 entre crochets, normalisez-le en supprimant les zéros inutiles au début des composants et en réduisant les composants 0 à l'aide de la syntaxe des doubles deux-points. Par exemple, [2001:0db8:0000::1] doit être transformé en [2001:db8::1]. Si le nom d'hôte fait partie de l'un des deux types d'adresses IPv6 spéciaux suivants, transformez-le en IPv4 :
   • Une adresse IPv6 mappée à l'IPv4, telle que [::ffff:1.2.3.4], qui doit être transformée en 1.2.3.4 ;
   • Une adresse NAT64 utilisant le préfixe connu 64:ff9b::/96, tel que [64:ff9b::1.2.3.4], qui doit être transformé en 1.2.3.4.
5. Mettre la chaîne en minuscules.

Pour définir l'URL canonique du chemin d'accès:

1. Résolvez les séquences /../ et /./ dans le chemin en remplaçant /./ par / et en supprimant /../ ainsi que le composant de chemin précédent.
2. Remplacez les séries de barres obliques consécutives par une seule barre oblique.

N'appliquez pas ces méthodes de mise en forme canonique du chemin aux paramètres de requête.

Dans l'URL, utilisez la touche d'échappement "%" pour tous les caractères <= ASCII 32, >= 127, # ou %. Les échappements doivent utiliser des caractères hexadécimaux en majuscules.

Expressions de préfixe de chemin d'hôte-suffixe

Une fois l'URL canonique, l'étape suivante consiste à créer les expressions de suffixe/préfixe. Chaque expression de suffixe/préfixe se compose d'un suffixe d'hôte (ou d'un hôte complet) et d'un préfixe de chemin (ou chemin d'accès complet).

Le client créera jusqu'à 30 combinaisons possibles de suffixe d'hôte et de préfixe de chemin d'accès. Ces combinaisons n'utilisent que les composants d'hôte et de chemin d'accès de l'URL. Le schéma, le nom d'utilisateur, le mot de passe et le port sont supprimés. Si l'URL inclut des paramètres de requête, au moins une combinaison inclut le chemin d'accès complet et les paramètres de requête.

Pour l'hôte, le client essaie au maximum cinq chaînes différentes. Les voici :

• Si le nom d'hôte n'est pas un littéral IPv4 ou IPv6, jusqu'à quatre noms d'hôte formés en commençant par le domaine eTLD+1 et en ajoutant des composants de tête successifs. Pour déterminer l'eTLD+1, vous devez vous baser sur la liste des suffixes publics. Par exemple, a.b.example.com donne le domaine eTLD+1 de example.com, ainsi que l'hôte avec un composant hôte supplémentaire b.example.com.
• Le nom d'hôte exact dans l'URL. Pour reprendre l'exemple précédent, a.b.example.com serait vérifié.

Pour le chemin, le client essaie au maximum six chaînes différentes. À savoir :

• Le chemin d'accès exact de l'URL, y compris les paramètres de requête.
• Le chemin d'accès exact de l'URL, sans paramètres de requête.
• Quatre chemins formés en commençant à la racine (/) et en ajoutant successivement des composants de chemin, y compris une barre oblique finale.

Les exemples suivants illustrent le comportement de la vérification :

Pour l'URL http://a.b.com/1/2.html?param=1, le client essaie les chaînes possibles suivantes :

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/

Pour l'URL http://a.b.c.d.e.f.com/1.html, le client essaie les chaînes possibles suivantes :

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/

(Remarque: ignorez b.c.d.e.f.com, car seuls les cinq derniers composants de nom d'hôte et le nom d'hôte complet seront pris en compte.)

Pour l'URL http://1.2.3.4/1/, le client essaie les chaînes possibles suivantes :

1.2.3.4/1/
1.2.3.4/

Pour l'URL http://example.co.uk/1, le client essaie les chaînes possibles suivantes :

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

Hachage

La navigation sécurisée Google utilise exclusivement SHA256 comme fonction de hachage. Cette fonction de hachage doit être appliquée aux expressions ci-dessus.

Le hachage complet de 32 octets sera, selon les circonstances, tronqué à 4 octets, 8 octets ou 16 octets:

• Lorsque vous utilisez la méthode hashes.search, nous exigeons actuellement que les hachages de la requête soient tronqués à exactement 4 octets. L'envoi d'octets supplémentaires dans cette requête compromet la confidentialité de l'utilisateur.

• Lorsque vous téléchargez les listes pour la base de données locale à l'aide de la méthode hashList.get ou de la méthode hashLists.batchGet, la longueur des hachages envoyés par le serveur est influencée à la fois par la nature de la liste et par la préférence du client concernant la longueur de hachage, communiquée par le paramètre desired_hash_length.

Procédure de vérification des URL en temps réel

Cette procédure est utilisée lorsque le client choisit le mode de fonctionnement en temps réel.

Cette procédure prend une seule URL u et renvoie SAFE, UNSAFE ou UNSURE. Si la valeur SAFE est renvoyée, l'URL est considérée comme sécurisée par la navigation sécurisée Google. Si la valeur UNSAFE est renvoyée, l'URL est considérée comme potentiellement dangereuse par la navigation sécurisée Google. Vous devez alors prendre les mesures appropriées, par exemple afficher un avertissement à l'utilisateur final, déplacer un message reçu dans le dossier de spam ou exiger une confirmation supplémentaire de la part de l'utilisateur avant de continuer. Si la valeur UNSURE est renvoyée, la procédure de vérification locale suivante doit ensuite être utilisée.

1. Soit expressions, une liste d'expressions de suffixe/préfixe générée par l'URL u.
2. Supposons que expressionHashes soit une liste, où les éléments sont des hachages SHA256 de chaque expression figurant dans expressions.
3. Pour chaque hash de expressionHashes :
   1. Si hash se trouve dans le cache global, renvoyez UNSURE.
4. Supposons que expressionHashPrefixes soit une liste, où les éléments correspondent aux quatre premiers octets de chaque hachage dans expressionHashes.
5. Pour chaque expressionHashPrefix de expressionHashPrefixes :
   1. Recherchez expressionHashPrefix dans le cache local.
   2. Si l'entrée mise en cache est trouvée :
      1. Déterminez si l'heure actuelle est postérieure à sa date d'expiration.
      2. Si elle est supérieure :
         1. Supprimez l'entrée mise en cache trouvée du cache local.
         2. Continuez avec la boucle.
      3. Si elle n'est pas supérieure :
         1. Supprimer ce expressionHashPrefix spécifique de expressionHashPrefixes.
         2. Vérifiez si le hachage complet correspondant dans expressionHashes est trouvé dans l'entrée mise en cache.
         3. Si vous le trouvez, renvoyez UNSAFE.
         4. Si vous ne le trouvez pas, poursuivez avec la boucle.
   3. Si l'entrée mise en cache est introuvable, poursuivez avec la boucle.
6. Envoyez expressionHashPrefixes au serveur de navigation sécurisée Google v5 à l'aide de RPC SearchHashes ou de la méthode REST hashes.search. Si une erreur s'est produite (erreurs réseau, erreurs HTTP, etc.), renvoyez UNSURE. Sinon, la réponse sera le response reçu du serveur SB, qui est une liste de hachages complets accompagnés de quelques informations auxiliaires identifiant la nature de la menace (ingénierie sociale, logiciels malveillants, etc.), ainsi que le délai d'expiration du cache expiration.
7. Pour chaque fullHash de response :
   1. Insérez fullHash dans le cache local, avec expiration.
8. Pour chaque fullHash de response :
   1. Soit isFound le résultat de la recherche de fullHash dans expressionHashes.
   2. Si isFound est défini sur "False", poursuivez la lecture en boucle.
   3. Si isFound est défini sur "True", renvoyez UNSAFE.
9. Renvoyez SAFE.

Procédure de vérification des URL de la liste LocalThreat List

Cette procédure est utilisée lorsque le client choisit le mode de fonctionnement de la liste locale. Il est également utilisé lorsque la procédure RealTimeCheck ci-dessus renvoie la valeur UNSURE au client.

Cette procédure prend une seule URL u et renvoie SAFE ou UNSAFE.

1. Soit expressions, une liste d'expressions de suffixe/préfixe générée par l'URL u.
2. Supposons que expressionHashes soit une liste, où les éléments sont des hachages SHA256 de chaque expression figurant dans expressions.
3. Supposons que expressionHashPrefixes soit une liste, où les éléments correspondent aux quatre premiers octets de chaque hachage dans expressionHashes.
4. Pour chaque expressionHashPrefix de expressionHashPrefixes :
   1. Recherchez expressionHashPrefix dans le cache local.
   2. Si l'entrée mise en cache est trouvée :
      1. Déterminez si l'heure actuelle est postérieure à sa date d'expiration.
      2. Si elle est supérieure :
         1. Supprimez l'entrée mise en cache trouvée du cache local.
         2. Continuez avec la boucle.
      3. Si elle n'est pas supérieure :
         1. Supprimer ce expressionHashPrefix spécifique de expressionHashPrefixes.
         2. Vérifiez si le hachage complet correspondant dans expressionHashes est trouvé dans l'entrée mise en cache.
         3. Si vous le trouvez, renvoyez UNSAFE.
         4. Si vous ne le trouvez pas, poursuivez avec la boucle.
   3. Si l'entrée mise en cache est introuvable, poursuivez avec la boucle.
5. Pour chaque expressionHashPrefix de expressionHashPrefixes :
   1. Recherchez expressionHashPrefix dans la base de données de la liste des menaces locale.
   2. Si le expressionHashPrefix est introuvable dans la base de données de la liste des menaces locale, supprimez-le de expressionHashPrefixes.
6. Envoyez expressionHashPrefixes au serveur de navigation sécurisée Google v5 à l'aide de RPC SearchHashes ou de la méthode REST hashes.search. Si une erreur s'est produite (erreurs réseau, erreurs HTTP, etc.), renvoyez SAFE. Sinon, la réponse sera le response reçu du serveur SB, qui est une liste de hachages complets accompagnés de quelques informations auxiliaires identifiant la nature de la menace (ingénierie sociale, logiciels malveillants, etc.), ainsi que le délai d'expiration du cache expiration.
7. Pour chaque fullHash de response :
   1. Insérez fullHash dans le cache local, avec expiration.
8. Pour chaque fullHash de response :
   1. Soit isFound le résultat de la recherche de fullHash dans expressionHashes.
   2. Si isFound est défini sur "False", poursuivez la lecture en boucle.
   3. Si isFound est défini sur "True", renvoyez UNSAFE.
9. Renvoyez SAFE.

Procédure de vérification des URL en temps réel sans base de données locale

Cette procédure est utilisée lorsque le client choisit le mode de fonctionnement en temps réel sans stockage.

Cette procédure prend une seule URL u et renvoie SAFE ou UNSAFE.

1. Soit expressions, une liste d'expressions de suffixe/préfixe générée par l'URL u.
2. Supposons que expressionHashes soit une liste, où les éléments sont des hachages SHA256 de chaque expression figurant dans expressions.
3. Supposons que expressionHashPrefixes soit une liste, où les éléments correspondent aux quatre premiers octets de chaque hachage dans expressionHashes.
4. Pour chaque expressionHashPrefix de expressionHashPrefixes :
   1. Recherchez expressionHashPrefix dans le cache local.
   2. Si l'entrée mise en cache est trouvée :
      1. Déterminez si l'heure actuelle est postérieure à sa date d'expiration.
      2. Si elle est supérieure :
         1. Supprimez l'entrée mise en cache trouvée du cache local.
         2. Continuez avec la boucle.
      3. Si elle n'est pas supérieure :
         1. Supprimer ce expressionHashPrefix spécifique de expressionHashPrefixes.
         2. Vérifiez si le hachage complet correspondant dans expressionHashes est trouvé dans l'entrée mise en cache.
         3. Si vous le trouvez, renvoyez UNSAFE.
         4. Si vous ne le trouvez pas, poursuivez avec la boucle.
   3. Si l'entrée mise en cache est introuvable, poursuivez avec la boucle.
5. Envoyez expressionHashPrefixes au serveur de navigation sécurisée Google v5 à l'aide de RPC SearchHashes ou de la méthode REST hashes.search. Si une erreur s'est produite (erreurs réseau, erreurs HTTP, etc.), renvoyez SAFE. Sinon, la réponse sera le response reçu du serveur SB, qui est une liste de hachages complets accompagnés de quelques informations auxiliaires identifiant la nature de la menace (ingénierie sociale, logiciels malveillants, etc.), ainsi que le délai d'expiration du cache expiration.
6. Pour chaque fullHash de response :
   1. Insérez fullHash dans le cache local, avec expiration.
7. Pour chaque fullHash de response :
   1. Soit isFound le résultat de la recherche de fullHash dans expressionHashes.
   2. Si isFound est défini sur "False", poursuivez la lecture en boucle.
   3. Si isFound est défini sur "True", renvoyez UNSAFE.
8. Renvoyez SAFE.

Maintenance de la base de données locale

Dans la version 5 de la navigation sécurisée Google, le client doit gérer une base de données locale, sauf lorsqu'il choisit le mode en temps réel sans stockage. C'est au client de déterminer le format et le stockage de cette base de données locale. D'un point de vue conceptuel, le contenu de cette base de données locale peut être considéré comme un dossier contenant diverses listes en tant que fichiers. Ces fichiers contiennent des hachages SHA256 ou des préfixes de hachage.

Mises à jour des bases de données

Le client appelle régulièrement la méthode hashList.get ou la méthode hashLists.batchGet pour mettre à jour la base de données. Comme un client standard souhaite mettre à jour plusieurs listes à la fois, il est recommandé d'utiliser la méthode hashLists.batchGet.

Les listes sont identifiées par des noms distincts. Les noms sont de courtes chaînes ASCII de quelques caractères.

Contrairement à V4, où les listes sont identifiées par le tuple par type de menace, type de plate-forme et type d'entrée de menace, dans v5, les listes sont simplement identifiées par nom. Vous bénéficiez ainsi de plus de flexibilité lorsque plusieurs listes de la version 5 peuvent partager le même type de menace. Les types de plates-formes et d'entrées de menaces sont supprimés dans la version 5.

Une fois qu'un nom a été choisi pour une liste, il ne sera jamais renommé. En outre, lorsqu'une liste apparaît, elle n'est jamais supprimée (si la liste n'est plus utile, elle devient vide, mais continue d'exister). Par conséquent, il est approprié de coder ces noms en dur dans le code client de la navigation sécurisée Google.

Les méthodes hashList.get et hashLists.batchGet acceptent les mises à jour incrémentielles. Les mises à jour incrémentielles permettent d'économiser de la bande passante et d'améliorer les performances. Les mises à jour incrémentielles fonctionnent en générant un delta entre la version du client de la liste et la dernière version de la liste. (Si un client vient d'être déployé et qu'aucune version n'est disponible, une mise à jour complète est disponible.) La mise à jour incrémentielle contient des index de suppression et des ajouts. Le client doit d'abord supprimer de sa base de données locale les entrées correspondant aux index spécifiés, puis appliquer les ajouts.

Enfin, pour éviter toute corruption, le client doit comparer les données stockées à la somme de contrôle fournie par le serveur. Chaque fois que la somme de contrôle ne correspond pas, le client doit effectuer une mise à jour complète.

Décoder le contenu de la liste

Toutes les listes sont envoyées à l'aide d'un encodage spécial afin de réduire leur taille. Cet encodage tient compte du fait que les listes de la navigation sécurisée Google contiennent conceptuellement un ensemble de hachages ou de préfixes de hachage qui ne peuvent pas être distingués d'un point de vue statistique des entiers aléatoires. Si nous triions ces nombres entiers et que nous prenions la différence adjacente, cette différence adjacente devrait être, en quelque sorte, "petite". L'encodage Golomb-Rice exploite ensuite cette petite taille.

La navigation sécurisée Google version 5 propose quatre types distincts pour traiter les données de 4, 8, 16 et 32 octets. Examinons un exemple dans lequel trois entiers numériques consécutifs de 4 octets sont encodés. Choisissez la valeur 3 pour le paramètre Rice, désigné par k. La partie du quotient de l'encodage est simplement la valeur de différence adjacente décalée de k bits vers la droite. Puisque les entiers donnés sont consécutifs, leur différence adjacente est de 1. Après un décalage de 3 bits, la partie du quotient est égale à zéro. Les k bits les moins significatifs sont 001. Le quotient nul est encodé sous la forme d'un seul bit de 0. Le reste est de 1 et encodé sous la forme 100. Cette opération est répétée de nouveau pour former le flux de bits 01000100. Le flux de bits obtenu est encodé à l'aide de Little Endian sous la forme 00100010. Par conséquent, elle correspond aux données suivantes:

rice_parameter: 3
entries_count: 2
encoded_data: "\x22"

Après l'étape de décodage ci-dessus pour les entiers 32 bits, le résultat est directement utilisable comme index de suppression ou ajouts. Contrairement à la version 4, il n'est pas nécessaire d'effectuer un échange d'octets par la suite.

Listes disponibles

Les listes suivantes sont recommandées pour une utilisation dans v5alpha1:

Nom de la liste	Énumération ThreatType correspondante de la version 4	Description
gc	Aucun	Il s'agit d'une liste de cache globale. Il s'agit d'une liste spéciale utilisée uniquement en mode Temps réel.
se	SOCIAL_ENGINEERING	Cette liste contient les menaces de type SOCIAL_ENGINEERING.
mw	MALWARE	Cette liste contient les menaces du type MALWARE pour les plates-formes de bureau.
uws	UNWANTED_SOFTWARE	Cette liste contient les menaces de type UNWANTED_SOFTWARE pour les plates-formes de bureau.
uwsa	UNWANTED_SOFTWARE	Cette liste contient les menaces de type UNWANTED_SOFTWARE pour les plates-formes Android.
pha	POTENTIALLY_HARMFUL_APPLICATION	Cette liste contient les menaces de type POTENTIALLY_HARMFUL_APPLICATION pour les plates-formes Android.

D'autres listes seront disponibles ultérieurement, après quoi le tableau ci-dessus sera développé.

Fréquence de mise à jour

Le client doit inspecter la valeur renvoyée par le serveur dans le champ minimum_wait_duration et s'en servir pour planifier la prochaine mise à jour de la base de données. Cette valeur peut être nulle, auquel cas le client doit immédiatement effectuer une autre mise à jour.

Exemples de requête

Cette section présente quelques exemples d'utilisation directe de l'API HTTP pour accéder à la navigation sécurisée Google. Il est généralement recommandé d'utiliser une liaison de langue générée, car elle gère automatiquement l'encodage et le décodage de manière pratique. Veuillez consulter la documentation concernant cette liaison.

Voici un exemple de requête HTTP utilisant la méthode hashes.search:

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

Le corps de la réponse est une charge utile au format Protocol-Buffer que vous pouvez ensuite décoder.

Voici un exemple de requête HTTP utilisant la méthode hashLists.batchGet:

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

Le corps de la réponse est, là encore, une charge utile au format Protocol-Buffer que vous pouvez ensuite décoder.

Guide de migration

Si vous utilisez actuellement l'API Update v4, le processus de migration est simple de la version 4 à la version 5, sans avoir à réinitialiser ni à effacer la base de données locale. Cette section explique comment procéder.

Conversion des mises à jour de liste

Dans la version 4, vous deviez utiliser la méthodethreatListUpdates.fetch pour télécharger les listes. Dans la version 5, vous passeriez à la méthode hashLists.batchGet.

Les modifications suivantes doivent être apportées à la demande:

1. Supprimez l'objet ClientInfo v4. Au lieu de fournir l'identification d'un client à l'aide d'un champ dédié, utilisez simplement l'en-tête User-Agent bien connu. Bien qu'aucun format ne soit prescrit pour fournir l'identification du client dans cet en-tête, nous vous suggérons de simplement inclure l'ID client d'origine et la version du client en les séparant par un espace ou une barre oblique.
2. Pour chaque objet ListUpdateRequest v4 :
   • Recherchez le nom de la liste de la version 5 correspondante dans le tableau ci-dessus et indiquez-le dans la requête de la version 5.
   • Supprimez les champs inutiles tels que threat_entry_type ou platform_type.
   • Dans la version 4, le champ state est directement compatible avec le champ versions de la version 5. La même chaîne d'octets qui serait envoyée au serveur à l'aide du champ state dans la version 4 peut simplement être envoyée dans la version 5 à l'aide du champ versions.
   • Pour les contraintes de la version 4, la version 5 utilise une version simplifiée appelée SizeConstraints. Les champs supplémentaires, comme region, doivent être supprimés.

Les modifications suivantes doivent être apportées à la réponse:

1. L'énumération ResponseType v4 est simplement remplacée par un champ booléen nommé partial_update.
2. Le champ minimum_wait_duration peut désormais être égal à zéro ou omis. Si c'est le cas, le client est invité à effectuer immédiatement une autre requête. Cela ne se produit que lorsque le client spécifie dans SizeConstraints une contrainte inférieure à la taille maximale de mise à jour de la taille de mise à jour.
3. L'algorithme de décodage Rice pour les entiers 32 bits devra être ajusté. La différence réside dans le fait que les données encodées sont encodées avec une terminaison différente. Dans les versions 4 et 5, les préfixes de hachage 32 bits sont triés par ordre lexicographique. Toutefois, dans la version 4, ces préfixes sont traités comme en quasi-totalité lors du tri, tandis que dans la version 5, ils sont traités comme en big endian lorsqu'ils sont triés. Cela signifie que le client n'a pas besoin d'effectuer de tri, car le tri lexicographique est identique au tri numérique avec big endian. Pour consulter un exemple de ce type dans l'implémentation de la version 4 de Chromium, cliquez ici. Ce tri peut être supprimé.
4. L'algorithme de décodage Rice devra être implémenté pour les autres longueurs de hachage.

Conversion des recherches de hachage

Dans la version 4, il était nécessaire d'utiliser la méthode fullHashes.find pour obtenir le hachage complet. Dans la version 5, la méthode équivalente est la méthode hashes.search.

Les modifications suivantes doivent être apportées à la demande:

1. Structurez le code de manière à n'envoyer que des préfixes de hachage d'une longueur exacte de 4 octets.
2. Supprimez la totalité des objets ClientInfo de la version 4. Au lieu de fournir l'identification d'un client à l'aide d'un champ dédié, utilisez simplement l'en-tête User-Agent bien connu. Bien qu'aucun format ne soit prescrit pour fournir l'identification du client dans cet en-tête, nous vous suggérons de simplement inclure l'ID client d'origine et la version du client en les séparant par un espace ou une barre oblique.
3. Supprimez le champ client_states. qui n'était plus nécessaire.
4. Il n'est plus nécessaire d'inclure threat_types et des champs similaires.

Les modifications suivantes doivent être apportées à la réponse:

1. Le champ minimum_wait_duration a été supprimé. Le client peut toujours émettre une nouvelle demande au besoin.
2. L'objet ThreatMatch v4 a été simplifié dans l'objet FullHash.
3. La mise en cache a été simplifiée avec une durée de cache unique. Consultez les procédures ci-dessus pour interagir avec le cache.