URLs and Hashing
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Esta seção contém especificações detalhadas de como os clientes verificam URLs.
Canonização de URLs
Antes de verificar qualquer URL, o cliente precisa realizar uma canonização nesse URL.
Para começar, presumimos que o cliente analisou o URL e o tornou válido de acordo com a RFC 2396. Se o URL usar um nome de domínio internacionalizado (IDN, na sigla em inglês), o cliente deverá converter o URL para a representação ASCII de 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, faça o escape de porcentagem do URL repetidamente até que ele não tenha mais escapes de porcentagem. Isso pode tornar o URL inválido.
Para canonizar o nome do host:
Extraia o nome do host do URL e:
- Remova todos os pontos iniciais e finais.
- Substitua os pontos consecutivos por um único ponto.
- Se o nome do host puder ser analisado como um endereço IPv4, normalize-o para quatro valores decimais separados por ponto. O cliente precisa processar qualquer codificação de endereço IP legal, incluindo octal, hexadecimal e menos de quatro componentes.
- 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 reduzindo os componentes nulos 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ço IPv6 especiais a seguir, transforme-o 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.
- Minúsculas a string inteira.
Para canonizar o caminho:
- Resolva as sequências
/../ e /./ no caminho substituindo /./ por / e removendo /../ junto com o componente de caminho anterior.
- 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 a função de escape de porcentagem para todos os caracteres que são {= ASCII 32, = = 127, # ou %. Os escape devem usar caracteres hexadecimais em maiúsculas.
Expressões de prefixo de caminho de sufixo de host
Depois que o URL for canonizado, a próxima etapa será 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 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 vai 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 de host não for um literal IPv4 ou IPv6, até quatro nomes de host formados começando pelo domínio eTLD+1 e adicionando componentes principais sucessivos. A determinação do 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 adicional 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 pela raiz (/) e anexando componentes de 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/
b.c.d.e.f.com é ignorado, já que vamos usar apenas os cinco últimos componentes do nome do host e o nome 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
O Google Safe Browsing usa exclusivamente o SHA256 como função hash. Essa função de hash precisa ser aplicada às expressões acima.
O hash completo de 32 bytes será truncado para 4, 8 ou 16 bytes, dependendo das circunstâncias:
Ao usar o método hashes.search, atualmente exigimos que os hashes na solicitação sejam truncados para exatamente 4 bytes. O envio de bytes adicionais nessa solicitação compromete 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 é codificado na convenção de nomenclatura das listas que contêm um sufixo que indica o comprimento do hash. Consulte a seção Listas disponíveis para mais detalhes.
Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2025-07-25 UTC.
[null,null,["Última atualização 2025-07-25 UTC."],[],[],null,["# URLs and Hashing\n\nThis section contains detailed specifications of how clients check URLs.\n\n### Canonicalization of URLs\n\nBefore any URLs are checked, the client is expected to perform some canonicalization on that URL.\n\nTo begin, we assume that the client has parsed the URL and made it valid according to RFC 2396. If the URL uses an internationalized domain name (IDN), the client should convert the URL to the ASCII Punycode representation. The URL must include a path component; that is, it must have at least one slash following the domain (`http://google.com/` instead of `http://google.com`).\n\nFirst, remove tab (0x09), CR (0x0d), and LF (0x0a) characters from the URL. Do not remove escape sequences for these characters (e.g. `%0a`).\n\nSecond, if the URL ends in a fragment, remove the fragment. For example, shorten `http://google.com/#frag` to `http://google.com/`.\n\nThird, repeatedly percent-unescape the URL until it has no more percent-escapes. (This may render the URL invalid.)\n\n**To canonicalize the hostname:**\n\nExtract the hostname from the URL and then:\n\n1. Remove all leading and trailing dots.\n2. Replace consecutive dots with a single dot.\n3. If the hostname can be parsed as an IPv4 address, normalize it to 4 dot-separated decimal values. The client should handle any legal IP-address encoding, including octal, hex, and fewer than four components.\n4. If the hostname can be parsed as a bracketed IPv6 address, normalize it by removing unnecessary leading zeroes in the components and collapsing zero components by using the double-colon syntax. For example `[2001:0db8:0000::1]` should be transformed into `[2001:db8::1]`. If the hostname is one of the two following special IPv6 address types, transform them into IPv4:\n - An IPv4-mapped IPv6 address, such as `[::ffff:1.2.3.4]`, which should be transformed into `1.2.3.4`;\n - A NAT64 address using [the well-known prefix 64:ff9b::/96](https://datatracker.ietf.org/doc/html/rfc6052#section-2.1), such as `[64:ff9b::1.2.3.4]`, which should be transformed into `1.2.3.4`.\n5. Lowercase the whole string.\n\n**To canonicalize the path:**\n\n1. Resolve the sequences `/../` and `/./` in the path by replacing `/./` with `/`, and removing `/../` along with the preceding path component.\n2. Replace runs of consecutive slashes with a single slash character.\n\nDo not apply these path canonicalizations to the query parameters.\n\nIn the URL, percent-escape all characters that are \\\u003c= ASCII 32, \\\u003e= 127, `#`, or `%`. The escapes should use uppercase hex characters.\n\n### Host-Suffix Path-Prefix Expressions\n\nOnce the URL is canonicalized, the next step is to create the suffix/prefix expressions. Each suffix/prefix expression consists of a host suffix (or full host) and a path prefix (or full path).\n\nThe client will form up to 30 different possible host suffix and path prefix combinations. These combinations use only the host and path components of the URL. The scheme, username, password, and port are discarded. If the URL includes query parameters, then at least one combination will include the full path and query parameters.\n\n**For the host**, the client will try at most five different strings. They are:\n\n- If the hostname is not an IPv4 or IPv6 literal, up to four hostnames formed by starting with the eTLD+1 domain and adding successive leading components. The determination of eTLD+1 should be based on the [Public Suffix List](https://publicsuffix.org/). For example, `a.b.example.com` would result in the eTLD+1 domain of `example.com` as well as the host with one additional host component `b.example.com`.\n- The exact hostname in the URL. Following the previous example, `a.b.example.com` would be checked.\n\n**For the path**, the client will try at most six different strings. They are:\n\n- The exact path of the URL, including query parameters.\n- The exact path of the URL, without query parameters.\n- The four paths formed by starting at the root (/) and successively appending path components, including a trailing slash.\n\nThe following examples illustrate the check behavior:\n\nFor the URL `http://a.b.com/1/2.html?param=1`, the client will try these possible strings: \n\n a.b.com/1/2.html?param=1\n a.b.com/1/2.html\n a.b.com/\n a.b.com/1/\n b.com/1/2.html?param=1\n b.com/1/2.html\n b.com/\n b.com/1/\n\nFor the URL `http://a.b.c.d.e.f.com/1.html`, the client will try these possible strings: \n\n a.b.c.d.e.f.com/1.html\n a.b.c.d.e.f.com/\n c.d.e.f.com/1.html\n c.d.e.f.com/\n d.e.f.com/1.html\n d.e.f.com/\n e.f.com/1.html\n e.f.com/\n f.com/1.html\n f.com/\n\n(Note: skip `b.c.d.e.f.com`, since we'll take only the last five hostname components, and the full hostname.)\n\nFor the URL `http://1.2.3.4/1/`, the client will try these possible strings: \n\n 1.2.3.4/1/\n 1.2.3.4/\n\nFor the URL `http://example.co.uk/1`, the client will try these possible strings: \n\n example.co.uk/1\n example.co.uk/\n\n### Hashing\n\nGoogle Safe Browsing exclusively uses SHA256 as the hash function. This hash function should be applied to the above expressions.\n\nThe full 32-byte hash will, depending on the circumstances, be truncated to 4 bytes, 8 bytes, or 16 bytes:\n\n- When using the [hashes.search method](/safe-browsing/reference/rest/v5/hashes/search), we currently require the hashes in the request to be truncated to exactly 4 bytes. Sending additional bytes in this request will compromise user privacy.\n\n- When downloading the lists for the local database using the [hashList.get method](/safe-browsing/reference/rest/v5/hashList/get) or the [hashLists.batchGet method](/safe-browsing/reference/rest/v5/hashLists/batchGet), the length of the hashes sent by the server is encoded within the naming convention of the lists that contain suffix indicating hash length. See [Available Lists](/safe-browsing/reference/Local.Database#available-lists) section for more details."]]
