A colocar em cache

Este documento aplica-se aos seguintes métodos:

Acerca da colocação em cache

Para reduzir a utilização da largura de banda do cliente e proteger a Google contra picos de tráfego, os clientes da API Lookup e da API Update têm de criar e manter uma cache local de dados de ameaças. A API Lookup usa a cache para reduzir o número de uris.search pedidos que os clientes enviam para a Google. Para a API Update, a cache é usada para reduzir o número de hashes.search pedidos que os clientes enviam para a Google. O protocolo de colocação em cache para cada API é descrito abaixo.

API Lookup

Os clientes da API Lookup devem colocar em cache cada item ThreatUrl devolvido até à hora definida no campo expireTime. Em seguida, os clientes têm de consultar a cache antes de fazer um pedido uris.search subsequente ao servidor. Se a entrada da cache de um ThreatUrl devolvido anteriormente ainda não tiver expirado, o cliente deve assumir que o artigo ainda não é seguro. O armazenamento em cache de ThreatUrlitens pode reduzir o número de pedidos de API feitos pelo cliente.

API Update

Para reduzir o número total de pedidos hashes.search enviados para a Google através da API Update, os clientes têm de manter uma cache local. A API estabelece dois tipos de colocação em cache: positiva e negativa.

Colocação em cache positiva

Para impedir que os clientes perguntem repetidamente sobre o estado de um hash completo não seguro específico, cada ThreatHash devolvido contém um tempo de cache positivo (definido pelo campo expireTime). O hash completo pode ser considerado inseguro até esta altura.

Colocação em cache negativa

Para impedir que os clientes perguntem repetidamente sobre o estado de um hash completo seguro específico, a resposta define uma duração da cache negativa para o prefixo pedido (definido pelo campo negativeExpireTime). Todos os hashes completos com o prefixo pedido devem ser considerados seguros para os tipos de ameaças pedidos até esta hora, exceto os devolvidos pelo servidor como não seguros. Esta colocação em cache é particularmente importante, uma vez que 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.

Consultar a cache

Quando o cliente quer verificar o estado de um URL, calcula primeiro o respetivo hash completo. Se o prefixo do hash completo estiver presente na base de dados local, o cliente deve consultar a respetiva cache antes de fazer um pedido hashes.search ao servidor.

Primeiro, os clientes devem verificar se existe um resultado positivo na cache. Se existir uma entrada de cache positiva não expirada para o hash completo do interesse, deve ser considerada não segura. Se a entrada de cache positiva tiver expirado, o cliente tem de enviar um pedido hashes.search para o prefixo local associado. De acordo com o protocolo, se o servidor devolver o hash completo, é considerado inseguro; caso contrário, é considerado seguro.

Se não existirem entradas de cache positivas para o hash completo, o cliente deve verificar se existe um resultado de cache negativo. Se existir uma entrada de cache negativa não expirada para o prefixo local associado, o hash completo é considerado seguro. Se a entrada de cache negativa tiver expirado ou não existir, o cliente tem de enviar um pedido hashes.search para o prefixo local associado e interpretar a resposta como normal.

A atualizar a cache

A cache do cliente deve ser atualizada sempre que for recebida uma resposta hashes.search. Deve ser criada ou atualizada uma entrada de cache positiva para o hash completo de acordo com o campo expireTime. A duração da cache negativa do prefixo hash também deve ser criada ou atualizada de acordo com o campo negativeExpireTime da resposta.

Se um pedido hashes.search subsequente não devolver um hash completo que esteja atualmente em cache de forma positiva, o cliente não tem de remover a entrada de cache positiva. Na prática, isto não é motivo de preocupação, uma vez que as durações da cache positivas são normalmente curtas (alguns minutos) para permitir uma correção rápida de falsos positivos.

Cenário de exemplo

No exemplo seguinte, suponha que h(url) é o prefixo de hash do URL e H(url) é o hash de comprimento total do URL. Ou seja, h(url) = SHA256(url).substr(4), H(url) = SHA256(url).

Suponhamos que um cliente com uma cache vazia visita example.com/ e vê que h(example.com/) está na base de dados local. O cliente pede os hashes de comprimento total para o prefixo de hash h(example.com/) e recebe o hash de comprimento total H(example.com/) juntamente com um tempo de expiração da cache positivo de 5 minutos a partir de agora e um tempo de expiração da cache negativo de 1 hora a partir de agora.

A duração da cache positiva de 5 minutos indica ao cliente durante quanto tempo o hash de comprimento total H(example.com/) tem de ser considerado não seguro sem enviar outro pedido hashes.search. Após 5 minutos, o cliente tem de emitir outro pedido hashes.search para esse prefixo h(example.com/) se o cliente visitar example.com/ novamente. O cliente deve repor o tempo de expiração da cache negativa do prefixo de hash de acordo com a nova resposta.

A duração da cache negativa de 1 hora indica ao cliente durante quanto tempo todos os outros hashes de comprimento total, além de H(example.com/), que partilham o mesmo prefixo de h(example.com/) têm de ser considerados seguros. Durante 1 hora, todos os URLs tais que h(URL) = h(example.com/) têm de ser considerados seguros e, por isso, não resultar num pedido hashes.search (assumindo que H(URL) != H(example.com/)).

Se a resposta fullHashes contiver zero correspondências e for definido um tempo de expiração da cache negativo, o cliente não deve emitir pedidos hashes.search para nenhum dos prefixos pedidos durante o tempo de cache negativo indicado.

Se a resposta hashes.search contiver uma ou mais correspondências, continua a ser definido um tempo de expiração da cache negativo para toda a resposta. Nesse caso, o tempo de expiração da cache de um único hash completo indica durante quanto tempo o cliente tem de assumir que o hash completo específico é inseguro. Após o decurso da ThreatHashduração da cache hashes.search, o cliente tem de atualizar o hash de comprimento total emitindo um pedido hashes.searchpara esse prefixo de hash se o URL pedido corresponder ao hash de comprimento total existente na cache. Nesse caso, a duração da cache negativa não se aplica. A duração da cache negativa da resposta aplica-se apenas aos hashes de comprimento total que não estavam presentes na resposta hashes.search. Para hashes de comprimento total que não estejam presentes na resposta, o cliente tem de se abster de emitir pedidos até que a duração da cache negativa termine.hashes.search