Overview

Introdução

Observação: esta documentação ainda está em desenvolvimento. Espere melhorias em breve.

A Navegação segura do Google v5 é uma evolução da Navegação segura do Google v4. As duas principais mudanças feitas na v5 são a atualização de dados e a privacidade de IP. Além disso, a superfície da API foi aprimorada para aumentar a flexibilidade e a eficiência e reduzir a sobrecarga. Além disso, a Navegação segura do Google v5 foi criada para facilitar a migração da v4.

Atualmente, o Google oferece as versões v4 e v5, e ambas são consideradas prontas para produção. É possível usar a v4 ou a v5. Não anunciamos uma data para a desativação da v4. Caso contrário, enviaremos um aviso com pelo menos um ano de antecedência. Nesta página, descrevemos a v5 e um guia de migração da v4 para a v5. A documentação completa da v4 continua disponível.

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 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 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 oferecem ataques tinham menos de 10 minutos de duração. Nossa análise mostra que cerca de 25% a 30% das ausências na proteção contra phishing se deve a essa insatisfação dos dados. Além disso, alguns dispositivos não são equipados para gerenciar todas as listas de ameaças da Navegação segura do Google, que continuam aumentando com o tempo.

Na v5, introduzimos um modo de operação conhecido como proteção em tempo real. Isso contorna o problema de desatualização dos dados acima. Na v4, espera-se que os clientes façam o download e mantenham um banco de dados local, executem verificações nas listas de ameaças baixadas localmente e, quando houver uma correspondência parcial de prefixo, execute uma solicitação para fazer o download do hash completo. Na v5, embora os clientes devam continuar a fazer o download e manter um banco de dados local de listas de ameaças, agora também se espera que os clientes façam o download de uma lista de sites provavelmente benignos (chamadas de cache global), realizem uma verificação local para esse cache global e uma verificação local da lista de ameaças e, por fim, quando houver uma correspondência de prefixo parcial para listas de ameaças ou uma falta de correspondência no cache global. Para mais detalhes sobre o processamento local exigido pelo cliente, consulte o procedimento abaixo. Isso representa uma mudança de "permitir por padrão" para "verificação por padrão", o que pode melhorar a proteção diante da propagação mais rápida de ameaças na Web. Em outras palavras, esse é um protocolo projetado para fornecer proteção quase em tempo real: queremos que os clientes se beneficiem dos 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, serão ignorados. Os endereços IP de origem das solicitações são conhecidos pelo Google, mas o Google só usa os endereços IP para necessidades essenciais de rede (por exemplo, para enviar respostas) e para fins antiDoS.

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

Uso apropriado

Uso permitido

A API Safe Browsing é apenas para uso não comercial (ou seja, "não para fins de venda ou geração de receita"). Se você precisar de uma solução para fins comerciais, consulte Web Risk.

Preços

Todas as APIs da Navegação segura do Google 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ê pretende usar mais do que a cota alocada atualmente, solicite uma cota adicional na interface de cotas do Play Console. Analisamos essas solicitações e solicitamos que um contato entre em contato quando solicitar uma cota maior 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 criada para atuar em URLs que são exibidos na barra de endereço de um navegador. Ele não foi projetado para ser usado na verificação de sub-recursos (como um JavaScript ou uma imagem referenciada por um arquivo HTML ou uma URL WebSocket iniciada pelo JavaScript). Esses URLs de recursos secundários não devem ser verificados na Navegação segura do Google.

Se a visita a um URL resultar em um redirecionamento (como HTTP 301), é apropriado que o URL redirecionado seja verificado na 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 verificados com relação à Navegação segura do Google.

Avisos para os usuários

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

Essas diretrizes ajudam a proteger você e o Google de mal-entendidos, deixando claro que a página não tem 100% de certeza de ser um recurso não seguro da Web e que os avisos apenas identificam um possível risco.

• No aviso visível ao usuário, você não pode levar 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 riscos potenciais que ela pode representar para os usuários, você precisa qualificar o aviso usando termos como: suspeita, possivelmente, possível, provável.
• O aviso precisa permitir que o usuário saiba mais revisando a definição de várias ameaças pelo Google. Confira a seguir os links 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
  • Aplicativos potencialmente nocivos (somente Android): https://developers.google.com/android/play-protect/potentially-harmful-applications
• Quando você mostra avisos sobre páginas identificadas como arriscadas pelo serviço da Navegação segura, é necessário atribuir atribuições ao Google incluindo a linha "Consultoria fornecida pelo Google" com um link para o Alerta da Navegação segura. Se o produto também mostra 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. Ela precisa informar a eles que há uma chance de haver falsos positivos (sites seguros sinalizados como arriscados) e falsos negativos (sites de risco não sinalizados). Sugerimos usar o seguinte idioma:

  O Google trabalha para oferecer as informações mais precisas e atualizadas sobre recursos não seguros da Web. No entanto, o Google não pode garantir que as 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.

Os modos de operação

A Navegação segura do Google v5 permite que os clientes escolham entre três modos de operação.

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 no banco de dados local: (i) um cache global de sites provavelmente benignos, formatados como hashes SHA256 de expressões de URL de sufixo de host/prefixo de caminho, (ii) um conjunto de listas de ameaças, formatadas como prefixos de hash SHA256 de expressões de URL de sufixo de host/caminho-prefixo. A ideia geral é que sempre que o cliente quiser verificar um URL específico, uma verificação local será realizada usando o cache global. Se essa verificação é aprovada, uma verificação das listas de ameaças locais é realizada. Caso contrário, o cliente continua com a verificação de hash em tempo real, conforme detalhado abaixo.

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

Veja a seguir uma especificação detalhada do procedimento.

Modo de lista local

Quando os clientes escolhem usar a Navegação segura do Google v5 nesse modo, o comportamento dele é semelhante ao da API Update v4, exceto por usar a superfície da API aprimorada da v5. Os clientes mantêm no banco de dados local um conjunto de listas de ameaças formatadas como prefixos de hash SHA256 de expressões de URL de sufixo de host/prefixo de caminho. Sempre que o cliente quiser verificar um URL específico, 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 exemplo acima, o cliente também 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. Sempre que o cliente quiser verificar um URL específico, ele se conectará ao servidor para realizar essa verificação. Esse modo é semelhante ao que os clientes da API Lookup v4 podem implementar.

Como verificar URLs

Esta seção contém especificações detalhadas de como os clientes verificam URLs.

Canonização de URLs

Antes da verificação de qualquer URL, espera-se que o cliente execute a canonização nele.

Para começar, presumimos que o cliente analisou o URL e o tornou válido de acordo com a RFC 2396. Se o URL usa um nome de domínio internacionalizado (IDN, na sigla em inglês), o cliente precisa converter o URL na representação ASCII Punycode. O URL precisa incluir um componente de caminho, ou seja, ele precisa ter pelo menos uma barra após o 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/.

Em terceiro lugar, remova repetidamente o escape percentual do URL até que ele não tenha mais escapes percentuais. 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 iniciais desnecessários nos componentes e recolhendo 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 que usa o conhecido prefixo 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, use porcentagem de escape de todos os caracteres <= ASCII 32, >= 127, # ou %. Os escape devem usar caracteres hexadecimais em maiúsculas.

Expressões de prefixo do caminho do sufixo de host

Depois que o URL for canonizado, 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 combinações diferentes possíveis de sufixo 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 do host formados começando com o domínio eTLD+1 e adicionando componentes principais sucessivos. A determinação do eTLD+1 deve 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 extra b.example.com.
• 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 componentes do caminho, incluindo uma barra à direita.

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: pule b.c.d.e.f.com, já que usaremos apenas os últimos cinco componentes do nome do host 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/

Hashing

A Navegação segura do Google usa exclusivamente SHA256 como a função hash. Essa função 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 hash.search, exigimos que os hashes na solicitação sejam truncados em exatamente 4 bytes. O envio de bytes adicionais nesta solicitação comprometerá a privacidade do usuário.

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

O 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 retornar UNSAFE, o URL será considerado potencialmente não seguro pela Navegação segura do Google e as medidas apropriadas deverão ser tomadas, como mostrar um aviso ao usuário final, mover uma mensagem recebida para a pasta de spam ou exigir uma confirmação extra por parte do usuário antes de continuar. Se retornar UNSURE, o procedimento de verificação local a seguir precisará ser usado posteriormente.

1. Permita que expressions seja uma lista de expressões de sufixo/prefixo geradas 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. Pesquisar expressionHashPrefix no cache local.
   2. Se a entrada armazenada em cache for encontrada:
      1. Determine se a hora atual é maior que o tempo de expiração.
      2. Se for maior:
         1. Remova do cache local a entrada encontrada em cache.
         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 armazenada em cache.
         3. Se ela for encontrada, retorne 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. Enviar expressionHashPrefixes para o 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 o response recebido 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.), além do prazo de validade do cache expiration.
7. Para cada fullHash de response:
   1. Insira fullHash no cache local, junto com expiration.
8. Para cada fullHash de response:
   1. Permita que isFound seja o resultado de encontrar fullHash em expressionHashes.
   2. Se isFound for falsa, continue com a repetição.
   3. Se isFound for "True", retorna UNSAFE.
9. Retorne o SAFE.

O procedimento de verificação do URL da lista de ameaças locais

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 geradas 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. Pesquisar expressionHashPrefix no cache local.
   2. Se a entrada armazenada em cache for encontrada:
      1. Determine se a hora atual é maior que o tempo de expiração.
      2. Se for maior:
         1. Remova do cache local a entrada encontrada em cache.
         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 armazenada em cache.
         3. Se ela for encontrada, retorne 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 local da lista de ameaças.
   2. Se o expressionHashPrefix não puder ser encontrado no banco de dados da lista local de ameaças, remova-o de expressionHashPrefixes.
6. Enviar expressionHashPrefixes para o 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 o response recebido 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.), além do prazo de validade do cache expiration.
7. Para cada fullHash de response:
   1. Insira fullHash no cache local, junto com expiration.
8. Para cada fullHash de response:
   1. Permita que isFound seja o resultado de encontrar fullHash em expressionHashes.
   2. Se isFound for falsa, continue com a repetição.
   3. Se isFound for "True", retorna UNSAFE.
9. Retorne o SAFE.

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

Este 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 geradas 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. Pesquisar expressionHashPrefix no cache local.
   2. Se a entrada armazenada em cache for encontrada:
      1. Determine se a hora atual é maior que o tempo de expiração.
      2. Se for maior:
         1. Remova do cache local a entrada encontrada em cache.
         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 armazenada em cache.
         3. Se ela for encontrada, retorne 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. Enviar expressionHashPrefixes para o 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 o response recebido 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.), além do prazo de validade do cache expiration.
6. Para cada fullHash de response:
   1. Insira fullHash no cache local, junto com expiration.
7. Para cada fullHash de response:
   1. Permita que isFound seja o resultado de encontrar fullHash em expressionHashes.
   2. Se isFound for falsa, continue com a repetição.
   3. Se isFound for "True", retorna UNSAFE.
8. Retorne o SAFE.

Manutenção do banco de dados local

A Navegação segura do Google v5 espera que o cliente mantenha um banco de dados local, exceto quando o cliente escolher o modo em tempo real sem armazenamento. Cabe ao cliente definir o formato e o armazenamento desse banco de dados local. O conteúdo desse banco de dados local pode ser conceitualmente considerado uma pasta que contém várias listas como arquivos, e o conteúdo desses arquivos são hashes SHA256 ou prefixos de hash.

Atualizações do banco de dados

O cliente chama regularmente o método hashList.get ou hashLists.batchGet para atualizar o banco de dados. Como o cliente comum quer atualizar várias listas de uma 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 poucos caracteres.

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

Depois que um nome for escolhido para uma lista, ele nunca será renomeado. Além disso, depois que uma lista aparece, ela nunca é removida (se a lista não for mais útil, ela ficará vazia, mas continuará existindo). Portanto, é recomendável 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. As atualizações incrementais funcionam fornecendo um delta entre a versão da lista do cliente e a versão mais recente dela. Se um cliente for recém-implantado e não houver versões disponíveis, uma atualização completa estará disponível. A atualização incremental contém índices de remoção e inclusões. Primeiro, espera-se 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 a corrupção, o cliente deve comparar os dados armazenados em relação à soma de verificação fornecida pelo servidor. Sempre que a soma de verificação não for correspondente, o cliente deverá executar uma atualização completa.

Decodificar o conteúdo da lista

Todas as listas são entregues usando uma codificação especial para reduzir o tamanho. Essa codificação reconhece que as listas da Navegação segura do Google contêm, conceitualmente, um conjunto de hashes ou prefixos de hash, que são estatisticamente indistinguíveis de números inteiros aleatórios. Se fôssemos classificar esses números inteiros e tomar as diferenças adjacentes deles, espera-se que a diferença adjacente seja "pequena", em algum sentido. A codificação Golomb-Rice explora essa penetração menor.

A Navegação segura do Google v5 tem quatro tipos distintos para lidar com dados de 4, 8, 16 e 32 bytes. Vejamos um exemplo em que três números inteiros de 4 bytes numericamente consecutivos são codificados. Permita que o parâmetro Rice, representado por k, seja 3. A parte quociente da codificação é simplesmente o valor da diferença adjacente deslocado para a direita em k bits. Como os números inteiros fornecidos são consecutivos, a diferença adjacente é 1 e, após deslocar por 3 bits, a parte do quociente é zero. Os k bits menos significativos são 001. O quociente zero é codificado como um único bit 0. O restante é 1 e codificado como 100. Isso é repetido novamente para formar o bitstream 01000100. O bitstream resultante é codificado usando little endian como 00100010. Portanto, ela corresponde aos seguintes dados:

rice_parameter: 3
entries_count: 2
encoded_data: "\x22"

Após a etapa de decodificação acima para números inteiros de 32 bits, o resultado pode ser usado diretamente como índices de remoção ou adições. Ao contrário da v4, não é necessário realizar uma troca de bytes depois.

Listas disponíveis

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

Nome da lista	Enumeração ThreatType correspondente da v4	Descrição
gc	Nenhuma	Esta é uma lista de cache global. É uma lista especial usada apenas no modo de operação em tempo real.
se	SOCIAL_ENGINEERING	Essa lista contém ameaças do tipo SOCIAL_EngineerING.
mw	MALWARE	Essa lista contém ameaças do tipo MALWARE para plataformas de desktop.
uws	UNWANTED_SOFTWARE	Essa lista contém ameaças do tipo UNWANTED_SOFTWARE para plataformas de desktop.
uwsa	UNWANTED_SOFTWARE	Essa lista contém ameaças do tipo UNWANTED_SOFTWARE para plataformas Android.
pha	POTENTIALLY_HARMFUL_APPLICATION	Essa lista contém ameaças do tipo POTENTIALLY_HARMFUL_APPLICATION para plataformas Android.

Listas adicionais serão disponibilizadas posteriormente, quando a tabela acima será expandida.

Frequência de atualização

O cliente precisa 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. Nesse caso, o cliente precisa realizar outra atualização imediatamente.

Exemplos de solicitação

Esta seção documenta alguns exemplos de uso direto da API HTTP para acessar a Navegação segura do Google. Geralmente, é recomendável usar uma vinculação de linguagem gerada, porque ela lidará automaticamente com a codificação e a decodificação de uma maneira conveniente. Consulte a documentação dessa vinculação.

Este é um exemplo de solicitação HTTP que usa o método hashes.search:

GET https://safebrowsing.googleapis.com/v5/hashes:search?key=INSERT_YOUR_API_KEY_HERE&hashPrefixes=WwuJdQ

O corpo da resposta é um payload formatado de buffer de protocolo que você pode decodificar.

Este é um exemplo de solicitação HTTP que usa o método hashLists.batchGet:

GET https://safebrowsing.googleapis.com/v5alpha1/hashLists:batchGet?key=INSERT_YOUR_API_KEY_HERE&names=se&names=mw

O corpo da resposta é, mais uma vez, um payload formatado com buffer de protocolo que você pode decodificar.

Guia de migração

Se você estiver usando atualmente a API v4 Update, haverá um caminho de migração contínuo da v4 para a v5 sem precisar redefinir ou apagar o banco de dados local. Esta seção documenta como fazer isso.

Conversão de atualizações da lista

Na v4, o método threatListUpdates.fetch é usado para fazer o download de listas. Na v5, a alteração seria feita para o método hashLists.batchGet.

As seguintes alterações devem ser feitas na solicitação:

1. Remova completamente o objeto ClientInfo v4. Em vez de fornecer a identificação de um cliente com 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 simplesmente incluir o ID do cliente original e a versão do cliente 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 ser simplesmente 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 alterações 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 será 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 do que o tamanho máximo do banco de dados.
3. O algoritmo de decodificação do Rice para números inteiros de 32 bits precisa ser ajustado. A diferença é que os dados codificados são codificados com endianness diferente. Nas versões v4 e v5, os prefixos de hash de 32 bits são classificados lexicograficamente. No entanto, 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, uma vez que a classificação lexicográfica é idêntica à classificação numérica com big endian. Um exemplo desse tipo na implementação do Chromium da v4 pode ser encontrado aqui. Essa classificação pode ser removida.
4. O algoritmo de decodificação do "Rice" precisará ser implementado para outros comprimentos de hash.

Conversão de pesquisas de hash

Na v4, o método fullHashes.find pode ser usado para receber hashes completos. O método equivalente na v5 é o hash.search.

As seguintes alterações devem ser feitas na solicitação:

1. Estrutura o código para enviar apenas prefixos de hash com exatamente 4 bytes.
2. Remova todos os objetos ClientInfo v4. Em vez de fornecer a identificação de um cliente com 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 simplesmente incluir o ID do cliente original e a versão do cliente 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 alterações precisam ser feitas na resposta:

1. O campo minimum_wait_duration foi removido. O cliente pode fazer 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 de cache. Veja os procedimentos acima para interagir com o cache.