Armazenamento em cache

Este documento se aplica aos seguintes métodos:

• API Lookup: uris.search
• API Update: hashes.search

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 da API Lookup e da API Update precisam criar e manter um cache local de dados de ameaças. A API Lookup usa o cache para reduzir o número de solicitações uris.search que os clientes enviam ao Google. Para a API Update, o cache é usado para reduzir o número de solicitações hashes.search que os clientes enviam ao Google. O protocolo de armazenamento em cache para cada API está descrito abaixo.

API Lookup

Os clientes da API Lookup devem armazenar em cache cada item ThreatUrl retornado até o horário definido no campo expireTime. Os clientes precisam consultar o cache antes de fazer uma solicitação uris.search subsequente ao servidor. Se a entrada de cache de um ThreatUrl retornado anteriormente ainda não expirou, o cliente deve presumir que o item ainda não é seguro. Armazenar em cache itens ThreatUrl pode reduzir o número de solicitações de API feitas pelo cliente.

API Update

Para reduzir o número total de solicitações hashes.search 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, cada ThreatHash retornado contém um tempo de cache positivo (definido pelo campo expireTime). O hash completo pode ser considerado não seguro até o momento.

Armazenamento em cache negativo

Para evitar que os clientes perguntem repetidamente sobre o estado de um determinado hash seguro, a resposta define uma duração de cache negativa para o prefixo solicitado (definido pelo campo negativeExpireTime). Todos os hashes completos com o prefixo solicitado devem ser considerados seguros para os tipos de ameaças solicitados até o momento, exceto aqueles retornados pelo servidor como não seguros. Esse armazenamento em cache é particularmente importante porque evita sobrecarga de tráfego que pode ser causada por uma colisão de prefixo 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, ele primeiro calcula o hash completo. Se o prefixo completo do hash estiver presente no banco de dados local, o cliente deverá consultar o cache antes de fazer uma solicitação hashes.search 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 de interesse completo, ela deverá ser considerada não segura. Se a entrada de cache positivo tiver expirado, o cliente precisará enviar uma solicitação hashes.search 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, ela será considerada segura.

Se não houver entradas de cache positivas para o hash completo, o cliente deverá verificar se há um hit de cache negativo. 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 hashes.search 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 hashes.search é recebida. Uma entrada de cache positiva deve ser criada ou atualizada para o hash completo de acordo com o campo expireTime. A duração do cache negativo do prefixo de hash também precisa ser criada ou atualizada de acordo com o campo negativeExpireTime da resposta.

Se uma solicitação hashes.search subsequente não retornar um hash completo atualmente armazenado em cache, o cliente não precisará remover a entrada de cache positiva. Isso não é motivo para preocupação na prática, já que as durações de cache positivas normalmente 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).

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 hash h(example.com/) e recebe de volta o hash H(example.com/) completo com um tempo de expiração positivo de cache de cinco minutos a partir de agora e um cache negativo expira hora de 1 hora a partir de agora.

A duração positiva do cache de cinco minutos informa ao cliente por quanto tempo o hash H(example.com/) completo precisa ser considerado não seguro sem enviar outra solicitação hashes.search. Após cinco minutos, o cliente precisará emitir outra solicitação hashes.search para esse prefixo h(example.com/) se o cliente visitar example.com/ novamente. O cliente deve redefinir o tempo de expiraçã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. Durante uma hora, todos os URLs de modo que h(URL) = h(exemplo.com/) devem ser considerados seguros e, portanto, não resultar em uma solicitação hashes.search (presumindo que H(URL)!= H(example.com/)).

Se a resposta fullHashes contiver zero correspondências e um tempo de expiração de cache negativo for definido, o cliente não poderá emitir solicitações hashes.search para nenhum dos prefixos solicitados para o tempo de cache negativo fornecido.

Se a resposta hashes.search contiver uma ou mais correspondências, um tempo de expiração em cache negativo ainda será definido para toda a resposta. Nesse caso, o tempo de expiração do cache de um único hash completo indica por quanto tempo o cliente precisa presumir que o hash completo não é seguro. Depois que a duração do cache ThreatHash terminar, o cliente precisará atualizar o hash completo enviando uma solicitação hashes.search 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 aplica. A duração do cache negativo da resposta só se aplica a hashes de comprimento total que não estavam presentes na resposta hashes.search. Para hashes completos que não estão presentes na resposta, o cliente precisa evitar a emissão de solicitações hashes.search até que a duração do cache negativo seja encerrada.