Este documento se aplica aos seguintes métodos:
Sobre o armazenamento em cache
Para reduzir o uso da largura de banda do cliente e proteger o Google contra picos de tráfego, os clientes das
APIs Lookup e Update precisam criar e manter um cache local de dados de ameaças.
Na API Lookup, o cache é usado para reduzir o número de solicitações 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 para cada API é descrito abaixo.
API Lookup
Os clientes da API Lookup precisam armazenar em cache cada item ThreatMatch retornado pelo período definido
pelo campo cacheDuration. Os clientes precisam consultar o cache antes de fazer uma solicitação
threatMatches subsequente ao servidor. Se a duração do cache de um ThreatMatch
retornado anteriormente ainda não tiver expirado, o cliente presumirá que o item ainda não é seguro. Armazenar itens ThreatMatch 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.
| Verificação de URL Solicitação threatMatches |
Correspondência de URL Resposta threatMatches |
Comportamento de armazenamento em cache |
|---|---|---|
"threatEntries": [
{"url": "http://www.urltocheck.org/"}
]
|
"matches": [{
"threat": {"url": "http://www.urltocheck.org/"},
"cacheDuration": "300.000s"
}]
|
Correspondência O cliente precisa aguardar cinco minutos antes de enviar uma nova solicitação threatMatches que inclua o URL http://www.urltocheck.org/.
|
API Update
Para reduzir o número total de solicitações fullHashes enviadas ao Google usando a API Update, os clientes
precisam 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 específico,
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 específico, cada resposta fullHashes define uma duração negativa de cache para o prefixo solicitado (definido pelo campo negativeCacheDuration). Essa duração indica por quanto tempo todos os hashes completos com o prefixo solicitado serão considerados seguros para as listas solicitadas, exceto aqueles retornados pelo servidor como não seguros. Esse armazenamento em cache é especialmente importante, porque evita a sobrecarga de tráfego que pode ser causada
por uma colisão de prefixos hash com um URL seguro que recebe muito tráfego.
Como consultar o cache
Quando o cliente quer verificar o estado de um URL, ele primeiro calcula o hash completo. Se o prefixo
de hash completo estiver presente no banco de dados local, o cliente precisará consultar o cache antes
de fazer uma solicitação fullHashes ao servidor.
Primeiro, os clientes devem verificar se há um hit de cache positivo. Se houver uma entrada de cache positiva não expirada
para o hash completo de interesse, ela será considerada não segura. Se a entrada positiva de cache
expirar, o cliente precisará enviar uma solicitação fullHashes para o prefixo local associado. De acordo com o protocolo, se o servidor retornar o hash completo, ele será considerado não seguro. Caso contrário, será considerado seguro.
Se não houver entradas positivas de cache para o hash completo, o cliente precisará verificar se há uma ocorrência em cache negativa. Se houver uma entrada de cache negativo não expirada para o prefixo local associado, o
hash completo será considerado seguro. Se a entrada de cache negativa tiver expirado ou não existir, o cliente precisará enviar uma solicitação fullHashes para o prefixo local associado e interpretar a resposta normalmente.
Como atualizar o cache
O cache do cliente precisa ser atualizado sempre que uma resposta fullHashes é recebida. Uma entrada positiva de cache
precisa ser criada ou atualizada para o hash completo de acordo com o campo cacheDuration. A duração do cache negativo do prefixo de hash também precisa ser criada ou atualizada de acordo com o campo negativeCacheDuration da resposta.
Se uma solicitação fullHashes subsequente não retornar um hash completo atualmente armazenado em cache, o cliente não precisará remover a entrada positiva de cache. Na prática, isso não é motivo de preocupação, já que as durações positivas de cache geralmente são curtas (alguns minutos) para permitir a correção rápida de falsos positivos.
Exemplo
No exemplo a seguir, suponha que h(url) seja o prefixo de hash do URL e H(url) seja 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 para o prefixo de hash h(example.com/) e recebe o hash completo H(example.com/) com uma duração positiva de cache de cinco minutos e uma duração de cache negativa de 1 hora.
A duração positiva do cache de cinco minutos informa ao cliente por quanto tempo o hash completo H(example.com/) precisa ser considerado não seguro sem enviar outra solicitação fullHashes. Após cinco minutos, o cliente precisará emitir outra solicitação fullHashes para esse prefixo h(example.com/) se acessar 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 negativa do cache 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 considerados seguros. Pela duração de uma hora, todos os URLs de forma que h(URL) = h(example.com/) sejam considerados seguros e, portanto, não resultem em uma solicitação fullHashes (supondo que H(URL) != H(example.com/)).
Se a resposta fullHashes não contiver correspondências e uma duração de cache negativa estiver definida, o cliente não poderá emitir solicitações fullHashes para nenhum dos prefixos solicitados para a duração do cache negativo fornecido.
Se a resposta fullHashes tiver uma ou mais correspondências, uma duração de cache negativa ainda será definida para toda a resposta. Nesse caso, a duração do cache de um único hash completo indica por quanto tempo esse hash completo específico precisa ser considerado não seguro pelo cliente. Após o término da duração do cache ThreatMatch, o cliente precisa atualizar o hash completo emitindo uma solicitação fullHashes para esse prefixo de hash, caso o URL solicitado corresponda ao hash completo existente no cache. Nesse caso, a duração negativa do cache não se aplica. A duração do cache negativo da resposta se aplica apenas
a hashes completos que não estavam presentes na resposta fullHashes. Para hashes completos que
não estiverem presentes na resposta, o cliente precisará não emitir solicitações fullHashes
até que a duração do cache negativo seja atingida.
Exemplo: fullHashes.find
Clique nos links de solicitação e resposta no cabeçalho da tabela para ver exemplos completos.
| Prefixos de hash solicitação fullHashes |
Correspondências de hash completas Resposta de fullHashes |
Comportamento de armazenamento em cache |
|---|---|---|
"threatEntries": [
{"hash": "0xaaaaaaaa"}
]
|
"matches": [], "negativeCacheDuration": "3600.000s" |
Nenhuma correspondência. O cliente não pode enviar solicitações fullHashes para o prefixo de hash 0xaaaaaaaa por pelo menos uma hora.
Qualquer hash com o prefixo 0xaaaaaaaa é considerado seguro por uma hora. |
"threatEntries": [
{"hash": "0xbbbbbbbb"}
]
|
"matches": [
"threat": {"hash": "0xbbbbbbbb0000..."}
"cacheDuration": "600.000s",
],
"negativeCacheDuration": "300.000s"
|
Possíveis correspondências. O cliente precisa considerar o URL com o hash completo 0xbbbbbb0000... não seguro por 10 minutos. O cliente deve considerar como seguros todos os outros URLs com o prefixo hash 0xbbbbbbbb por cinco minutos. Após cinco minutos, a entrada de cache negativo dos prefixos de hash expira. Como a entrada positiva de cache para 0xbbbbbb0000... ainda não expirou, o cliente precisa enviar solicitações fullHashes para todos os hashes,
exceto esse. |
"threatEntries": [
{"hash": "0xcccccccc"}
]
|
"matches": [
"threat": {"hash": "0xccccccccdddd..."},
"cacheDuration": "600.000s"
],
"negativeCacheDuration": "3600.000s"
|
Possíveis correspondências. O cliente não pode enviar nenhuma solicitação fullHashes para o prefixo de hash 0xccgpcs por pelo menos 1h e presumir
que esse prefixo é seguro, exceto se o hash completo do URL corresponder ao hash completo 0xresourcemanagerresourcemanagerccdddd.... Nesse caso, o cliente deve considerar esse URL como não seguro por 10 minutos.
Após 10 minutos, o hash completo expira. Outras pesquisas posteriores para esse hash completo devem acionar uma nova solicitação fullHashes. |