Mise en cache

Ce document s'applique aux méthodes suivantes :

À propos du cache

Pour réduire l'utilisation de la bande passante du client et pour protéger Google des pics de trafic, les clients de l'API Lookup et de l'API Update doivent créer et gérer un cache local des données sur les menaces. Pour l'API Lookup, le cache permet de réduire le nombre de requêtes threatMatches que les clients envoient à Google. Pour l'API Update, le cache est utilisé pour réduire le nombre de requêtes fullHashes que les clients envoient à Google. Le protocole de mise en cache de chaque API est décrit ci-dessous.

API Lookup

Les clients de l'API Lookup doivent mettre en cache chaque élément ThreatMatch renvoyé pendant la durée définie par son champ cacheDuration. Les clients doivent ensuite consulter le cache avant d'envoyer une requête threatMatches ultérieure au serveur. Si la durée de mise en cache d'un ThreatMatch précédemment renvoyé n'a pas encore expiré, le client doit supposer que l'élément est toujours dangereux. La mise en cache d'éléments ThreatMatch peut réduire le nombre de requêtes API effectuées par le client.

Exemple: threatMatches.find

Cliquez sur les liens de requête et de réponse dans l'en-tête du tableau pour obtenir des exemples complets.

Vérification de l'URL
Demande de correspondances 		Correspondance avec l'URL
Réponse à la question de menace 		Comportement de mise en cache 
"threatEntries": [
 {"url": "http://www.urltocheck.org/"}
]

"matches": [{
 "threat": {"url": "http://www.urltocheck.org/"},
 "cacheDuration": "300.000s"
}]
Correspondance
Le client doit attendre cinq minutes avant d'envoyer une nouvelle requête threatMatches incluant l'URL http://www.urltocheck.org/.

API Update

Pour réduire le nombre total de requêtes fullHashes envoyées à Google à l'aide de l'API Update, les clients doivent conserver un cache local. L'API établit deux types de mise en cache : la mise en cache positive et la mise en cache négative.

Cache positif

Pour empêcher les clients d'interroger à plusieurs reprises l'état d'un hachage complet non sécurisé, chaque ThreatMatch renvoyé contient une durée de cache positive (définie par le champ cacheDuration), qui indique la durée pendant laquelle le hachage complet doit être considéré comme dangereux.

Cache négatif

Pour empêcher les clients d'interroger à plusieurs reprises l'état d'un hachage complet sécurisé particulier, chaque réponse fullHashes définit une durée de cache négative pour le préfixe demandé (défini par le champ negativeCacheDuration). Cette durée indique la durée pendant laquelle tous les hachages complets avec le préfixe demandé sont considérés comme sûrs pour les listes demandées, à l'exception de ceux renvoyés par le serveur. Cette mise en cache est particulièrement importante, car elle évite la surcharge du trafic pouvant être causé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 complet du hachage est présent dans la base de données locale, le client doit ensuite consulter son cache avant d'envoyer une requête fullHashes au serveur.

Tout d'abord, les clients doivent rechercher un succès de cache positif. Si une entrée de cache positive non expirée existe pour le hachage complet qui vous intéresse, elle doit être considérée comme non sécurisée. Si l'entrée de cache positive a expiré, le client doit envoyer une requête fullHashes pour le préfixe local associé. Conformément au protocole, si le serveur renvoie le hachage complet, il est considéré comme non sécurisé. Sinon, il est considéré comme sûr.

S'il n'y a pas d'entrées de cache positives pour le hachage complet, le client doit rechercher un succès de cache négatif. S'il existe une entrée de cache négative non expirée pour le préfixe local associé, le hachage complet est considéré comme sûr. Si l'entrée de cache négative a expiré ou qu'elle n'existe pas, le client doit envoyer une requête fullHashes pour le préfixe local associé et interpréter la réponse normalement.

Mise à jour du cache

Le cache du client doit être mis à jour chaque fois qu'une réponse fullHashes est reçue. Une entrée de cache positive doit être créée ou mise à jour pour le hachage complet conformément au champ cacheDuration. La durée de cache négative du préfixe de hachage doit également être créée ou mise à jour conformément au champ negativeCacheDuration de la réponse.

Si une requête fullHashes ultérieure ne renvoie pas un hachage complet actuellement mis en cache, le client n'est pas tenu de supprimer l'entrée de cache positive. Cela ne pose pas de problème dans la pratique, car les durées de cache positives sont généralement courtes (quelques minutes) pour permettre la 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. Par exemple, h(url) = SHA256(url).substr(4), H(url) = SHA256(url).

Supposons maintenant qu'un client (avec un cache vide) visite example.com/ et voie que h(example.com/) se trouve dans la base de données locale. Le client demande les hachages complets du préfixe h(example.com/) et reçoit le hachage complet H(example.com/), ainsi qu'une durée de mise en cache positive de cinq minutes et une durée de mise en cache négative d'une heure.

La durée de mise en cache positive de 5 minutes indique au client combien de temps le hachage complet(H.example.com/) doit être considéré comme dangereux sans envoyer une autre requête fullHashes. Au bout de cinq minutes, le client doit émettre une autre requête fullHashes pour ce préfixe h(example.com/) s'il accède de nouveau à example.com/. Le client doit réinitialiser la durée de cache négative du préfixe de hachage selon la nouvelle réponse.

La durée de mise en cache négative d'une heure indique au client la durée pendant laquelle tous les autres hachages complets, en plus de H(example.com/), qui partagent le même préfixe h(example.com/), doivent être considérés comme sûrs. Pendant une durée d'une heure, toutes les URL telles que h(URL) = h(example.com/) doivent être considérées comme sûres. Elles ne doivent donc pas entraîner une requête fullHashes (en supposant que H(URL) != H(example.com/).

Si la réponse fullHashes ne contient aucune correspondance et qu'une durée de cache négative est définie, le client ne doit émettre aucune requête fullHashes pour les préfixes demandés pour la durée de cache négative donnée.

Si la réponse fullHashes contient une ou plusieurs correspondances, une durée de cache négative est tout de même définie pour toute la réponse. Dans ce cas, la durée de mise en cache d'un seul hachage complet indique la durée pendant laquelle ce hachage complet doit être considéré comme dangereux par le client. Une fois la durée de cache ThreatMatch écoulée, le client doit actualiser le hachage complet en envoyant une requête fullHashes 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égative ne s'applique pas. La durée négative du cache de la réponse ne s'applique qu'aux hachages complets qui n'étaient pas présents dans la réponse fullHashes. Pour les hachages complets qui ne sont pas présents dans la réponse, le client doit s'abstenir d'émettre des requêtes fullHashes jusqu'à ce que la durée de cache négative soit écoulée.

Exemple: fullHashes.find

Cliquez sur les liens de requête et de réponse dans l'en-tête du tableau pour obtenir des exemples complets.

Préfixes de hachage
Requête fullHashes 		Correspondances de hachage complètes
Réponse fullHashes 		Comportement de mise en cache 
"threatEntries": [
  {"hash": "0xaaaaaaaa"}
]

"matches": [],
"negativeCacheDuration": "3600.000s"
Aucune correspondance
Le client ne doit pas envoyer de requêtes fullHashes pour le préfixe de hachage 0xaaaaaaaa pendant au moins une heure. Tout hachage avec le préfixe 0xaaaaaaaa est considéré comme sûr pendant une heure.		 
"threatEntries": [
  {"hash": "0xbbbbbbbb"}
]

"matches": [
 "threat": {"hash": "0xbbbbbbbb0000..."}
 "cacheDuration": "600.000s",
],
"negativeCacheDuration": "300.000s"
Correspondances possibles.
Le client doit considérer l'URL avec le hachage complet 0xbbbbbbbb0000... et non sécurisée pendant 10 minutes. Le client doit tenir compte de toutes les autres URL dont le préfixe de hachage 0xbbbbbbbb est sécurisé pendant cinq minutes. Après cinq minutes, l'entrée de cache à exclure des préfixes de hachage expire. Comme l'entrée de cache positive pour 0xbbbbbbbb0000... n'a pas encore expiré, le client doit envoyer des requêtes fullHashes pour tous les hachages, à l'exception de celui-ci.		 
"threatEntries": [
  {"hash": "0xcccccccc"}
]

"matches": [
 "threat": {"hash": "0xccccccccdddd..."},
 "cacheDuration": "600.000s"
],
"negativeCacheDuration": "3600.000s"
Correspondances possibles.
Le client ne doit pas envoyer de requête fullHashes pour le préfixe de hachage 0xcccccccc pendant au moins une heure, et supposer que ce préfixe est sûr, sauf si le hachage complet de l'URL correspond au hachage complet en cache (0xccccccccdddd...). Dans ce cas, le client doit considérer cette URL comme dangereuse pendant 10 minutes. Au bout de 10 minutes, le hachage complet expire. Toute recherche ultérieure pour ce hachage complet devrait déclencher une nouvelle requête fullHashes.