Mise en cache

Ce document s'applique aux méthodes suivantes :

• API Lookup (v4): threatMatches.find
• API Update (v4): fullHashes.find

À propos du cache

Pour réduire l'utilisation de la bande passante des clients et protéger Google contre les pics de trafic, les clients Les API Lookup et Update sont nécessaires pour créer et gérer un cache local de données sur les menaces. Pour l'API Lookup, le cache permet de réduire le nombre de 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 pour chaque API est décrits 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'effectuer une threatMatches au serveur. Si la durée de cache d'un ThreatMatch précédemment renvoyé n'a pas encore expiré, le client doit supposer que l'article est toujours dangereux. Mise en cache de ThreatMatch éléments... peut réduire le nombre de requêtes API effectuées par le client.

Exemple: menaceCorrespondances.find

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

"threatEntries": [
 {"url": "http://www.urltocheck.org/"}
]

"matches": [{
 "threat": {"url": "http://www.urltocheck.org/"},
 "cacheDuration": "300.000s"
}]

API Update

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

Cache positif

Pour éviter que les clients posent des questions répétées sur 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 non sécurisé.

Cache négatif

Pour éviter que les clients posent des questions répétées sur l'état d'un hachage complet sécurisé spécifique, chaque réponse fullHashes définit une durée de cache négative pour le préfixe demandé (défini par le negativeCacheDuration). Cette durée indique la durée de tous les hachages complets avec la valeur doivent être considérés comme sûrs pour les listes demandées, à l'exception de celles renvoyées par le serveur en tant que non sécurisé. Cette mise en cache est particulièrement importante, car elle évite la surcharge de trafic qui pourrait par une collision 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 les de hachage est présent dans la base de données locale, le client doit alors consulter son cache avant en envoyant une requête fullHashes au serveur.

Tout d'abord, les clients doivent rechercher un succès de cache positif. S'il existe un cache positif non expiré pour le hachage complet de l'intérêt, il doit être considéré comme non sécurisé. Si l'entrée de cache positive expiré, le client doit envoyer une requête fullHashes pour le préfixe local associé. Conformément aux protocole, si le serveur renvoie le hachage complet, il est considéré comme non sécurisé. sinon, il est considéré en toute sécurité.

S'il n'existe aucune entrée de cache positive pour le hachage complet, le client doit rechercher une valeur succès de cache. S'il existe une entrée de cache négative non expirée pour le préfixe local associé, le le hachage complet est considéré comme sûr. Si l'entrée de cache négative a expiré ou n'existe pas, le client doit envoyer une requête fullHashes 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 fullHashes est reçue. Un cache positif doit être créée ou mise à jour pour le hachage complet, conformément au champ cacheDuration. Le préfixe de hachage la durée de cache négative doit également être créée ou mise à jour conformément aux negativeCacheDuration de la réponse. .

Si une requête fullHashes ultérieure ne renvoie pas de hachage complet actuellement positif mis en cache, le client n'est pas obligé de supprimer l'entrée de cache positive. Ce n'est pas une cause de préoccupation. en pratique, car les durées de cache positives sont généralement courtes (quelques minutes) pour permettre la correction 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 que H(url) est le hachage complet de l'URL. Autrement dit, h(url) = SHA256(url).substr(4), H(url) = SHA256(url).

Supposons maintenant qu'un client (avec un cache vide) visite example.com/ et constate que h(example.com/) est dans la base de données locale. Le client demande les hachages de la longueur complète du préfixe de hachage h(exemple.com/). et reçoit en retour le hachage complet H(example.com/) avec une durée de cache positive de 5. minutes et une durée de cache négative de 1 heure.

Une durée de cache positive de 5 minutes indique au client la durée du hachage complet H(example.com/) doit être considéré comme non sécurisé sans envoyer une autre requête fullHashes. Après 17h minutes, le client doit émettre une autre requête fullHashes pour ce préfixe h(example.com/) si le client visite de nouveau example.com/. Le client doit réinitialiser la durée de cache négative du préfixe de hachage conformément à la nouvelle réponse.

La durée négative de 1 heure du cache indique au client la durée de tous les autres hachages de la longueur totale autres que H(example.com/), qui partagent le même préfixe que h(example.com/), doivent être considérés comme fiables. Pour qu'une durée d'une heure doit être considérée comme sûre, chaque URL de telle sorte que h(URL) = h(example.com/) et n'entraîne donc pas de 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 le client ne doit pas émettre de requêtes fullHashes pour les préfixes demandés pour la valeur une durée de cache négative.

Si la réponse fullHashes contient une ou plusieurs correspondances, une durée de cache négative est toujours définie. pour l'ensemble de la réponse. Dans ce cas, la durée de cache d'un seul hachage complet indique combien de temps ce hachage complet de longueur doit être considéré comme non sécurisé par le client. Après le cache ThreatMatch est écoulée, le client doit actualiser le hachage complet en émettant 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 où la durée de mise en cache négative ne s'applique pas. La durée de mise en cache négative de la réponse ne s'applique en valeurs de hachage complètes qui n'étaient pas présentes dans la réponse fullHashes. Pour les hachages en pleine longueur qui ne sont pas présentes 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.

"threatEntries": [
  {"hash": "0xaaaaaaaa"}
]

"matches": [],
"negativeCacheDuration": "3600.000s"

"threatEntries": [
  {"hash": "0xbbbbbbbb"}
]

"matches": [
 "threat": {"hash": "0xbbbbbbbb0000..."}
 "cacheDuration": "600.000s",
],
"negativeCacheDuration": "300.000s"

"threatEntries": [
  {"hash": "0xcccccccc"}
]

"matches": [
 "threat": {"hash": "0xccccccccdddd..."},
 "cacheDuration": "600.000s"
],
"negativeCacheDuration": "3600.000s"