Este documento se aplica aos seguintes métodos:
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.
| Verificação de URL Solicitação threatMatches |
Correspondência de URL Resposta dethreatMatches |
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
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
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.
| Prefixos de hash Solicitação fullHashes |
Correspondências de hash completos Resposta fullHashes |
Comportamento de armazenamento em cache |
|---|---|---|
"threatEntries": [
{"hash": "0xaaaaaaaa"}
]
|
"matches": [], "negativeCacheDuration": "3600.000s" |
Nenhuma correspondência. O cliente não deve enviar solicitações fullHashes para o prefixo 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 deve considerar o URL com o hash completo 0xbbbbbbbb0000... inseguro por 10 minutos. A o cliente deve considerar todos os outros URLs com o prefixo hash 0xbbbbbbbb como seguros por cinco minutos. Após as 17h minutos, a entrada de cache negativo dos prefixos hash vai expirar. Como a entrada positiva no cache do 0xbbbbbbbb0000... ainda não tenha expirado, 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 deve enviar nenhuma solicitação fullHashes para o prefixo de hash 0xch quandofccc por pelo menos 1h e assumir
esse prefixo seja seguro, exceto se o hash completo do URL corresponder ao hash completo armazenado em cache.
Nesse caso, o cliente deve considerar esse URL não seguro por 10 minutos.
Após 10 minutos, o hash completo expira. As pesquisas subsequentes desse hash completo devem
acionar uma nova solicitação fullHashes. |