Almacenamiento en caché

Este documento se aplica a los siguientes métodos:

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

Acerca del almacenamiento en caché

Para reducir el uso del ancho de banda del cliente y proteger a Google de los aumentos repentinos de tráfico, los clientes de la API de Lookup y la API de Update deben crear y mantener una caché local de datos de amenazas. Para la API de Lookup, la caché se usa para reducir la cantidad de solicitudes threatMatches que los clientes envían a Google. Para la API de Update, la caché se usa para reducir la cantidad de solicitudes fullHashes que los clientes envían a Google. El protocolo de almacenamiento en caché para cada API se describe a continuación.

API de Lookup

Los clientes de la API de Lookup deben almacenar en caché cada elemento ThreatMatch que se muestra durante el tiempo definido por su campo cacheDuration. Luego, los clientes deben consultar la caché antes de realizar una solicitud threatMatches posterior al servidor. Si aún no venció la duración de la caché de un objeto ThreatMatch que se mostró anteriormente, el cliente debe suponer que el elemento aún no es seguro. Almacenar en caché elementos ThreatMatch puede reducir la cantidad de solicitudes a la API que realiza el cliente.

Ejemplo: ThreatMatches.find

Haz clic en los vínculos de solicitud y respuesta que se encuentran en el encabezado de la tabla para ver los ejemplos completos.

Verificación de URL threatMatches Request	Coincidencia de URL threatMatches Response	Comportamiento del almacenamiento en caché
"threatEntries": [ {"url": "http://www.urltocheck.org/"} ]	"matches": [{ "threat": {"url": "http://www.urltocheck.org/"}, "cacheDuration": "300.000s" }]	Buscar coincidencias El cliente debe esperar 5 minutos antes de enviar una nueva solicitud threatMatches que incluya la URL http://www.urltocheck.org/.

API de Update

Para reducir la cantidad total de solicitudes fullHashes enviadas a Google con la API de Update, los clientes deben mantener una caché local. La API establece dos tipos de almacenamiento en caché: positivo y negativo.

Almacenamiento en caché positivo

Para evitar que los clientes pregunten repetidamente sobre el estado de un hash completo no seguro específico, cada ThreatMatch que se muestra contiene una duración de caché positiva (definida por el campo cacheDuration), que indica durante cuánto tiempo se debe considerar no seguro el hash completo.

Almacenamiento en caché negativo

Para evitar que los clientes pregunten repetidamente sobre el estado de un hash completo seguro específico, cada respuesta fullHashes define una duración negativa de la caché para el prefijo solicitado (definido por el campo negativeCacheDuration). Esta duración indica por cuánto tiempo se consideran seguros todos los hashes completos con el prefijo solicitado para las listas solicitadas, excepto los que el servidor muestra como no seguros. Este almacenamiento en caché es muy importante, ya que evita la sobrecarga de tráfico que podría deberse a una colisión de prefijos de hash con una URL segura que recibe mucho tráfico.

Consulta la caché

Cuando el cliente quiere verificar el estado de una URL, primero calcula su hash completo. Si el prefijo del hash completo está presente en la base de datos local, el cliente debe consultar su caché antes de realizar una solicitud fullHashes al servidor.

Primero, los clientes deben comprobar si hay un acierto de caché positivo. Si existe una entrada de caché positiva sin vencer para el hash de interés completo, debe considerarse no segura. Si la entrada de caché positiva venció, el cliente debe enviar una solicitud fullHashes para el prefijo local asociado. Según el protocolo, si el servidor muestra el hash completo, se considera no seguro; de lo contrario, se considera seguro.

Si no hay entradas de caché positivas para el hash completo, el cliente debe verificar si hay un acierto de caché negativo. Si existe una entrada de caché negativa sin vencer para el prefijo local asociado, el hash completo se considera seguro. Si la entrada de caché negativa venció o no existe, el cliente debe enviar una solicitud fullHashes para el prefijo local asociado y, luego, interpretar la respuesta como normal.

Actualiza la caché

La caché del cliente debe actualizarse cada vez que se recibe una respuesta fullHashes. Se debe crear o actualizar una entrada de caché positiva para el hash completo según el campo cacheDuration. La duración de la caché negativa del prefijo de hash también se debe crear o actualizar según el campo negativeCacheDuration de la respuesta.

Si una solicitud fullHashes posterior no muestra un hash completo que en este momento se almacene de forma positiva en caché, no es necesario que el cliente quite la entrada de caché positiva. Esto no es motivo de preocupación en la práctica, ya que las duraciones positivas de la caché suelen ser cortas (algunos minutos) para permitir una corrección rápida de los falsos positivos.

Situación de ejemplo

En el siguiente ejemplo, supongamos que h(url) es el prefijo de hash de la URL y H(url) es el hash de longitud completa de la URL. Es decir, h(url) = SHA256(url).substr(4), H(url) = SHA256(url).

Ahora, supongamos que un cliente (con una caché vacía) visita example.com/ y ve que h(example.com/) está en la base de datos local. El cliente solicita los hashes de longitud completa para el prefijo de hash h(example.com/) y recibe el hash completo H(example.com/), junto con una duración positiva de la caché de 5 minutos y una duración negativa de la caché de 1 hora.

La duración positiva de la caché de 5 minutos le indica al cliente por cuánto tiempo el hash completo H(example.com/) debe considerarse no seguro sin enviar otra solicitud fullHashes. Después de 5 minutos, el cliente debe emitir otra solicitud fullHashes para ese prefijo h(example.com/) si el cliente visita example.com/ nuevamente. El cliente debe restablecer la duración de caché negativa del prefijo hash según la respuesta nueva.

La duración negativa de la caché de 1 hora le indica al cliente durante cuánto tiempo todos los demás hashes completos, además de H(example.com/), que comparten el mismo prefijo de h(example.com/) deben considerarse seguros. Durante 1 hora, todas las URL en las que h(URL) = h(example.com/) deben considerarse seguras y, por lo tanto, no deben generar una solicitud fullHashes (suponiendo que H(URL) != H(example.com/)).

Si la respuesta fullHashes no contiene coincidencias y se establece una duración de caché negativa, el cliente no debe emitir ninguna solicitud fullHashes para ninguno de los prefijos solicitados para la duración de caché negativa determinada.

Si la respuesta fullHashes contiene una o más coincidencias, se establece una duración negativa de la caché para toda la respuesta. En ese caso, la duración de la caché de un solo hash completo indica durante cuánto tiempo el cliente debe suponer que no es seguro ese hash de longitud completa particular. Una vez que transcurre la duración de la caché ThreatMatch, el cliente debe actualizar el hash completo mediante la emisión de una solicitud fullHashes para ese prefijo de hash si la URL solicitada coincide con el hash de longitud completa existente en la caché. En ese caso, no se aplica la duración negativa de la caché. La duración negativa de la caché de la respuesta solo se aplica a los hashes de longitud completa que no estaban presentes en la respuesta fullHashes. En el caso de los hashes de longitud completa que no estén presentes en la respuesta, el cliente debe abstenerse de emitir solicitudes fullHashes hasta que haya transcurrido la duración negativa de la caché.

Ejemplo: fullHashes.find

Haz clic en los vínculos de solicitud y respuesta que se encuentran en el encabezado de la tabla para ver los ejemplos completos.

Prefijos de hash Solicitud de fullHashes	Coincidencias de hash de longitud completa respuesta fullHashes	Comportamiento del almacenamiento en caché
"threatEntries": [ {"hash": "0xaaaaaaaa"} ]	"matches": [], "negativeCacheDuration": "3600.000s"	No hay coincidencias El cliente no debe enviar ninguna solicitud fullHashes para el prefijo de hash 0xaaaaaaaa durante al menos una hora. Cualquier hash con el prefijo 0xaaaaaaaa se considera seguro durante una hora.
"threatEntries": [ {"hash": "0xbbbbbbbb"} ]	"matches": [ "threat": {"hash": "0xbbbbbbbb0000..."} "cacheDuration": "600.000s", ], "negativeCacheDuration": "300.000s"	Posibles coincidencias. El cliente debe considerar que la URL con el hash completo 0xbbbbbbbb0000... no segura durante 10 minutos. El cliente debe considerar que todas las demás URLs con el prefijo hash 0xbbbbbbbb son seguras durante 5 minutos. Después de 5 minutos, vencerán los prefijos hash de la entrada de caché negativa. Dado que la entrada de caché positiva para 0xbbbbbbbb0000... aún no venció, el cliente debe enviar solicitudes fullHashes para todos los hashes, excepto ese.
"threatEntries": [ {"hash": "0xcccccccc"} ]	"matches": [ "threat": {"hash": "0xccccccccdddd..."}, "cacheDuration": "600.000s" ], "negativeCacheDuration": "3600.000s"	Posibles coincidencias. El cliente no debe enviar ninguna solicitud fullHashes para el prefijo de hash 0xcccccccc durante al menos 1 h y suponer que ese prefijo es seguro, excepto si el hash completo de la URL coincide con el hash completo almacenado en caché 0xccccccccdddd... En ese caso, el cliente debe considerar que la URL no es segura durante 10 minutos. Después de 10 minutos, vence el hash completo. Cualquier búsqueda posterior de ese hash completo debe activar una nueva solicitud fullHashes.