Overview

Remarque: Cette documentation est actuellement en cours de développement. Des améliorations seront apportées dans un avenir proche.

La version 5 de la navigation sécurisée Google est une évolution de la version 4. Les deux principaux changements apportés à la version 5 concernent 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 augmenter la flexibilité et l'efficacité, et réduire l'encombrement. De plus, la version 5 de la navigation sécurisée de 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 à 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. Si nous le faisons, nous vous préviendrons au moins un an à l'avance. Cette page décrit la version 5 et un guide de migration de la version 4 vers la version 5. La documentation complète de la version 4 reste disponible.

Fraîcheur des données

Dans la version 5, nous introduisons un mode de fonctionnement appelé "protection en temps réel". Cela évite 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 sur les listes de menaces téléchargées localement, puis, en cas de correspondance partielle du préfixe, envoyer une requête pour télécharger le hachage complet. Dans la version 5, les clients doivent continuer à télécharger et à gérer une base de données locale de listes de menaces, mais ils doivent également télécharger une liste de sites probablement inoffensifs (appelée "Global Cache"), effectuer une vérification locale de ce Global Cache et une vérification locale de la liste de menaces, et enfin, en cas de correspondance partielle du préfixe pour les listes de menaces ou de non-correspondance dans le Global Cache, envoyer une requête pour télécharger les hachages complets. (Pour en savoir plus sur le traitement local requis par le client, veuillez consulter la procédure ci-dessous.) Il s'agit d'un passage de l'autorisation par défaut à la vérification 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, il s'agit d'un protocole conçu pour fournir une protection quasi en temps réel: nous souhaitons que les 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 de Google (versions 4 ou 5) ne traite rien qui soit associé à l'identité d'un utilisateur lors de l'envoi des requêtes. Les cookies, le cas échéant, sont ignorés. Google connaît les adresses IP d'origine des requêtes, mais il ne les utilise que pour des besoins de mise en réseau essentiels (par exemple, pour envoyer des réponses) et à des fins de lutte contre les attaques DoS.

En même temps que la version 5, nous lançons une API associée appelée API Safe Browsing Oblivious HTTP Gateway. Cette méthode utilise HTTP Oblivious pour masquer les adresses IP des utilisateurs finaux à Google. Pour fonctionner, un tiers non complice doit gérer une version chiffrée de la requête de l'utilisateur, puis la transmettre à Google. Le tiers n'a donc 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 transparent (tel que ce service de Fastly), et Google gère la passerelle HTTP transparente. Il s'agit d'une API associée facultative. Lorsqu'il est utilisé avec le service Google Browsing sécurisé, les adresses IP des utilisateurs finaux ne sont plus envoyées à Google.

Modes de fonctionnement

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

Mode "Temps réel"

Lorsque les clients choisissent d'utiliser la version 5 de Google Safe Browsing en mode temps réel, ils gèrent dans leur base de données locale: (i) un cache global de sites probablement inoffensifs, au format de hachages SHA256 d'expressions d'URL de suffixe d'hôte/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/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 des listes de menaces locales est effectuée. Sinon, le client poursuit la vérification du hachage en temps réel, comme indiqué ci-dessous.

En plus de la base de données locale, le client gère un cache local. Un tel cache local n'a pas besoin d'être stocké de manière persistante et peut être effacé en cas de pression sur la mémoire.

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

Mode Liste locale

Lorsque les clients choisissent d'utiliser la version 5 de Google Safe Browsing dans ce mode, leur comportement est semblable à celui de l'API Update v4, à l'exception de l'utilisation de la surface d'API améliorée de la version 5. Les clients gèrent dans leur base de données locale un ensemble de listes de menaces mises en forme sous forme de préfixes de hachage SHA-256 d'expressions d'URL de suffixe d'hôte/de 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 de menaces locale. Si et seulement si une correspondance est établie, le client se connecte au serveur pour poursuivre la vérification.

Comme indiqué ci-dessus, le client gère également un cache local qui n'a pas besoin d'être stocké de manière persistante.

Mode en temps réel sans stockage

Lorsque les clients choisissent d'utiliser la version 5 de la navigation sécurisée Google en mode sans stockage en temps réel, 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. Un tel cache local n'a pas besoin d'être stocké de manière persistante et peut être effacé en cas de pression sur la mémoire.

Chaque fois que le client souhaite vérifier une URL particulière, il se connecte toujours au serveur pour effectuer la vérification. Ce mode est semblable à celui que les clients de l'API Lookup v4 peuvent implémenter.

Par rapport au mode en temps réel, ce mode peut utiliser plus de bande passante réseau, mais il peut être plus adapté si le client ne souhaite pas maintenir un état local persistant.

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 elle renvoie SAFE, l'URL est considérée comme sécurisée par la navigation sécurisée Google. Si la valeur renvoyée est UNSAFE, l'URL est considérée comme potentiellement dangereuse par le Navigateur sécurisé de Google. Des mesures appropriées doivent être prises, par exemple en affichant un avertissement à l'utilisateur final, en déplaçant un message reçu dans le dossier de spam ou en demandant à l'utilisateur une confirmation supplémentaire avant de continuer. Si elle renvoie UNSURE, la procédure de vérification locale suivante doit être utilisée.

  1. Supposons que expressions soit une liste d'expressions de suffixe/préfixe générées par l'URL u.
  2. Supposons que expressionHashes soit une liste dont les éléments sont les hachages SHA256 de chaque expression de expressions.
  3. Pour chaque hash de expressionHashes :
    1. Si hash est trouvé dans le cache global, renvoyez UNSURE.
  4. Supposons que expressionHashPrefixes soit une liste dont les éléments sont les 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 supérieure à la date d'expiration.
      2. Si la valeur est supérieure :
        1. Supprimez l'entrée mise en cache trouvée du cache local.
        2. Poursuivez la boucle.
      3. Si ce n'est pas le cas :
        1. Supprimez cet élément expressionHashPrefix particulier de expressionHashPrefixes.
        2. Vérifiez si le hachage complet correspondant dans expressionHashes est trouvé dans l'entrée mise en cache.
        3. Si elle est trouvée, renvoyez UNSAFE.
        4. Si ce n'est pas le cas, poursuivez la boucle.
    3. Si l'entrée mise en cache est introuvable, continuez la boucle.
  6. Envoyez expressionHashPrefixes au serveur Google Safe Browsing v5 à l'aide de SearchHashes RPC ou de la méthode REST hashes.search. Si une erreur s'est produite (y compris des erreurs réseau, des erreurs HTTP, etc.), renvoyez UNSURE. Sinon, définissez la réponse sur le response reçu du serveur SB, qui est une liste de hachages complets avec des informations auxiliaires identifiant la nature de la menace (ingénierie sociale, logiciel malveillant, etc.), ainsi que l'heure 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. Supposons que isFound soit le résultat de la recherche de fullHash dans expressionHashes.
    2. Si isFound est défini sur "False", continuez la boucle.
    3. Si isFound est "true", renvoie UNSAFE.
  9. Renvoyez SAFE.

Bien que ce protocole spécifie quand le client envoie des expressionHashPrefixes au serveur, il ne spécifie pas précisément comment les envoyer. Par exemple, le client peut envoyer tous les expressionHashPrefixes dans une seule requête, et il peut également envoyer chaque préfixe individuel dans expressionHashPrefixes au serveur dans des requêtes distinctes (peut-être 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 des URL de la liste LocalThreat

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

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

  1. Supposons que expressions soit une liste d'expressions de suffixe/préfixe générées par l'URL u.
  2. Supposons que expressionHashes soit une liste dont les éléments sont les hachages SHA256 de chaque expression de expressions.
  3. Supposons que expressionHashPrefixes soit une liste dont les éléments sont les 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 supérieure à la date d'expiration.
      2. Si la valeur est supérieure :
        1. Supprimez l'entrée mise en cache trouvée du cache local.
        2. Poursuivez la boucle.
      3. Si ce n'est pas le cas :
        1. Supprimez cet élément expressionHashPrefix particulier de expressionHashPrefixes.
        2. Vérifiez si le hachage complet correspondant dans expressionHashes est trouvé dans l'entrée mise en cache.
        3. Si elle est trouvée, renvoyez UNSAFE.
        4. Si ce n'est pas le cas, poursuivez la boucle.
    3. Si l'entrée mise en cache est introuvable, continuez la boucle.
  5. Pour chaque expressionHashPrefix de expressionHashPrefixes :
    1. Recherchez expressionHashPrefix dans la base de données de la liste de menaces locale.
    2. Si l'expressionHashPrefix est introuvable dans la base de données de la liste de menaces locale, supprimez-le de expressionHashPrefixes.
  6. Envoyez expressionHashPrefixes au serveur Google Safe Browsing v5 à l'aide de SearchHashes RPC ou de la méthode REST hashes.search. Si une erreur s'est produite (y compris des erreurs réseau, des erreurs HTTP, etc.), renvoyez SAFE. Sinon, définissez la réponse sur le response reçu du serveur SB, qui est une liste de hachages complets avec des informations auxiliaires identifiant la nature de la menace (ingénierie sociale, logiciel malveillant, etc.), ainsi que l'heure 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. Supposons que isFound soit le résultat de la recherche de fullHash dans expressionHashes.
    2. Si isFound est défini sur "False", continuez la boucle.
    3. Si isFound est "true", renvoie 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. Supposons que expressions soit une liste d'expressions de suffixe/préfixe générées par l'URL u.
  2. Supposons que expressionHashes soit une liste dont les éléments sont les hachages SHA256 de chaque expression de expressions.
  3. Supposons que expressionHashPrefixes soit une liste dont les éléments sont les 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 supérieure à la date d'expiration.
      2. Si la valeur est supérieure :
        1. Supprimez l'entrée mise en cache trouvée du cache local.
        2. Poursuivez la boucle.
      3. Si ce n'est pas le cas :
        1. Supprimez cet élément expressionHashPrefix particulier de expressionHashPrefixes.
        2. Vérifiez si le hachage complet correspondant dans expressionHashes est trouvé dans l'entrée mise en cache.
        3. Si elle est trouvée, renvoyez UNSAFE.
        4. Si ce n'est pas le cas, poursuivez la boucle.
    3. Si l'entrée mise en cache est introuvable, continuez la boucle.
  5. Envoyez expressionHashPrefixes au serveur Google Safe Browsing v5 à l'aide de SearchHashes RPC ou de la méthode REST hashes.search. Si une erreur s'est produite (y compris des erreurs réseau, des erreurs HTTP, etc.), renvoyez SAFE. Sinon, définissez la réponse sur le response reçu du serveur SB, qui est une liste de hachages complets avec des informations auxiliaires identifiant la nature de la menace (ingénierie sociale, logiciel malveillant, etc.), ainsi que l'heure 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. Supposons que isFound soit le résultat de la recherche de fullHash dans expressionHashes.
    2. Si isFound est défini sur "False", continuez la boucle.
    3. Si isFound est "true", renvoie UNSAFE.
  8. Renvoyez SAFE.

Tout comme la procédure de vérification des URL en temps réel, celle-ci ne spécifie pas exactement comment envoyer les préfixes de hachage au serveur. Par exemple, le client peut envoyer tous les expressionHashPrefixes dans une seule requête, et il peut également envoyer chaque préfixe individuel dans expressionHashPrefixes au serveur dans des requêtes distinctes (peut-être 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.

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 de 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 de 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-4b

Le corps de la réponse est, encore une fois, une charge utile au format de tampon de protocole que vous pouvez ensuite décoder.