Mise en cache

Ce document s'applique aux méthodes suivantes :

À 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.

Vérification d'URL
Demande de correspondance de menaces 		Correspondance de l'URL :
Réponse 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 qui inclut 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 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 négative du cache 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 intégrales avec hachage
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 fiable 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... non sécurisé pendant 10 minutes. La le client doit prendre en compte toutes les autres URL avec le préfixe de hachage 0xbbbbbbbb pendant 5 minutes. Après 17h minutes, l'entrée de cache négative du préfixe de hachage expire. Étant donné que l'entrée de cache positive pour 0xbbbbbbbb0000... n'a pas encore expiré, le client devrait envoyer des requêtes fullHashes pour tous les hachages sauf celui-là.		 
"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 suppose pour garantir la sécurité, sauf si le hachage complet de l'URL correspond au hachage complet mis en cache 0xccccccccdddd... Dans ce cas, le client doit considérer cette URL comme non sécurisée pendant 10 minutes. Au bout de 10 minutes, la version intégrale du hachage expire. Toute recherche ultérieure de ce hachage complet doit déclenchera une nouvelle requête fullHashes.