Migration From V4

Uma melhoria significativa do Google Safe Browsing v5 em relação à v4 (especificamente, a API Update v4) é a atualização e a cobertura dos dados. Como a proteção depende muito do banco de dados local mantido pelo cliente, o atraso e o tamanho da atualização do banco de dados local são os principais fatores que contribuem para a proteção perdida. Na v4, o cliente típico leva de 20 a 50 minutos para receber a versão mais atualizada das listas de ameaças. Infelizmente, os ataques de phishing se espalham rapidamente. Em 2021, 60% dos sites que realizam ataques ficam ativos por menos de 10 minutos. Nossa análise mostra que cerca de 25 a 30% da proteção contra phishing ausente se deve a essa defasagem de dados. Além disso, alguns dispositivos não estão equipados para gerenciar todas as listas de ameaças da Navegação Segura do Google, que continuam crescendo com o tempo.

Se você estiver usando a API Update v4, há um caminho de migração simples da v4 para a v5 sem precisar redefinir ou apagar o banco de dados local. Esta seção explica como fazer isso.

Atualizações da lista de conversão

Ao contrário da V4, em que as listas são identificadas pela tupla de tipo de ameaça, tipo de plataforma e tipo de entrada de ameaça, na V5, elas são identificadas apenas pelo nome. Isso oferece flexibilidade quando várias listas da v5 podem compartilhar o mesmo tipo de ameaça. Os tipos de plataforma e de entrada de ameaça foram removidos na v5.

Na v4, é usado o método threatListUpdates.fetch para fazer o download de listas. Na v5, é preciso mudar para o método hashLists.batchGet.

Faça as seguintes mudanças na solicitação:

  1. Remova o objeto ClientInfo v4 por completo. Em vez de fornecer a identificação de um cliente usando um campo dedicado, use o cabeçalho User-Agent conhecido. Embora não haja um formato prescrito para fornecer a identificação do cliente nesse cabeçalho, sugerimos incluir o ID do cliente e a versão do cliente originais separados por um espaço ou uma barra.
  2. Para cada objeto ListUpdateRequest da v4: * Procure o nome da lista correspondente da v5 em listas disponíveis e forneça esse nome na solicitação da v5.
    • Remova campos desnecessários, como threat_entry_type ou platform_type.
    • O campo state na v4 é diretamente compatível com o campo versions na v5. A mesma string de bytes que seria enviada ao servidor usando o campo state na v4 pode ser enviada na v5 usando o campo versions.
    • Para as restrições da v4, a v5 usa uma versão simplificada chamada SizeConstraints. Outros campos, como region, precisam ser descartados.

As seguintes mudanças precisam ser feitas na resposta:

  1. A enumeração ResponseType da v4 foi substituída por um campo booleano chamado partial_update.
  2. O campo minimum_wait_duration agora pode ser zero ou omitido. Se for, o cliente vai precisar fazer outra solicitação imediatamente. Isso só acontece quando o cliente especifica em SizeConstraints uma restrição menor no tamanho máximo da atualização do que o tamanho máximo do banco de dados.
  3. A lógica para decodificar hashes codificados com Rice-Golomb exige dois ajustes principais:
    • Endianness e classificação:na v4, os hashes retornados eram classificados como valores little-endian. Na v5, eles são tratados como valores big-endian. Como a classificação lexicográfica de strings de bytes é equivalente à classificação numérica de valores big-endian, os clientes não precisam mais realizar uma etapa especial de classificação. A classificação little-endian personalizada, como a da implementação do Chromium v4, pode ser removida se tiver sido implementada anteriormente.
    • Comprimentos de hash variáveis:o algoritmo de decodificação precisa ser atualizado para oferecer suporte a vários comprimentos de hash que podem ser retornados no campo HashList.compressed_additions, não apenas o comprimento de hash de quatro bytes usado na v4. O comprimento dos hashes retornados na resposta pode ser determinado com base no HashList.metadata.hash_length retornado de hashLists.list. Como alternativa, o nome da lista de hash solicitada também indica os tamanhos de hash esperados retornados da lista. Consulte a página Banco de dados local para mais detalhes sobre as listas de hash.

Pesquisas de hash de conversão

Na v4, é possível usar o método fullHashes.find para receber hashes completos. O método equivalente na v5 é hashes.search.

Faça as seguintes mudanças na solicitação:

  1. Estruture o código para enviar apenas prefixos de hash com exatamente 4 bytes de comprimento.
  2. Remova todos os objetos ClientInfo da v4. Em vez de fornecer a identificação de um cliente usando um campo dedicado, use o cabeçalho User-Agent conhecido. Embora não haja um formato prescrito para fornecer a identificação do cliente nesse cabeçalho, sugerimos incluir o ID do cliente e a versão do cliente originais separados por um espaço ou uma barra.
  3. Remova o campo client_states. Ela não é mais necessária.
  4. Não é mais necessário incluir threat_types e campos semelhantes.

As seguintes mudanças precisam ser feitas na resposta:

  1. O campo minimum_wait_duration foi removido. O cliente pode sempre emitir uma nova solicitação conforme necessário.
  2. O objeto ThreatMatch v4 foi simplificado no objeto FullHash.
  3. O armazenamento em cache foi simplificado em uma única duração. Consulte os procedimentos acima para interagir com o cache.