Armazenamento em cache

Este documento se aplica aos seguintes métodos:

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

Sobre o armazenamento em cache

Para reduzir o uso de largura de banda do cliente e proteger o Google contra picos de tráfego, os clientes do A API Lookup e a API Update são necessárias para criar e manter um cache local de dados sobre ameaças. Na API Lookup, o cache é usado para reduzir o número de threatMatches que os clientes enviam ao Google. Para a API Update, o cache é usado para reduzir o número de solicitações fullHashes que os clientes enviam ao Google. O protocolo de armazenamento em cache de cada API é descritos abaixo.

API Lookup

Os clientes da API Lookup precisam armazenar em cache cada item ThreatMatch retornado pelo tempo definido. pelo campo cacheDuration. Os clientes precisam consultar o cache antes de fazer uma threatMatches ao servidor. Se a duração do cache de um ThreatMatch retornado anteriormente ainda não expirou, o cliente deve presumir que o item ainda não é seguro. Armazenando ThreatMatch itens em cache pode reduzir o número de solicitações de API feitas pelo cliente.

Exemplo: ThreatMatches.find

Clique nos links de solicitação e resposta no cabeçalho da tabela para ver exemplos completos.

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

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

API Update

Para reduzir o número total de solicitações fullHashes enviadas ao Google usando a API Update, os clientes para manter um cache local. A API estabelece dois tipos de armazenamento em cache, positivo e negativo.

Armazenamento em cache positivo

Para evitar que os clientes perguntem repetidamente sobre o estado de um hash completo não seguro, cada ThreatMatch retornado contém uma duração de cache positiva (definida pelo campo cacheDuration), que indica por quanto tempo o hash completo deve ser considerado não seguro.

Armazenamento em cache negativo

Para evitar que os clientes perguntem repetidamente sobre o estado de um hash completo seguro, cada resposta fullHashes define uma duração de cache negativa para o prefixo solicitado (definido pelo negativeCacheDuration). Essa duração indica por quanto tempo todos os hashes completos com a solicitação prefixo devem ser considerados seguros para as listas solicitadas, exceto para aqueles retornados pelo servidor como não seguros. Esse armazenamento em cache é muito importante porque evita a sobrecarga de tráfego que pode ser causada por uma colisão de prefixos de hash com um URL seguro que recebe muito tráfego.

Como consultar o cache

Quando o cliente quer verificar o estado de um URL, primeiro ele calcula o hash completo. Se o prefixo do hash estiver presente no banco de dados local, o cliente deverá consultar o cache antes fazendo uma solicitação fullHashes ao servidor.

Primeiro, os clientes devem verificar se há um hit de cache positivo. Se houver um cache positivo não expirado para o hash completo de interesse, ele será considerado não seguro. Se a entrada positiva no cache expirar, o cliente precisa enviar uma solicitação fullHashes para o prefixo local associado. De acordo com se o servidor retornar o hash completo, ele será considerado não seguro; caso contrário, é considerado seguros.

Se não houver entradas de cache positivas para o hash completo, o cliente deve verificar se há um número negativo ocorrência em cache. Se houver uma entrada de cache negativa não expirada para o prefixo local associado, o o hash completo é considerado seguro. Se a entrada no cache negativo tiver expirado ou não existir, o cliente precisa enviar uma solicitação fullHashes para o prefixo local associado e interpretar a resposta como normal.

Como atualizar o cache

O cache do cliente precisa ser atualizado sempre que uma resposta fullHashes é recebida. Um cache positivo entrada deve ser criada ou atualizada para o hash completo de acordo com o campo cacheDuration. O prefixo hash a duração do cache negativo também precisa ser criada ou atualizada de acordo com o negativeCacheDuration da resposta. .

Se uma solicitação fullHashes subsequente não retornar um hash completo com status positivo no cache, o cliente não precisa remover a entrada positiva no cache. Isso não é motivo de preocupação na prática, já que durações positivas de cache são geralmente curtas (alguns minutos) para permitir uma e a correção de falsos positivos.

Exemplo de cenário

No exemplo a seguir, suponha que h(url) é o prefixo hash do URL e H(url) é o hash completo do URL. Ou seja, h(url) = SHA256(url).substr(4), H(url) = SHA256(url).

Agora, suponha que um cliente (com um cache vazio) visite example.com/ e veja que h(example.com/) está no banco de dados local. O cliente solicita os hashes completos do prefixo de hash h(example.com/). e recebe o hash completo H(example.com/) com uma duração de cache positiva de 5. minutos e uma duração de cache negativa de 1 hora.

A duração positiva de cache de 5 minutos informa ao cliente por quanto tempo o hash completo H(example.com/) precisa ser considerado não seguro sem o envio de outra solicitação fullHashes. Após as 17h minutos, o cliente precisará emitir outra solicitação fullHashes para o prefixo h(example.com/) se o o cliente visita example.com/ novamente. O cliente precisa redefinir a duração do cache negativo do prefixo de hash. de acordo com a nova resposta.

A duração de cache negativa de 1 hora informa ao cliente por quanto tempo todos os outros hashes completos além de H(example.com/), que compartilham o mesmo prefixo de h(example.com/), precisam ser consideradas seguras. Para a duração de uma hora, cada URL de modo que h(URL) = h(example.com/) seja considerado seguro e portanto, não vai resultar em uma solicitação fullHashes, supondo que H(URL) != H(example.com/)).

Se a resposta fullHashes não tiver nenhuma correspondência e uma duração de cache negativa for definida, então o o cliente não poderá emitir solicitações fullHashes para nenhum dos prefixos solicitados para o duração do cache negativo.

Se a resposta fullHashes contiver uma ou mais correspondências, ainda haverá uma duração de cache negativa definida para toda a resposta. Nesse caso, a duração do cache de um único hash completo indica quanto tempo esse hash completo específico precisa ser considerado inseguro pelo cliente. Após o cache de ThreatMatch decorrido, o cliente precisa atualizar o hash completo emitindo uma solicitação fullHashes para esse prefixo de hash se o URL solicitado corresponder ao hash completo existente no cache. Nesse caso a duração do cache negativo não se aplique. A duração do cache negativo da resposta só se aplica para hashes completos que não estavam presentes na resposta fullHashes. Para hashes completos que não estiverem presentes na resposta, o cliente deverá evitar emitir solicitações fullHashes até que a duração do cache negativo termine.

Exemplo: fullHashes.find

Clique nos links de solicitação e resposta no cabeçalho da tabela para ver exemplos completos.

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