Cache

Ce document s'applique aux méthodes suivantes :

• API Lookup : uris.search
• API Update : hashes.search

À propos du cache

Pour réduire l'utilisation de la bande passante par les clients et aider Google à faire face aux pics de trafic, les clients de l'API Lookup et de l'API Update doivent créer et gérer un cache local de données sur les menaces. L'API Lookup utilise le cache pour réduire le nombre de requêtes uris.search que les clients envoient à Google. Pour l'API Update, le cache est utilisé pour réduire le nombre de requêtes hashes.search que les clients envoient à Google. Le protocole de mise en cache pour chaque API est décrit ci-dessous.

API Lookup

Les clients de l'API Lookup doivent mettre en cache chaque élément ThreatUrl renvoyé jusqu'au moment indiqué dans le champ expireTime. Les clients doivent ensuite consulter le cache avant d'envoyer une requête uris.search ultérieure au serveur. Si l'entrée de cache d'un élément ThreatUrl précédemment renvoyé n'a pas encore expiré, le client doit supposer que l'élément n'est toujours pas sécurisé. La mise en cache d'éléments ThreatUrl peut réduire le nombre de requêtes API effectuées par le client.

API Update

Pour réduire le nombre total de requêtes hashes.search envoyées à Google à l'aide de l'API Update, les clients doivent gérer un cache local. L'API établit deux types de cache : positif et négatif.

Cache positif

Pour empêcher les clients de demander à plusieurs reprises l'état d'un hachage completnon sécurisé, chaque élément ThreatHash renvoyé contient un délai de cache positif (défini dans le champ expireTime). Le hachage complet peut être considéré comme non sécurisé jusqu'à cette date.

Cache négatif

Pour empêcher les clients de demander à plusieurs reprises l'état d'un hachage complet sécurisé, la réponse définit une durée de cache négatif pour le préfixe demandé (définie dans le champ negativeExpireTime). Tous les hachages complets avec le préfixe demandé doivent être considérés comme sécurisés pour les types de menaces demandés jusqu'à cette date, à l'exception de ceux renvoyés par le serveur comme non sécurisés. Cette mise en cache est particulièrement importante, car elle empêche la surcharge du trafic qui pourrait être provoquée par un conflit de préfixe de hachage avec une URL sécurisée qui reçoit beaucoup de trafic.

Consultation du cache

Lorsque le client souhaite vérifier l'état d'une URL, il calcule d'abord son hachage complet. Si le préfixe du hachage complet est présent dans la base de données locale, le client doit consulter son cache avant d'envoyer une requête hashes.search au serveur.

Tout d'abord, les clients doivent rechercher un succès de cache positif. S'il existe une entrée de cache positif n'ayant pas expiré pour le hachage complet concerné, elle doit être considérée comme non sécurisée. Si l'entrée de cache positif a expiré, le client doit envoyer une requête hashes.search pour le préfixe local associé. Selon le protocole, si le serveur renvoie le hachage complet, il est considéré comme non sécurisé. Sinon, il est considéré comme sécurisé.

S'il n'y a aucune entrée de cache positif pour le hachage complet, le client doit rechercher un succès de cache négatif. S'il existe une entrée de cache négatif n'ayant pas expiré pour le préfixe local associé, le hachage complet est considéré comme sécurisé. Si l'entrée de cache négatif a expiré ou si elle n'existe pas, le client doit envoyer une requête hashes.search pour le préfixe local associé et interpréter la réponse comme d'habitude.

Mise à jour du cache

Le cache du client doit être mis à jour chaque fois qu'une réponse hashes.search est reçue. Une entrée de cache positif doit être créée ou mise à jour pour le hachage complet en fonction du champ expireTime. La durée de cache négatif du préfixe de hachage doit également être définie ou mise à jour en fonction du champ negativeExpireTime de la réponse.

Si une requête hashes.search ultérieure ne renvoie pas un hachage complet qui est actuellement mis en cache de façon positive, le client n'est pas tenu de supprimer l'entrée de cache positif. Cela ne pose pas de problème dans la pratique, car les durées de cache positif sont généralement courtes (quelques minutes) pour permettre une correction rapide des faux positifs.

Exemple de scénario

Dans l'exemple suivant, supposons que h(url) est le préfixe de hachage de l'URL et H(url) le hachage complet de l'URL. Autrement dit, h(url) = SHA256(url).substr(4) et H(url) = SHA256(url).

Supposons qu'un client avec un cache vide accède à example.com/ et constate que h(example.com/) se trouve dans la base de données locale. Le client demande les hachages complets pour le préfixe de hachage h(example.com/) et reçoit le hachage complet H(example.com/) avec un délai d'expiration de cache positif de cinq minutes et un délai d'expiration de cache négatif d'une heure.

La durée de cache positif de cinq minutes indique au client la durée pendant laquelle le hachage complet H(example.com/) doit être considéré comme non sécurisé, sans envoyer une autre requête hashes.search. Après cinq minutes, le client doit envoyer une autre requête hashes.search pour ce préfixe h(example.com/) s'il accède de nouveau à example.com/. Le client doit réinitialiser le délai d'expiration de cache négatif du préfixe de hachage en fonction de la nouvelle réponse.

La durée de cache négatif d'une heure indique au client combien de temps tous les autres hachages complets autres que H(example.com/) qui partage le même préfixe h(example.com/) doivent être considérés comme sécurisés. Pendant cette durée d'une heure, chaque URL telle que h(URL) = h(example.com/) doit être considérée comme sécurisée et ne doit donc pas entraîner de requête hashes.search (en supposant que H(URL)!= H(example.com/)).

Si la réponse fullHashes ne contient aucune correspondance et qu'un délai d'expiration de cache négatif est défini, le client ne doit envoyer aucune requête hashes.search pour les préfixes demandés avec un délai de cache négatif donné.

Si la réponse hashes.search contient une ou plusieurs correspondances, un délai d'expiration de cache négatif est toujours défini pour l'intégralité de la réponse. Dans ce cas, le délai d'expiration du cache d'un seul hachage complet indique la durée pendant laquelle le client doit supposer que le hachage complet est non sécurisé. Une fois la durée du cache ThreatHash écoulée, le client doit actualiser le hachage complet en envoyant une requête hashes.search pour ce préfixe de hachage si l'URL demandée correspond au hachage complet existant dans le cache. Dans ce cas, la durée de cache négatif ne s'applique pas. La durée de cache négatif de la réponse ne s'applique qu'aux hachages complets qui n'étaient pas présents dans la réponse hashes.search. Pour les hachages complets qui ne sont pas présents dans la réponse, le client doit s'abstenir d'envoyer des requêtes hashes.search tant que la durée de cache négatif n'est pas écoulée.