Overview

Atualização de dados

Uma melhoria significativa da Navegação segura do Google v5 em relação à v4 (especificamente, a API v4 Update) é a atualização e a cobertura de 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 responsáveis pela proteção perdida. Na v4, o cliente típico leva de 20 a 50 minutos para obter a versão mais atualizada das listas de ameaças. Infelizmente, os ataques de phishing se espalham rapidamente: em 2021, 60% dos sites que entregam ataques duravam menos de 10 minutos. Nossa análise mostra que cerca de 25 a 30% da proteção contra phishing ausente se deve à inatividade dos dados. Além disso, alguns dispositivos não são equipados para gerenciar toda as listas de ameaças da Navegação segura do Google, que continuam a crescer ao longo do tempo.

Na v5, introduzimos um modo de operação conhecido como proteção em tempo real. Isso evita o problema de desatualização dos dados acima. Na v4, os clientes devem baixar e manter um banco de dados local, executar verificações nas listas de ameaças baixadas localmente e, quando houver uma correspondência parcial de prefixo, executar uma solicitação para baixar o hash completo. Na v5, embora os clientes devam continuar a fazer download e manter um banco de dados local de listas de ameaças, os clientes agora também devem fazer download de uma lista de sites provavelmente benignos (chamado de Cache global), executar tanto uma verificação local para esse cache global quanto uma verificação de lista de ameaças local e, finalmente, quando houver uma correspondência parcial de prefixo para listas de ameaças ou uma falta de correspondência no Cache global, execute uma solicitação para baixar os hashes completos. Para detalhes sobre o processamento local exigido pelo cliente, consulte o procedimento fornecido abaixo. Isso representa uma mudança de permitir por padrão para verificação por padrão, o que pode melhorar a proteção considerando a propagação mais rápida das ameaças na Web. Em outras palavras, esse é um protocolo criado para oferecer proteção quase em tempo real: queremos que os clientes se beneficiem de dados mais recentes da Navegação segura do Google.

Privacidade de IP

A Navegação segura do Google (v4 ou v5) não processa nada associado à identidade de um usuário durante as solicitações de veiculação. Os cookies, se enviados, são ignorados. O Google conhece os endereços IP de origem das solicitações, mas eles só são usados para necessidades essenciais de rede (por exemplo, para enviar respostas) e anti-DoS.

Simultaneamente à v5, introduzimos uma API complementar conhecida como API Safe Browsing Oblivious HTTP Gateway. Ele usa o Oblivious HTTP para ocultar o endereço endereços IP do Google. Ele funciona com um terceiro não parceiro para lidar com uma versão criptografada da solicitação do usuário e encaminhá-la ao Google. Assim, o terceiro só tem acesso aos endereços IP, e o Google só tem acesso ao conteúdo da solicitação. O terceiro opera um Oblivious HTTP Relay (como este serviço da Fastly), e o Google opera o Oblivious HTTP Gateway. Esta é uma API complementar opcional. Ao usá-lo em conjunto com a Navegação segura do Google, os usuários finais Os endereços IP não são mais enviados ao Google.

Uso permitido

A API Safe Browsing é somente para uso não comercial, ou seja, “não está disponível para venda ou geração de receita”. Se você precisar de uma solução para fins comerciais, consulte Web Risk.

Preços

Todas as APIs Google Safe Browsing são sem custo financeiro.

Cotas

Os desenvolvedores recebem uma cota de uso padrão ao ativar a API Safe Browsing. A alocação e o uso atuais podem ser visualizados no Google Developer Console. Se você espera usar mais do que sua cota alocada atualmente, solicite uma cota adicional na interface de cotas do Play Console. Analisamos essas solicitações e solicitamos um contato quando solicitamos o aumento da cota para garantir que a disponibilidade do nosso serviço atenda às necessidades de todos os usuários.

URLs apropriados

A Navegação segura do Google foi desenvolvida para atuar em URLs que seriam exibidos na barra de endereço de um navegador. Ele não foi projetado para ser usado para verificar sub-recursos (como um JavaScript ou uma imagem referenciada por um arquivo HTML ou um URL WebSocket iniciado pelo JavaScript). Esses URLs de sub-recursos não devem ser verificados na Navegação segura do Google.

Se a visita a um URL resultar em um redirecionamento (como HTTP 301), é recomendável que o URL redirecionado seja verificado no recurso Navegação segura do Google. A manipulação de URL do lado do cliente, como History.pushState, não faz com que novos URLs sejam comparados com a Navegação segura do Google.

Avisos de usuário

Se você usa a Navegação segura do Google para avisar os usuários sobre os riscos de páginas da Web específicas, siga as diretrizes a seguir.

Essas diretrizes ajudam a proteger você e o Google contra mal-entendidos, deixando claro que a página não é 100% conhecida como um recurso da Web não seguro e que os avisos apenas identificam possíveis riscos.

• No aviso visível ao usuário, não é permitido induzir os usuários a acreditar que a página em questão é, sem dúvida, um recurso da Web não seguro. Ao se referir à página que está sendo identificada ou aos possíveis riscos que ela pode representar aos usuários, você precisa qualificar o aviso usando termos como: suspeito, possivelmente, possível, provável.
• Seu aviso precisa permitir que o usuário saiba mais revisando a definição do Google de diversas ameaças. Os links a seguir são sugeridos:
  • Engenharia social: https://developers.google.com/search/docs/monitor-debug/security/social-engineering
  • Malware e software indesejado: https://developers.google.com/search/docs/monitor-debug/security/malware
  • Apps potencialmente nocivos (somente no Android): https://developers.google.com/android/play-protect/potentially-harmful-applications
• Ao exibir avisos para páginas identificadas como de risco pelo serviço Navegação segura, você precisa dar crédito ao Google incluindo a linha "Consultoria fornecida pelo Google". com um link para o Aviso de Navegação segura. Caso seu produto também mostre avisos com base em outras origens, não inclua a atribuição do Google em avisos derivados de dados que não são do Google.

• Na documentação do produto, é necessário incluir um aviso para informar aos usuários que a proteção oferecida pela Navegação segura do Google não é perfeita. Ele precisa informar que existe a possibilidade de falsos positivos (sites seguros sinalizados como de risco) e falsos negativos (sites de risco não sinalizados). Sugerimos usar o seguinte idioma:

  O Google trabalha para fornecer as informações mais precisas e atualizadas sobre recursos da Web não seguros. No entanto, o Google não pode garantir que suas informações sejam abrangentes e livres de erros: alguns sites perigosos podem não ser identificados e alguns sites seguros podem ser identificados por engano.

Modo em tempo real

Quando os clientes optam por usar a Navegação segura do Google v5 no modo em tempo real, os clientes mantêm em seu banco de dados local: (i) um cache global de sites provavelmente benignos, formatados como hashes SHA256 de expressões de URL com sufixo de host/prefixo de caminho, (ii) um conjunto de listas de ameaças, formatados como prefixos de hash SHA256 de expressões de URL com sufixo de host/prefixo de caminho. A ideia geral é que sempre que o cliente quer verificar um URL específico, uma verificação local é realizada usando o cache global. Se essa verificação for aprovada, uma verificação das listas de ameaças locais será realizada. Caso contrário, o cliente continuará com a verificação de hash em tempo real, conforme detalhado abaixo.

Além do banco de dados local, o cliente vai manter um cache local. Esse cache local não precisa estar em armazenamento persistente e pode ser apagado em caso de pressão de memória.

Veja abaixo uma especificação detalhada do procedimento.

Modo de lista local

Quando os clientes optam por usar a Navegação segura do Google v5 nesse modo, o comportamento do cliente é semelhante ao da API Update v4, exceto pelo uso da superfície de API aprimorada da v5. Os clientes manterão em seu banco de dados local um conjunto de listas de ameaças formatadas como prefixos de hash SHA256 de expressões de URL com sufixo host/prefixo de caminho. Sempre que o cliente deseja verificar um determinado URL, uma verificação é realizada usando a lista de ameaças locais. Somente se houver uma correspondência, o cliente se conectará ao servidor para continuar a verificação.

Como no caso acima, o cliente também vai manter um cache local que não precisa estar no armazenamento persistente.

Modo em tempo real sem armazenamento

Quando os clientes optam por usar a Navegação segura do Google v5 no modo em tempo real sem armazenamento, eles não precisam manter nenhum banco de dados local persistente. No entanto, ainda se espera que o cliente mantenha um cache local. Esse cache local não precisa estar em armazenamento persistente e pode ser apagado em caso de pressão de memória.

Sempre que o cliente quer verificar um URL específico, ele se conecta ao servidor para realizar a verificação. Esse modo é semelhante ao que os clientes da API Lookup v4 podem implementar.

Comparado com o modo em tempo real, esse modo pode usar mais largura de banda da rede, mas pode ser mais adequado se for inconveniente para o cliente manter o estado local persistente.

Canonização de URLs

Antes da verificação dos URLs, o cliente deve realizar uma canonização nesse URL.

Para começar, presumimos que o cliente analisou o URL e o tornou válido de acordo com o RFC 2396. Se o URL usar um nome de domínio internacionalizado (IDN, na sigla em inglês), o cliente precisa converter o URL para a representação ASCII do Punycode. O URL precisa incluir um componente de caminho. ou seja, precisa ter pelo menos uma barra depois do domínio (http://google.com/ em vez de http://google.com).

Primeiro, remova os caracteres tab (0x09), CR (0x0d) e LF (0x0a) do URL. Não remova sequências de escape para esses caracteres (por exemplo, %0a).

Segundo, se o URL terminar em um fragmento, remova o fragmento. Por exemplo, reduza http://google.com/#frag para http://google.com/.

Terceiro, remova a porcentagem de escape do URL repetidamente até que ele não tenha mais percentuais de escape. Isso pode tornar o URL inválido.

Para canonizar o nome do host:

Extraia o nome do host do URL e:

1. Remova todos os pontos iniciais e finais.
2. Substitua os pontos consecutivos por um único ponto.
3. Se o nome do host puder ser analisado como um endereço IPv4, normalize-o para valores decimais separados por quatro pontos. O cliente deve lidar com qualquer codificação legal de endereço IP, incluindo octal, hexadecimal e menos de quatro componentes.
4. Se o nome do host puder ser analisado como um endereço IPv6 entre colchetes, normalize-o removendo zeros à esquerda desnecessários nos componentes e recolhendo os componentes zero usando a sintaxe de dois-pontos. Por exemplo, [2001:0db8:0000::1] precisa ser transformado em [2001:db8::1]. Se o nome do host for um dos dois tipos de endereços IPv6 especiais a seguir, transforme-os em IPv4:
   • Um endereço IPv6 mapeado para IPv4, como [::ffff:1.2.3.4], que precisa ser transformado em 1.2.3.4.
   • Um endereço NAT64 usando o prefixo conhecido 64:ff9b::/96, como [64:ff9b::1.2.3.4], que precisa ser transformado em 1.2.3.4.
5. Minúsculas a string inteira.

Para canonizar o caminho:

1. Resolva as sequências /../ e /./ no caminho substituindo /./ por / e removendo /../ com o componente de caminho anterior.
2. Substitua execuções de barras consecutivas por uma única barra.

Não aplique essas canonizações de caminho aos parâmetros de consulta.

No URL, faça o escape percentual de todos os caracteres que sejam <= ASCII 32, >= 127, # ou %. Os escape devem usar caracteres hexadecimais em maiúsculas.

Expressões de prefixo de caminho do sufixo do host

Depois de canonizar o URL, a próxima etapa é criar as expressões de sufixo/prefixo. Cada expressão de sufixo/prefixo consiste em um sufixo de host (ou host completo) e um prefixo de caminho (ou caminho completo).

O cliente vai formar até 30 possíveis combinações diferentes de sufixos de host e prefixo de caminho. Essas combinações usam apenas os componentes de host e caminho do URL. O esquema, o nome de usuário, a senha e a porta são descartados. Se o URL incluir parâmetros de consulta, pelo menos uma combinação incluirá o caminho completo e os parâmetros de consulta.

Para o host, o cliente tentará no máximo cinco strings diferentes. São eles:

• Se o nome do host não for um literal IPv4 ou IPv6, até quatro nomes de host serão formados começando com o domínio eTLD+1 e adicionando componentes principais sucessivos. A determinação de eTLD+1 precisa ser baseada na lista de sufixos públicos. Por exemplo, a.b.example.com resultaria no domínio eTLD+1 de example.com, bem como no host com um componente de host b.example.com extra.
• O nome do host exato no URL. Seguindo o exemplo anterior, a.b.example.com seria verificado.

Para o caminho, o cliente tentará no máximo seis strings diferentes. Elas são:

• O caminho exato do URL, incluindo os parâmetros de consulta.
• O caminho exato do URL, sem parâmetros de consulta.
• Os quatro caminhos formados começando na raiz (/) e anexando sucessivamente os componentes do caminho, incluindo uma barra final.

Os exemplos a seguir ilustram o comportamento da verificação:

Para o URL http://a.b.com/1/2.html?param=1, o cliente tentará estas strings possíveis:

a.b.com/1/2.html?param=1
a.b.com/1/2.html
a.b.com/
a.b.com/1/
b.com/1/2.html?param=1
b.com/1/2.html
b.com/
b.com/1/

Para o URL http://a.b.c.d.e.f.com/1.html, o cliente tentará estas strings possíveis:

a.b.c.d.e.f.com/1.html
a.b.c.d.e.f.com/
c.d.e.f.com/1.html
c.d.e.f.com/
d.e.f.com/1.html
d.e.f.com/
e.f.com/1.html
e.f.com/
f.com/1.html
f.com/

Observação: ignore b.c.d.e.f.com, já que usaremos apenas os últimos cinco componentes e o nome do host completo.

Para o URL http://1.2.3.4/1/, o cliente tentará estas strings possíveis:

1.2.3.4/1/
1.2.3.4/

Para o URL http://example.co.uk/1, o cliente tentará estas strings possíveis:

example.co.uk/1
example.co.uk/

Hash

A Navegação segura do Google usa exclusivamente SHA256 como função hash. Essa função de hash precisa ser aplicada às expressões acima.

Dependendo das circunstâncias, o hash completo de 32 bytes será truncado para 4, 8 ou 16 bytes:

• No momento, ao usar o método hashes.search, exigimos que os hashes na solicitação sejam truncados para exatamente quatro bytes. O envio de mais bytes nessa solicitação vai comprometer a privacidade do usuário.

• Ao fazer o download das listas para o banco de dados local usando o método hashList.get ou o método hashLists.batchGet, o comprimento dos hashes enviados pelo servidor é influenciado pela natureza da lista e pela preferência do cliente em relação ao tamanho do hash, comunicada pelo parâmetro desired_hash_length.

Procedimento de verificação de URL em tempo real

Esse procedimento é usado quando o cliente escolhe o modo de operação em tempo real.

Esse procedimento usa um único URL u e retorna SAFE, UNSAFE ou UNSURE. Se retornar SAFE, o URL será considerado seguro pela Navegação segura do Google. Se ele retornar UNSAFE, o URL será considerado potencialmente inseguro pela Navegação segura do Google, e as medidas adequadas serão tomadas, como mostrar um aviso ao usuário final, mover uma mensagem recebida para a caixa de spam ou exigir uma confirmação extra do usuário antes de continuar. Se ele retornar UNSURE, o procedimento de verificação local a seguir precisará ser usado depois.

1. Permita que expressions seja uma lista de expressões de sufixo/prefixo gerada pelo URL u.
2. Permita que expressionHashes seja uma lista, em que os elementos são hashes SHA256 de cada expressão em expressions.
3. Para cada hash de expressionHashes:
   1. Se hash puder ser encontrado no cache global, retorne UNSURE.
4. Permita que expressionHashPrefixes seja uma lista, em que os elementos são os primeiros 4 bytes de cada hash em expressionHashes.
5. Para cada expressionHashPrefix de expressionHashPrefixes:
   1. Procure expressionHashPrefix no cache local.
   2. Se a entrada em cache for encontrada:
      1. Determine se a hora atual é maior que o prazo de validade.
      2. Se for maior:
         1. Remova a entrada encontrada em cache do cache local.
         2. Continue com o loop.
      3. Se não for maior:
         1. Remova esse expressionHashPrefix específico de expressionHashPrefixes.
         2. Verifique se o hash completo correspondente em expressionHashes é encontrado na entrada em cache.
         3. Se encontrado, retorna UNSAFE.
         4. Se não encontrar, continue com o loop.
   3. Se a entrada em cache não for encontrada, continue com o loop.
6. Envie expressionHashPrefixes ao servidor da Navegação segura do Google v5 usando RPC SearchHashes ou o método REST hashes.search. Se ocorrer um erro (incluindo erros de rede, de HTTP etc.), retorne UNSURE. Caso contrário, permita que a resposta seja a response recebida do servidor SB, que é uma lista de hashes completos com algumas informações auxiliares que identificam a natureza da ameaça (engenharia social, malware etc.), bem como o prazo de validade do cache expiration.
7. Para cada fullHash de response:
   1. Insira fullHash no cache local com expiration.
8. Para cada fullHash de response:
   1. Permita que isFound seja o resultado da descoberta de fullHash em expressionHashes.
   2. Se isFound for falso, continue com a repetição.
   3. Se isFound for "True", retorna UNSAFE.
9. Retorne o SAFE.

Embora ele especifique quando o cliente enviará expressionHashPrefixes ao servidor, ele intencionalmente não especifica como fazer o envio. Por exemplo, o cliente pode enviar todos os expressionHashPrefixes em uma única solicitação e cada prefixo individual em expressionHashPrefixes para o servidor em solicitações separadas, talvez continue em paralelo. Também é aceitável que o cliente envie prefixos de hash não relacionados ou gerados aleatoriamente com os prefixos de hash em expressionHashPrefixes, desde que o número de prefixos de hash enviados em uma única solicitação não exceda 30.

O procedimento de verificação de URL da lista de LocalThreat

Esse procedimento é usado quando o cliente opta pelo modo de operação de lista local. Ele também é usado quando o cliente o procedimento RealTimeCheck acima retorna o valor de UNSURE.

Esse procedimento usa um único URL u e retorna SAFE ou UNSAFE.

1. Permita que expressions seja uma lista de expressões de sufixo/prefixo gerada pelo URL u.
2. Permita que expressionHashes seja uma lista, em que os elementos são hashes SHA256 de cada expressão em expressions.
3. Permita que expressionHashPrefixes seja uma lista, em que os elementos são os primeiros 4 bytes de cada hash em expressionHashes.
4. Para cada expressionHashPrefix de expressionHashPrefixes:
   1. Procure expressionHashPrefix no cache local.
   2. Se a entrada em cache for encontrada:
      1. Determine se a hora atual é maior que o prazo de validade.
      2. Se for maior:
         1. Remova a entrada encontrada em cache do cache local.
         2. Continue com o loop.
      3. Se não for maior:
         1. Remova esse expressionHashPrefix específico de expressionHashPrefixes.
         2. Verifique se o hash completo correspondente em expressionHashes é encontrado na entrada em cache.
         3. Se encontrado, retorna UNSAFE.
         4. Se não encontrar, continue com o loop.
   3. Se a entrada em cache não for encontrada, continue com o loop.
5. Para cada expressionHashPrefix de expressionHashPrefixes:
   1. Procure expressionHashPrefix no banco de dados da lista de ameaças local.
   2. Se a expressionHashPrefix não for encontrada no banco de dados da lista de ameaças local, remova-a do expressionHashPrefixes.
6. Envie expressionHashPrefixes ao servidor da Navegação segura do Google v5 usando RPC SearchHashes ou o método REST hashes.search. Se ocorrer um erro (incluindo erros de rede, de HTTP etc.), retorne SAFE. Caso contrário, permita que a resposta seja a response recebida do servidor SB, que é uma lista de hashes completos com algumas informações auxiliares que identificam a natureza da ameaça (engenharia social, malware etc.), bem como o prazo de validade do cache expiration.
7. Para cada fullHash de response:
   1. Insira fullHash no cache local com expiration.
8. Para cada fullHash de response:
   1. Permita que isFound seja o resultado da descoberta de fullHash em expressionHashes.
   2. Se isFound for falso, continue com a repetição.
   3. Se isFound for "True", retorna UNSAFE.
9. Retorne o SAFE.

Procedimento de verificação de URL em tempo real sem um banco de dados local

Esse procedimento é usado quando o cliente escolhe o modo de operação em tempo real sem armazenamento.

Esse procedimento usa um único URL u e retorna SAFE ou UNSAFE.

1. Permita que expressions seja uma lista de expressões de sufixo/prefixo gerada pelo URL u.
2. Permita que expressionHashes seja uma lista, em que os elementos são hashes SHA256 de cada expressão em expressions.
3. Permita que expressionHashPrefixes seja uma lista, em que os elementos são os primeiros 4 bytes de cada hash em expressionHashes.
4. Para cada expressionHashPrefix de expressionHashPrefixes:
   1. Procure expressionHashPrefix no cache local.
   2. Se a entrada em cache for encontrada:
      1. Determine se a hora atual é maior que o prazo de validade.
      2. Se for maior:
         1. Remova a entrada encontrada em cache do cache local.
         2. Continue com o loop.
      3. Se não for maior:
         1. Remova esse expressionHashPrefix específico de expressionHashPrefixes.
         2. Verifique se o hash completo correspondente em expressionHashes é encontrado na entrada em cache.
         3. Se encontrado, retorna UNSAFE.
         4. Se não encontrar, continue com o loop.
   3. Se a entrada em cache não for encontrada, continue com o loop.
5. Envie expressionHashPrefixes ao servidor da Navegação segura do Google v5 usando RPC SearchHashes ou o método REST hashes.search. Se ocorrer um erro (incluindo erros de rede, de HTTP etc.), retorne SAFE. Caso contrário, permita que a resposta seja a response recebida do servidor SB, que é uma lista de hashes completos com algumas informações auxiliares que identificam a natureza da ameaça (engenharia social, malware etc.), bem como o prazo de validade do cache expiration.
6. Para cada fullHash de response:
   1. Insira fullHash no cache local com expiration.
7. Para cada fullHash de response:
   1. Permita que isFound seja o resultado da descoberta de fullHash em expressionHashes.
   2. Se isFound for falso, continue com a repetição.
   3. Se isFound for "True", retorna UNSAFE.
8. Retorne o SAFE.

Assim como o procedimento de verificação de URL em tempo real, esse não especifica exatamente como enviar os prefixos de hash ao servidor. Por exemplo, o cliente pode enviar todos os expressionHashPrefixes em uma única solicitação e cada prefixo individual em expressionHashPrefixes para o servidor em solicitações separadas, talvez continue em paralelo. Também é aceitável que o cliente envie prefixos de hash não relacionados ou gerados aleatoriamente com os prefixos de hash em expressionHashPrefixes, desde que o número de prefixos de hash enviados em uma única solicitação não exceda 30.

Atualizações do banco de dados

O cliente chama regularmente o método hashList.get ou o método hashLists.batchGet para atualizar o banco de dados. Como o cliente típico vai atualizar várias listas de uma só vez, é recomendável usar o método hashLists.batchGet.

As listas são identificadas por nomes distintos. Os nomes são strings ASCII curtas com alguns caracteres.

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, nas listas da v5 são simplesmente identificadas por nome. Isso proporciona 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.

Depois que um nome for escolhido para uma lista, ele nunca será renomeado. Além disso, depois que uma lista é exibida, ela nunca é removida. Se a lista não for mais útil, ficará vazia, mas continuará existindo. Portanto, é apropriado codificar esses nomes no código do cliente da Navegação segura do Google.

Os métodos hashList.get e hashLists.batchGet oferecem suporte a atualizações incrementais. O uso de atualizações incrementais economiza largura de banda e melhora o desempenho. Atualizações incrementais funcionam fornecendo um delta entre a versão da lista do cliente e a versão mais recente da lista. Se um cliente tiver sido implantado recentemente e não tiver versões disponíveis, uma atualização completa será disponibilizada. A atualização incremental contém adições e índices de remoção. Espera-se primeiro que o cliente remova as entradas nos índices especificados do banco de dados local e, em seguida, aplique as adições.

Por fim, para evitar corrupção, o cliente deve comparar os dados armazenados com a soma de verificação fornecida pelo servidor. Sempre que a soma de verificação não corresponder, o cliente deverá executar uma atualização completa.

Como decodificar o conteúdo da lista

291bc5421f1cd54d99afcc55d166e2b9fe42447025895bf09dd41b2110a687dc  a.example.com/
1d32c5084a360e58f1b87109637a6810acad97a861a7769e8f1841410d2a960c  b.example.com/
f7a502e56e8b01c6dc242b35122683c9d25d07fb1f532d9853eb0ef3ff334f03  y.example.com/

001110100010010011110110100011 # Second number, remainder part
0111 # Second number, quotient part
001011111010010000000000111010 # First number, remainder part
0 # First number, quotient part

00111010001001001111011010001101110010111110100100000000001110100

0 01110100 01001001 11101101 00011011 10010111 11010010 00000000 01110100

01110100
00000000
11010010
10010111
00011011
11101101
01001001
01110100
00000000

additions_four_bytes {
  first_value: 489866504
  rice_parameter: 30
  entries_count: 2
  encoded_data: "t\000\322\227\033\355It\000"
}

Listas disponíveis

As listas a seguir são recomendadas para uso na v5alpha1:

Mais listas vão ser disponibilizadas mais tarde, quando a tabela acima vai ser expandida.

O cliente pode operar um servidor proxy de cache para recuperar algumas ou todas as listas acima e, em seguida, fazer com que o cliente entre em contato com o servidor proxy. Se isso for implementado, recomendamos uma duração de cache curta, como cinco minutos; No futuro, essa duração do cache poderá ser comunicada usando o cabeçalho HTTP Cache-Control padrão.

Frequência de atualização

O cliente deve inspecionar o valor retornado do servidor no campo minimum_wait_duration e usá-lo para programar a próxima atualização do banco de dados. Esse valor é possivelmente zero (o campo minimum_wait_duration está completamente ausente). Nesse caso, o cliente DEVE fazer outra atualização imediatamente.

Convertendo atualizações de lista

Na v4, o método threatListUpdates.fetch é usado para fazer o download das listas. Na v5, é possível mudar para o método hashLists.batchGet.

As seguintes mudanças precisam ser feitas na solicitação:

1. Remova completamente o objeto ClientInfo v4. Em vez de fornecer a identificação de um cliente usando um campo dedicado, basta usar o conhecido cabeçalho User-Agent. Embora não haja um formato prescrito para fornecer a identificação do cliente nesse cabeçalho, sugerimos que você inclua simplesmente o ID do cliente original e a versão dele, separados por um caractere de espaço ou barra.
2. Para cada objeto ListUpdateRequest v4:
   • Procure o nome da lista da v5 correspondente na tabela acima 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 da v5. A mesma string de bytes que seria enviada ao servidor usando o campo state na v4 pode simplesmente ser enviada na v5 usando o campo versions.
   • Para as restrições da v4, a v5 usa uma versão simplificada chamada SizeConstraints. Campos adicionais, como region, precisam ser descartados.

As seguintes mudanças precisam ser feitas na resposta:

1. O enum ResponseType da v4 é simplesmente substituído por um campo booleano chamado partial_update.
2. O campo minimum_wait_duration agora pode ser zero ou omitido. Se estiver, o cliente é solicitado a 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 que o tamanho máximo do banco de dados.
3. O algoritmo de decodificação de Rice para números inteiros de 32 bits precisará ser ajustado. A diferença é que os dados codificados são codificados com uma endianness diferente. Nas versões v4 e v5, os prefixos de hash de 32 bits são classificados lexicograficamente. Mas na v4, esses prefixos são tratados como small endian quando classificados, enquanto na v5 esses prefixos são tratados como big endian quando classificados. Isso significa que o cliente não precisa fazer nenhuma classificação, já que a classificação lexicográfica é idêntica à classificação numérica com big endian. Um exemplo desse tipo na implementação do Chromium na v4 pode ser encontrado aqui. Essa classificação pode ser removida.
4. O algoritmo de decodificação Rice precisará ser implementado em outros comprimentos de hash.

Conversão de pesquisas de hash

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

As seguintes mudanças precisam ser feitas na solicitação:

1. Estruture o código para enviar apenas prefixos hash com exatamente 4 bytes.
2. Remova completamente os objetos ClientInfo da v4. Em vez de fornecer a identificação de um cliente usando um campo dedicado, basta usar o conhecido cabeçalho User-Agent. Embora não haja um formato prescrito para fornecer a identificação do cliente nesse cabeçalho, sugerimos que você inclua simplesmente o ID do cliente original e a versão dele, separados por um caractere de espaço ou 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 poderá 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 para uma única duração de cache. Consulte os procedimentos acima para interagir com o cache.