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