Overview

Introduction

Remarque: Cette documentation est en cours de développement. Nous prévoyons des améliorations dans un avenir proche.

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 principaux changements 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 surcouche. De plus, la version 5 de la navigation sécurisée Google est conçue pour faciliter la migration depuis la version 4.

Actuellement, les versions 4 et 5 de Google sont considérées comme prêtes pour la production. Vous pouvez utiliser la version 4 ou la version 5. Nous n'avons pas encore annoncé de date d'abandon de la version 4. Dans ce cas, nous vous préviendrons au moins un an à l'avance. Cette page décrit la version 5 et propose un guide de migration de la version 4 à la version 5. La documentation complète de la version 4 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 protection manquée. Dans la version 4, il faut 20 à 50 minutes à un client type pour obtenir la version la plus récente des listes de menaces. Malheureusement, les attaques par hameçonnage se propagent rapidement: depuis 2021, 60% des sites qui utilisent des méthodes d'attaque durent moins de 10 minutes. D'après nos analyses, entre 25 et 30% des cas de protection contre l'hameçonnage manquants sont dus à l'obsolescence des données. De plus, certains appareils ne sont pas équipés pour gérer l'intégralité des listes de menaces associées à la navigation sécurisée Google, qui continuent de croître 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 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 de préfixe partielle, envoyer 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 désormais télécharger une liste de sites potentiellement inoffensifs (appelée Global Cache), effectuer une vérification locale de ce cache global ainsi qu'une vérification locale de la liste des menaces. Enfin, lorsqu'il y a une correspondance partielle de préfixe pour les listes de menaces ou une absence de correspondance dans le cache global, effectuez une requête pour télécharger les hachages complets. Pour plus d'informations sur le traitement local requis par le client, veuillez consulter la procédure ci-dessous. Cela représente un passage de l'autorisation par défaut à l'activation par défaut, ce qui peut améliorer la protection compte tenu de la propagation plus rapide des menaces sur le Web. En d'autres termes, ce protocole est conçu pour offrir une protection en temps quasi réel: notre objectif est de permettre à nos clients de bénéficier de données de navigation sécurisée Google plus récentes.

Confidentialité IP

La navigation sécurisée Google (v4 ou v5) ne traite aucune donnée associée à l'identité d'un utilisateur lors du traitement des requêtes. S'ils sont envoyés, les cookies sont ignorés. Google connaît les adresses IP d'origine des requêtes, mais Google n'utilise les adresses IP que pour les besoins réseau essentiels (c'est-à-dire pour l'envoi de réponses) et à des fins anti-DoS.

Parallèlement à la version 5, nous lançons une API associée appelée API Safe Browsing Oblivious HTTP Gateway. Ce protocole utilise le protocole Oblivious HTTP pour masquer les adresses IP des utilisateurs finaux à Google. Pour ce faire, un tiers non coopératif traite une version chiffrée de la requête de l'utilisateur, puis la transmet à 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 exploite un relais HTTP Oblivious (tel que ce service proposé par Fastly), et Google exploite la passerelle HTTP Oblivious. Il s'agit d'une API associée facultative. Lorsque cette fonctionnalité est utilisée en conjonction 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 uniquement à un usage non commercial (autrement dit, ne doit pas être utilisée à des fins de vente ou de 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 lorsqu'ils activent l'API Safe Browsing. Vous pouvez consulter la répartition et l'utilisation actuelles dans la Google Developers Console. Si vous pensez que vous dépasserez le quota actuellement alloué, vous pouvez demander un quota supplémentaire dans l'interface des quotas de la Play Console. Nous examinons ces demandes et nous demandons à ce que les personnes concernées soient informées lorsque vous demandez une augmentation de quota afin de nous assurer que la disponibilité de nos services 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 s'affichent 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 initiée par JavaScript). Ces URL de sous-ressources ne doivent pas être comparées à la navigation sécurisée Google.

Si la visite d'une URL entraîne une redirection (telle que le code HTTP 301), il est normal qu'elle soit comparée à la navigation sécurisée Google. La manipulation d'URL côté client comme History.pushState n'entraîne pas la vérification des nouvelles URL par rapport à 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 contribuent à vous protéger, vous et Google, des malentendus en indiquant clairement que la page n'est pas connue avec certitude comme une ressource Web non sécurisée, et que les avertissements se contentent d'identifier un risque potentiel.

• Dans votre avertissement visible par l'utilisateur, vous ne devez pas faire croire aux utilisateurs que la page en question est, sans aucun doute, une ressource Web non sécurisée. Lorsque vous faites référence à la page identifiée ou aux risques potentiels qu'elle peut présenter aux utilisateurs, vous devez qualifier l'avertissement en utilisant des termes tels que "suspicion, potentiel, possible, probable.
• Votre mise en garde doit permettre à l'utilisateur d'obtenir plus d'informations sur la définition des différentes menaces établie par Google. 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 présentant un risque par le service de navigation sécurisée, vous devez en attribuer la paternité à 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 indiquer qu'il existe un risque de faux positifs (sites à risque 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'erreurs. En effet, certains sites à risque peuvent ne pas être identifiés et certains sites sûrs peuvent être identifiés par erreur.

Modes de fonctionnement

La version 5 de la navigation sécurisée Google permet aux clients de choisir entre 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 temps réel, ils conservent dans leur base de données locale: (i) un cache global de sites potentiellement inoffensifs au format SHA256 des expressions d'URL de suffixe d'hôte ou de préfixe de chemin ; (ii) un ensemble de listes de menaces au format de préfixes de hachage SHA256 d'expressions d'URL de suffixe d'hôte ou de préfixe de chemin. L'idée générale 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 locale des listes des menaces est effectuée. Sinon, le client poursuit 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. Ce cache local n'a pas besoin d'être stocké dans un espace de stockage persistant et peut être vidé si la mémoire est trop sollicitée.

Une spécification détaillée de la procédure est disponible ci-dessous.

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 la version 4 de l'API Update, sauf qu'ils utilisent 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 au format de préfixes de hachage SHA256 d'expressions d'URL de suffixe d'hôte/préfixe de chemin. Chaque fois que le client souhaite vérifier une URL spécifique, une vérification est effectuée à l'aide de la liste des menaces locales. Si et seulement si une correspondance est trouvée, le client se connecte au serveur pour poursuivre la vérification.

Comme précédemment, le client conservera également un cache local qui n'a pas besoin d'être stocké 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 temps réel sans espace de stockage, ils n'ont pas besoin de gérer de base de données locale persistante. Toutefois, le client doit toujours gérer un cache local. Ce cache local n'a pas besoin d'être stocké dans un espace de stockage persistant et peut être vidé si la mémoire est trop sollicitée.

Chaque fois que le client souhaite vérifier une URL en particulier, il se connecte toujours au serveur pour effectuer une vérification. Ce mode est semblable à ce que les clients de l'API Lookup version 4 peuvent implémenter.

Par rapport au mode Temps réel, ce mode peut utiliser davantage de bande passante réseau, mais peut être plus adapté s'il n'est pas pratique pour le client de maintenir un état local persistant.

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 supposons 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 convertir l'URL en représentation ASCII Punycode. L'URL doit inclure un composant de chemin d'accès, 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).

Commencez par supprimer les caractères de tabulation (0x09), de RS (0x0d) et de gauche (0x0a) de l'URL. Ne supprimez pas les séquences d'échappement de ces caractères (par exemple, %0a).

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

Troisièmement, supprimez les échappements de type "%" de manière répétée jusqu'à ce qu'il n'y ait plus aucun échappement "%-échappement". (L'URL risque alors de ne pas être valide.)

Pour définir le nom d'hôte canonique, procédez comme suit:

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 avec quatre valeurs décimales séparées par un point. Le client doit gérer tout encodage d'adresse IP légal, y compris octal, hexadécimal et moins de quatre composants.
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 zéro à l'aide de la syntaxe du double deux-points. Par exemple, [2001:0db8:0000::1] doit être transformé en [2001:db8::1]. Si le nom d'hôte fait partie des deux types d'adresses IPv6 spéciaux suivants, convertissez-les en IPv4 :
   • Une adresse IPv6 mappée avec 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 bien connu 64:ff9b::/96, telle que [64:ff9b::1.2.3.4], qui doit être transformée en 1.2.3.4.
5. Mettre la chaîne en minuscules.

Pour définir le chemin canonique:

1. Pour résoudre les séquences /../ et /./ du chemin, remplacez /./ par / et supprimez /../ avec 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 l'é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 du suffixe d'hôte

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 d'accès (ou d'un chemin d'accès complet).

Le client peut former jusqu'à 30 combinaisons différentes de suffixe d'hôte et de préfixe de chemin d'accès. Ces combinaisons n'utilisent que les composants 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 comprend des paramètres de requête, alors au moins une combinaison inclura 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. Il s'agit des suivants :

• 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 successivement les composants principaux. La détermination de l'eTLD+1 doit être basée sur la liste des suffixes publics. Par exemple, a.b.example.com générerait 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.
• Les quatre chemins formés en partant de la racine (/) et en ajoutant successivement les 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 nous ne prendrons que les cinq derniers composants du nom d'hôte, ainsi que le nom d'hôte complet.)

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 n'utilise que la fonction de hachage SHA256. Cette fonction de hachage doit être appliquée aux expressions ci-dessus.

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

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

• Lors du téléchargement des listes pour la base de données locale à l'aide des méthodes hashList.get ou hashLists.batchGet, la longueur des hachages envoyés par le serveur dépend à la fois de la nature de la liste et de 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 accepte une seule URL u et renvoie SAFE, UNSAFE ou UNSURE. Si la valeur SAFE est renvoyée, la navigation sécurisée Google considère l'URL comme sûre. Si la valeur UNSAFE est renvoyée, l'URL est considérée comme potentiellement dangereuse par la navigation sécurisée Google, et des mesures appropriées doivent être prises, comme afficher un avertissement à l'utilisateur final, déplacer un message reçu dans le dossier de spam ou demander 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 être utilisée après.

1. Soit expressions une liste d'expressions de suffixe/préfixe générées par l'URL u.
2. Soit expressionHashes une liste, dont les éléments sont des hachages SHA256 de chaque expression de expressions.
3. Pour chaque valeur hash de expressionHashes :
   1. Si hash se trouve dans le cache global, renvoyez UNSURE.
4. Soit expressionHashPrefixes une liste, où les éléments correspondent aux quatre premiers octets de chaque hachage dans expressionHashes.
5. Pour chaque valeur 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 du cache local l'entrée en cache trouvée.
         2. Continuez avec la boucle.
      3. Si la valeur n'est pas supérieure :
         1. Supprimez ce expressionHashPrefix de expressionHashPrefixes.
         2. Vérifiez si le hachage complet correspondant dans expressionHashes a été trouvé dans l'entrée mise en cache.
         3. Si vous le trouvez, renvoyez UNSAFE.
         4. Si vous ne le trouvez pas, poursuivez la lecture en boucle.
   3. Si l'entrée mise en cache est introuvable, poursuivez la lecture en boucle.
6. Envoyez expressionHashPrefixes au serveur de navigation sécurisée Google v5 à l'aide de SearchHashes RPC ou de la méthode REST hashes.search. Si une erreur s'est produite (erreurs réseau, erreurs HTTP, etc.), renvoyez UNSURE. Sinon, laissez la réponse response reçue du serveur SB, qui est une liste de hachages complets ainsi que des 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 valeur fullHash de response :
   1. Insérez fullHash dans le cache local, avec expiration.
8. Pour chaque valeur fullHash de response :
   1. Soit isFound le résultat de la recherche de fullHash dans expressionHashes.
   2. Si isFound est défini sur "False", continuez avec la boucle.
   3. Si isFound est "True", renvoyez UNSAFE.
9. Renvoyez SAFE.

Alors que ce protocole spécifie quand le client envoie des expressionHashPrefixes au serveur, il ne spécifie pas intentionnellement comment les envoyer. Par exemple, il est acceptable que le client envoie tous les expressionHashPrefixes dans une seule requête, et qu'il envoie également chaque préfixe individuel de expressionHashPrefixes au serveur dans des requêtes distinctes (éventuellement en parallèle). Le client peut également envoyer des préfixes de hachage sans rapport ou générés de manière aléatoire avec les préfixes de hachage dans expressionHashPrefixes, à condition que le nombre de préfixes de hachage envoyés dans une seule requête ne dépasse pas 30.

Procédure de vérification de l'URL de la liste des menaces locales

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

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

1. Soit expressions une liste d'expressions de suffixe/préfixe générées par l'URL u.
2. Soit expressionHashes une liste, dont les éléments sont des hachages SHA256 de chaque expression de expressions.
3. Soit expressionHashPrefixes une liste, où les éléments correspondent aux quatre premiers octets de chaque hachage dans expressionHashes.
4. Pour chaque valeur 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 du cache local l'entrée en cache trouvée.
         2. Continuez avec la boucle.
      3. Si la valeur n'est pas supérieure :
         1. Supprimez ce expressionHashPrefix de expressionHashPrefixes.
         2. Vérifiez si le hachage complet correspondant dans expressionHashes a été trouvé dans l'entrée mise en cache.
         3. Si vous le trouvez, renvoyez UNSAFE.
         4. Si vous ne le trouvez pas, poursuivez la lecture en boucle.
   3. Si l'entrée mise en cache est introuvable, poursuivez la lecture en boucle.
5. Pour chaque valeur expressionHashPrefix de expressionHashPrefixes :
   1. Recherchez expressionHashPrefix dans la base de données locale de la liste des menaces.
   2. Si le expressionHashPrefix est introuvable dans la base de données locale de la liste des menaces, supprimez-le de expressionHashPrefixes.
6. Envoyez expressionHashPrefixes au serveur de navigation sécurisée Google v5 à l'aide de SearchHashes RPC ou de la méthode REST hashes.search. Si une erreur s'est produite (erreurs réseau, erreurs HTTP, etc.), renvoyez SAFE. Sinon, laissez la réponse response reçue du serveur SB, qui est une liste de hachages complets ainsi que des 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 valeur fullHash de response :
   1. Insérez fullHash dans le cache local, avec expiration.
8. Pour chaque valeur fullHash de response :
   1. Soit isFound le résultat de la recherche de fullHash dans expressionHashes.
   2. Si isFound est défini sur "False", continuez avec la boucle.
   3. Si isFound est "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 utilise une seule URL u et renvoie SAFE ou UNSAFE.

1. Soit expressions une liste d'expressions de suffixe/préfixe générées par l'URL u.
2. Soit expressionHashes une liste, dont les éléments sont des hachages SHA256 de chaque expression de expressions.
3. Soit expressionHashPrefixes une liste, où les éléments correspondent aux quatre premiers octets de chaque hachage dans expressionHashes.
4. Pour chaque valeur 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 du cache local l'entrée en cache trouvée.
         2. Continuez avec la boucle.
      3. Si la valeur n'est pas supérieure :
         1. Supprimez ce expressionHashPrefix de expressionHashPrefixes.
         2. Vérifiez si le hachage complet correspondant dans expressionHashes a été trouvé dans l'entrée mise en cache.
         3. Si vous le trouvez, renvoyez UNSAFE.
         4. Si vous ne le trouvez pas, poursuivez la lecture en boucle.
   3. Si l'entrée mise en cache est introuvable, poursuivez la lecture en boucle.
5. Envoyez expressionHashPrefixes au serveur de navigation sécurisée Google v5 à l'aide de SearchHashes RPC ou de la méthode REST hashes.search. Si une erreur s'est produite (erreurs réseau, erreurs HTTP, etc.), renvoyez SAFE. Sinon, laissez la réponse response reçue du serveur SB, qui est une liste de hachages complets ainsi que des 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 valeur fullHash de response :
   1. Insérez fullHash dans le cache local, avec expiration.
7. Pour chaque valeur fullHash de response :
   1. Soit isFound le résultat de la recherche de fullHash dans expressionHashes.
   2. Si isFound est défini sur "False", continuez avec la boucle.
   3. Si isFound est "True", renvoyez UNSAFE.
8. Renvoyez SAFE.

Tout comme la procédure de vérification des URL en temps réel, cette procédure ne précise pas exactement comment envoyer les préfixes de hachage au serveur. Par exemple, il est acceptable que le client envoie tous les expressionHashPrefixes dans une seule requête, et qu'il envoie également chaque préfixe individuel de expressionHashPrefixes au serveur dans des requêtes distinctes (éventuellement en parallèle). Le client peut également envoyer des préfixes de hachage sans rapport ou générés de manière aléatoire avec les préfixes de hachage dans expressionHashPrefixes, à condition que le nombre de préfixes de hachage envoyés dans une seule requête ne dépasse pas 30.

Maintenance de la base de données locale

Avec la version 5 de la navigation sécurisée Google, le client est censé gérer une base de données locale, sauf s'il choisit le mode Sans stockage en temps réel. Il revient au client du format et du stockage de cette base de données locale. Le contenu de cette base de données locale peut être considéré comme un dossier contenant différentes listes sous la forme de fichiers, et ces fichiers sont des hachages SHA256 ou des préfixes de hachage.

Mises à jour de la base de données

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

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

Dans la version 4, les listes sont identifiées par le tuple type, type de plate-forme et type d'entrée de menace. Dans la version 5, les listes sont simplement identifiées par leur nom. Cela offre une certaine flexibilité lorsque plusieurs listes v5 peuvent partager le même type de menace. Les types de plates-formes et les types d'entrées de menaces sont supprimés dans la version 5.

Dès lors qu'un nom est attribué à une liste, il n'est jamais renommé. En outre, une fois qu'une liste a été affichée, elle n'est jamais supprimée (si la liste n'est plus utile, elle est 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. L'utilisation de mises à jour incrémentielles permet d'économiser 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 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 les entrées des index spécifiés de sa base de données locale, 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 d'une liste

Décodage des hachages et des préfixes de hachage

Toutes les listes sont transmises à l'aide d'un encodage spécial afin de réduire leur taille. Ce codage fonctionne en reconnaissant que les listes de navigation sécurisée Google contiennent, conceptuellement, un ensemble de hachages ou de préfixes de hachage qui ne sont pas statistiquement différenciés des entiers aléatoires. Si nous trions ces nombres entiers et prenons leur différence adjacente, cette différence adjacente devrait être "petite" en un sens. L'encodage Golomb-Rice, quant à lui, exploite cette petite quantité de données.

Supposons que trois expressions avec préfixe de chemin d'accès au suffixe d'hôte, à savoir a.example.com/, b.example.com/ et y.example.com/, doivent être transmises à l'aide de préfixes de hachage de 4 octets. Supposons également que le paramètre Rice, noté par k, soit choisi sur 30. Le serveur commence par calculer le hachage complet de ces chaînes, qui sont, respectivement:

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

Le serveur forme ensuite des préfixes de hachage de 4 octets pour chacun des éléments ci-dessus, qui correspondent aux 4 premiers octets du hachage complet de 32 octets, interprétés comme des entiers 32 bits en mode big-endian. Le big endiant fait référence au fait que le premier octet du hachage complet devient l’octet le plus significatif de l’entier 32 bits. Cette étape permet d'obtenir les entiers 0x291bc542, 0x1d32c508 et 0xf7a502e5.

Le serveur doit trier ces trois préfixes de hachage de manière lexicographique (ce qui équivaut au tri numérique en big endian). Le résultat du tri est 0x1d32c508, 0x291bc542, 0xf7a502e5. Le premier préfixe de hachage est stocké tel quel dans le champ first_value.

Le serveur calcule ensuite les deux différences adjacentes, respectivement 0xbe9003a et 0xce893da3. Étant donné que k est choisi pour obtenir 30, le serveur divise ces deux nombres en parties de quotient et en parties restantes d'une longueur respective de 2 et 30 bits. Pour le premier nombre, la partie du quotient est zéro et le reste est 0xbe9003a. Pour le deuxième nombre, la partie du quotient est de 3, car les deux bits les plus significatifs sont 11 en binaire et le reste est 0xe893da3. Pour un quotient donné q, il est encodé en (1 << q) - 1 avec exactement 1 + q bits. Le reste est encodé directement à l'aide de k bits. La partie du quotient du premier nombre est encodée sous la forme 0, et la partie restante est exprimée en binaire 00101111101001000000000111010. La partie du quotient du deuxième nombre est encodée sous la forme 0111 et la partie restante est 001110100010010101.

Lorsque ces nombres sont formés en une chaîne d'octets, Little endian est utilisé. Conceptuellement, il peut être plus facile d'imaginer une longue chaîne de bits à partir des bits les moins significatifs: nous prenons la partie du quotient du premier nombre et ajoutons la partie restante du premier nombre au début, puis nous ajoutons la partie du quotient du second nombre au début, puis ajoutons le reste à la partie restante. Vous devriez obtenir le nombre élevé suivant (sauts de ligne et commentaires ajoutés pour plus de clarté):

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

Rédigé en une seule ligne, ce qui serait

00111010001001001111011010001101110010111110100100000000001110100

Évidemment, ce nombre dépasse de loin les 8 bits disponibles dans un seul octet. Le codage Little-Endian prend ensuite les 8 bits les moins significatifs de ce nombre et les produit en tant que premier octet, qui est 01110100. Pour plus de clarté, nous pouvons regrouper la chaîne de bits ci-dessus en groupes de huit bits en commençant par les bits les moins significatifs:

0 01110100 01001001 11101101 00011011 10010111 11010010 00000000 01110100

Le codage Little Endian prend ensuite chaque octet de la droite et le place dans une chaîne d'octets:

01110100
00000000
11010010
10010111
00011011
11101101
01001001
01110100
00000000

Comme vous pouvez le constater, étant donné que nous prepend conceptuellement les nouvelles parties devant le grand nombre à gauche (c'est-à-dire en ajoutant des bits plus importants), mais que nous encoderons à partir de la droite (c'est-à-dire les bits les moins significatifs), l'encodage et le décodage peuvent être effectués de manière incrémentielle.

Cela se traduit enfin par

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

Le client suit simplement les étapes ci-dessus dans l'ordre inverse pour décoder les préfixes de hachage. Contrairement à la version 4, il n'est pas nécessaire d'effectuer un échange d'octets à la fin, car les entiers du préfixe de hachage sont interprétés comme des caractères big-endian.

Décodage des indices de suppression

Les index de suppression sont codés selon la même technique que ci-dessus, à l'aide d'entiers 32 bits. L'encodage et le décodage des index de suppression n'ont pas changé entre les versions v4 et v5.

Listes disponibles

Les listes suivantes sont recommandées pour la version v5alpha1:

Nom de la liste	Énumération ThreatType correspondante v4	Description
gc	Aucun	Cette liste est une liste de cache global. Il s'agit d'une liste spéciale utilisée uniquement en mode de fonctionnement "Temps réel".
se	SOCIAL_ENGINEERING	Cette liste contient les menaces de type SOCIAL_ENGINEERING.
mw	MALWARE	Cette liste contient les menaces de type MALWARE sur les plates-formes de bureau.
uws	UNWANTED_SOFTWARE	Cette liste contient les menaces de type UNWANTED_SOFTWARE sur les plates-formes de bureau.
uwsa	UNWANTED_SOFTWARE	Cette liste contient les menaces de type UNWANTED_SOFTWARE ciblant 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. Le tableau ci-dessus sera alors développé.

Le client est autorisé à faire fonctionner un serveur proxy de mise en cache pour récupérer tout ou partie des listes ci-dessus, puis demander au client de contacter le serveur proxy. Si tel est le cas, nous vous recommandons une courte durée de mise en cache (cinq minutes, par exemple). À l'avenir, cette durée pourra être communiquée à l'aide de l'en-tête HTTP Cache-Control standard.

Fréquence de mise à jour

Le client doit inspecter la valeur renvoyée par le serveur dans le champ minimum_wait_duration et l'utiliser pour planifier la mise à jour suivante de la base de données. Cette valeur peut être égale à zéro (le champ minimum_wait_duration est complètement manquant), auquel cas le client DOIT effectuer immédiatement 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 langage générée, car elle gère automatiquement l'encodage et le décodage d'une 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 de tampon de protocole 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 de tampon de protocole que vous pouvez ensuite décoder.

Guide de migration

Si vous utilisez actuellement l'API Update v4, vous pouvez migrer facilement 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 des listes

Dans la version 4, il fallait utiliser la méthode ThreatListUpdates.fetch pour télécharger des listes. Dans la version 5, il fallait passer à la méthode hashLists.batchGet.

Apportez les modifications suivantes à la requête:

1. Supprimez complètement 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 indiquer l'identification du client dans cet en-tête, nous vous suggérons d'inclure simplement l'ID client d'origine et la version du client séparés par un espace ou une barre oblique.
2. Pour chaque objet ListUpdateRequest v4 :
   • Recherchez le nom de la liste v5 correspondante dans le tableau ci-dessus et indiquez-le dans la requête v5.
   • Supprimez les champs inutiles tels que threat_entry_type ou platform_type.
   • Le champ state de la version 4 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 tels que region doivent être ignorés.

Vous devez apporter les modifications suivantes à la réponse:

1. L'énumération ResponseType de la version 4 est simplement remplacée par un champ booléen nommé partial_update.
2. Le champ minimum_wait_duration peut désormais être nul ou omis. Si c'est le cas, le client est invité à faire immédiatement une autre demande. Cela ne se produit que lorsque le client spécifie dans SizeConstraints une contrainte inférieure à la taille maximale de la base de données sur la taille maximale de mise à jour.
3. L'algorithme de décodage de riz pour les entiers 32 bits devra être ajusté. La différence est que les données encodées sont encodées avec une endianité différente. Dans les versions 4 et 5, les préfixes de hachage 32 bits sont triés de manière lexicographique. Toutefois, dans la version 4, ces préfixes sont traités comme des préfixes de petite-fin lorsqu'ils sont triés, tandis que dans la version 5, ils sont traités comme des préfixes big-endian lorsqu'ils sont triés. Cela signifie que le client n'a pas besoin d'effectuer un tri, car le tri lexicographique est identique au tri numérique avec le big endian. Vous trouverez un exemple de ce type dans l'implémentation de Chromium de la version 4 sur cette page. Ce tri peut être supprimé.
4. L'algorithme de décodage Rice devra être implémenté pour d'autres longueurs de hachage.

Conversion des recherches de hachage

Dans la version 4, il fallait utiliser la méthode fullHashes.find pour obtenir les valeurs de hachage complètes. Dans la version 5, la méthode équivalente est la méthode hashes.search.

Apportez les modifications suivantes à la requête:

1. Structurez le code pour n'envoyer que des préfixes de hachage d'une longueur exactement de 4 octets.
2. Supprimez complètement les objets 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 indiquer l'identification du client dans cet en-tête, nous vous suggérons d'inclure simplement l'ID client d'origine et la version du client séparés 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 les champs similaires.

Vous devez apporter les modifications suivantes à la réponse:

1. Le champ minimum_wait_duration a été supprimé. Le client peut toujours émettre une nouvelle requête selon les besoins.
2. L'objet ThreatMatch v4 a été simplifié en objet FullHash.
3. La mise en cache a été simplifiée en une seule durée de cache. Consultez les procédures ci-dessus pour interagir avec le cache.