Índice
SafeBrowsing(interface)BatchGetHashListsRequest(mensagem)BatchGetHashListsResponse(mensagem)FullHash(mensagem)FullHash.FullHashDetail(mensagem)GetHashListRequest(mensagem)HashList(mensagem)HashListMetadata(mensagem)HashListMetadata.HashLength(enum)LikelySafeType(enum)ListHashListsRequest(mensagem)ListHashListsResponse(mensagem)RiceDeltaEncoded128Bit(mensagem)RiceDeltaEncoded256Bit(mensagem)RiceDeltaEncoded32Bit(mensagem)RiceDeltaEncoded64Bit(mensagem)SearchHashesRequest(mensagem)SearchHashesResponse(mensagem)SizeConstraints(mensagem)ThreatAttribute(enum)ThreatType(enum)
SafeBrowsing
As APIs da Navegação segura permitem que os clientes verifiquem recursos da Web (geralmente URLs) nas listas de recursos da Web inseguros do Google, que são constantemente atualizadas.
| BatchGetHashLists |
|---|
|
Receba várias listas de hashes de uma só vez. É muito comum que um cliente precise acessar várias listas de hashes. É preferível usar esse método em vez do método Get normal várias vezes. Este é um método padrão de lote GET, conforme definido em https://google.aip.dev/231, e o método HTTP também é GET. |
| GetHashList |
|---|
|
Receba o conteúdo mais recente de uma lista de hashes. Uma lista de hashes pode ser uma lista de ameaças ou não, como o cache global. Este é um método GET padrão, conforme definido em https://google.aip.dev/131, e o método HTTP também é GET. |
| ListHashLists |
|---|
|
Listas de hash. Na API V5, o Google nunca remove uma lista de hashes retornada por esse método. Isso permite que os clientes ignorem esse método e simplesmente programem todas as listas de hashes necessárias. Este é um método de lista padrão, conforme definido em https://google.aip.dev/132, e o método HTTP é GET. |
| SearchHashes |
|---|
|
Pesquise hashes completos que correspondam aos prefixos especificados. Esse é um método personalizado, conforme definido em https://google.aip.dev/136. O método personalizado se refere a um método com um nome personalizado na nomenclatura geral de desenvolvimento de API do Google. Ele não se refere ao uso de um método HTTP personalizado. |
BatchGetHashListsRequest
A solicitação para receber várias listas de hashes ao mesmo tempo.
| Campos | |
|---|---|
names[] |
Obrigatório. Os nomes das listas de hash específicas. A lista pode ser uma lista de ameaças ou o cache global. Os nomes NÃO podem conter duplicatas. Caso contrário, o cliente vai receber um erro. |
version[] |
As versões da lista de hashes que o cliente já tem. Se esta for a primeira vez que o cliente está buscando as listas de hash, o campo precisa estar vazio. Caso contrário, o cliente precisa fornecer as versões recebidas anteriormente do servidor. O cliente NÃO PODE manipular esses bytes. O cliente não precisa enviar as versões na mesma ordem dos nomes de lista correspondentes. O cliente pode enviar mais ou menos versões em uma solicitação do que nomes. No entanto, o cliente NÃO PODE enviar várias versões que correspondam ao mesmo nome. Se isso acontecer, o cliente vai receber um erro. Observação histórica: na V4 da API, isso era chamado de |
desired_hash_length |
O comprimento do prefixo de hash desejado dos hashes retornados em bytes. O servidor vai retornar todos os prefixos de hash com esse comprimento especificado. Diferentes listas de hashes têm requisitos diferentes para os valores aceitáveis do campo Para o |
size_constraints |
As restrições de tamanho em cada lista. Se omitido, não há restrições. Os tamanhos aqui são por lista, não agregados em todas as listas. |
BatchGetHashListsResponse
A resposta que contém várias listas de hash.
| Campos | |
|---|---|
hash_lists[] |
O hash é listado na mesma ordem fornecida na solicitação. |
FullHash
O hash completo identificado com uma ou mais correspondências.
| Campos | |
|---|---|
full_hash |
O hash completo correspondente. Este é o hash SHA256. O comprimento será de exatamente 32 bytes. |
full_hash_details[] |
Lista não ordenada. Um campo repetido que identifica os detalhes relevantes para esse hash completo. |
FullHashDetail
Detalhes sobre um hash completo correspondente.
Observação importante sobre a compatibilidade com versões futuras: novos tipos e atributos de ameaça podem ser adicionados pelo servidor a qualquer momento. Essas adições são consideradas mudanças de versão menores. A política do Google é não expor números de versões secundárias nas APIs (consulte https://cloud.google.com/apis/design/versioning para saber mais sobre a política de controle de versões). Portanto, os clientes precisam estar preparados para receber mensagens FullHashDetail que contêm valores de enumeração ThreatType ou ThreatAttribute que são considerados inválidos pelo cliente. Portanto, é responsabilidade do cliente verificar a validade de todos os valores de tipo enumerado ThreatType e ThreatAttribute. Se algum valor for considerado inválido, o cliente PRECISA desconsiderar toda a mensagem FullHashDetail.
| Campos | |
|---|---|
threat_type |
O tipo de ameaça. Esse campo nunca vai ficar vazio. |
attributes[] |
Lista não ordenada. Atributos adicionais sobre esses hashes completos. Pode estar vazio. |
GetHashListRequest
Uma solicitação para receber uma lista de hashes, que pode ser uma lista de ameaças ou não, como o cache global.
Novidades da V5: o que antes era chamado de states na V4 foi renomeado como version para maior clareza. As listas agora são nomeadas, e os tipos de plataforma e de entrada de ameaças foram removidos. Agora é possível que várias listas tenham o mesmo tipo de ameaça ou que uma única lista se refira a vários tipos de ameaça. Os clientes agora podem especificar um comprimento de hash desejado. Isso faz parte da resposta aos prefixos de hash de comprimento variável do V4, que causaram problemas em muitas implementações de cliente: todos os hashes em uma lista agora têm um único comprimento, permitindo implementações de cliente muito mais eficientes. As restrições foram simplificadas, e o tipo de compactação foi removido. A compactação é sempre aplicada.
| Campos | |
|---|---|
name |
Obrigatório. O nome dessa lista de hashes específica. Pode ser uma lista de ameaças ou o cache global. |
version |
A versão da lista de hash que o cliente já tem. Se esta for a primeira vez que o cliente está buscando a lista de hashes, esse campo PRECISA ficar vazio. Caso contrário, o cliente PRECISA fornecer a versão recebida anteriormente do servidor. O cliente NÃO PODE manipular esses bytes. Novidades na V5: na V4 da API, isso era chamado de |
desired_hash_length |
O comprimento do prefixo de hash desejado dos hashes retornados em bytes. O servidor vai retornar todos os prefixos de hash com esse comprimento especificado. Diferentes listas de hashes têm requisitos diferentes para os valores aceitáveis do campo |
size_constraints |
As restrições de tamanho na lista. Se omitido, não há restrições. As restrições são recomendadas em todos os dispositivos com capacidade de processamento, largura de banda ou armazenamento limitados. |
HashList
Uma lista de hashes identificados pelo nome.
| Campos | |
|---|---|
name |
O nome da lista de hashes. O cache global também é apenas uma lista de hashes e pode ser referenciado aqui. |
version |
A versão da lista de hashes. O cliente NÃO PODE manipular esses bytes. |
partial_update |
Quando verdadeiro, é uma diferença parcial que contém adições e exclusões com base no que o cliente já tem. Quando é falso, é a lista de hashes completa. Quando é falso, o cliente PRECISA excluir qualquer versão armazenada localmente para essa lista de hashes. Isso significa que a versão do cliente está desatualizada ou que os dados do cliente estão corrompidos. O campo Quando verdadeiro, o cliente PRECISA aplicar uma atualização incremental removendo e adicionando itens. |
compressed_removals |
A versão codificada em delta-Rice dos índices de remoção. Como cada lista de hashes definitivamente tem menos de 2^32 entradas, os índices são tratados como números inteiros de 32 bits e codificados. |
minimum_wait_duration |
Os clientes precisam esperar pelo menos esse tempo para receber a lista de hashes novamente. Se for omitido ou zero, os clientes PRECISAM buscar imediatamente, porque isso indica que o servidor tem uma atualização adicional a ser enviada ao cliente, mas não pode devido às restrições especificadas pelo cliente. |
sha256_checksum |
A lista classificada de todos os hashes, hash novamente com SHA256. Essa é a soma de verificação da lista classificada de todos os hashes presentes no banco de dados após a aplicação da atualização fornecida. Se nenhuma atualização for fornecida, o servidor vai omitir esse campo para indicar que o cliente precisa usar a soma de verificação atual. |
metadata |
Metadados sobre a lista de hashes. Ele não é preenchido pelo método |
Campo de união compressed_additions. A versão codificada Rice-delta de adições. As extensões do prefixo de hash das adições são uniformes em todas as adições na lista. É o desired_hash_length enviado pelo cliente ou um valor escolhido pelo servidor se o cliente tiver omitido esse campo. compressed_additions pode ser apenas de um dos tipos a seguir: |
|
additions_four_bytes |
As adições de 4 bytes. |
additions_eight_bytes |
As adições de 8 bytes. |
additions_sixteen_bytes |
As adições de 16 bytes. |
additions_thirty_two_bytes |
As adições de 32 bytes. |
HashListMetadata
Metadados sobre uma lista de hash específica.
| Campos | |
|---|---|
threat_types[] |
Lista não ordenada. Se não estiver vazia, especifica que a lista de hashes é um tipo de lista de ameaças e enumera o tipo de ameaças associadas a hashes ou prefixos de hash nessa lista. Pode estar vazio se a entrada não representar uma ameaça, ou seja, se representar um tipo provavelmente seguro. |
likely_safe_types[] |
Lista não ordenada. Se não estiver vazia, especifica que a lista de hashes representa uma lista de hashes provavelmente seguros e enumera as maneiras como eles são considerados seguros. Esse campo é mutuamente exclusivo com o campo threat_types. |
description |
Uma descrição legível por humanos sobre essa lista. Escrita em inglês. |
supported_hash_lengths[] |
As comprimentos de hash compatíveis para essa lista de hashes. Cada lista de hashes oferece suporte a pelo menos um comprimento. Portanto, esse campo não vai ficar vazio. |
hash_length |
O comprimento do hash aceito para essa lista de hashes. Cada lista de hashes oferece suporte a exatamente um comprimento. Se um comprimento de hash diferente for introduzido para o mesmo conjunto de tipos de ameaça ou de segurança, ele será introduzido como uma lista separada com um nome distinto e o respectivo comprimento de hash definido. |
HashLength
O comprimento dos hashes em uma lista de hashes.
| Enums | |
|---|---|
HASH_LENGTH_UNSPECIFIED |
Comprimento não especificado. O servidor não vai retornar esse valor nas respostas ao cliente (no campo supported_hash_lengths), mas o cliente pode enviar esse valor ao servidor (no campo desired_hash_length). Nesse caso, o servidor vai escolher um valor automaticamente. Os clientes precisam deixar o servidor escolher um valor. |
FOUR_BYTES |
Cada hash é um prefixo de quatro bytes. |
EIGHT_BYTES |
Cada hash é um prefixo de oito bytes. |
SIXTEEN_BYTES |
Cada hash é um prefixo de 16 bytes. |
THIRTY_TWO_BYTES |
Cada hash é um hash completo de 32 bytes. |
LikelySafeType
Tipos de sites provavelmente seguros.
Observe que o SearchHashesResponse não contém LikelySafeType intencionalmente.
| Enums | |
|---|---|
LIKELY_SAFE_TYPE_UNSPECIFIED |
Desconhecido. |
GENERAL_BROWSING |
Esse site provavelmente é seguro para navegação geral. Isso também é conhecido como cache global. |
CSD |
É provável que esse site seja seguro o suficiente para que não seja necessário executar modelos de detecção do lado do cliente ou verificações de proteção por senha. |
DOWNLOAD |
Esse site provavelmente é seguro o suficiente para que os downloads dele não precisem ser verificados. |
ListHashListsRequest
A solicitação para listar as listas de hash disponíveis.
| Campos | |
|---|---|
page_size |
O número máximo de listas de hashes a serem retornadas. O serviço pode retornar menos que esse valor. Se não for especificado, o servidor vai escolher um tamanho de página, que pode ser maior que o número de listas de hash para que a paginação não seja necessária. |
page_token |
Um token de página recebido de uma chamada |
ListHashListsResponse
A resposta que contém metadados sobre listas de hashes.
| Campos | |
|---|---|
hash_lists[] |
O hash é listado em uma ordem arbitrária. Somente os metadados sobre as listas de hashes serão incluídos, não o conteúdo. |
next_page_token |
Um token, que pode ser enviado como |
RiceDeltaEncoded128Bit
Igual a RiceDeltaEncoded32Bit, exceto que codifica números de 128 bits.
| Campos | |
|---|---|
first_value_hi |
Os 64 bits superiores da primeira entrada nos dados codificados (hashes). Se o campo estiver vazio, os 64 bits superiores serão todos zero. |
first_value_lo |
Os 64 bits mais baixos da primeira entrada nos dados codificados (hashes). Se o campo estiver vazio, os 64 bits mais baixos serão todos zero. |
rice_parameter |
O parâmetro Golomb-Rice. Esse parâmetro precisa estar entre 99 e 126. |
entries_count |
O número de entradas codificadas delta nos dados codificados. Se apenas um número inteiro for codificado, ele será zero e o valor único será armazenado em |
encoded_data |
As deltas codificadas usando o codificador Golomb-Rice. |
RiceDeltaEncoded256Bit
Igual a RiceDeltaEncoded32Bit, exceto por codificar números de 256 bits.
| Campos | |
|---|---|
first_value_first_part |
Os primeiros 64 bits da primeira entrada nos dados codificados (hashes). Se o campo estiver vazio, os primeiros 64 bits serão todos zero. |
first_value_second_part |
Os bits de 65 a 128 da primeira entrada nos dados codificados (hashes). Se o campo estiver vazio, os bits de 65 a 128 serão todos zero. |
first_value_third_part |
Os bits de 129 a 192 da primeira entrada nos dados codificados (hashes). Se o campo estiver vazio, os bits de 129 a 192 serão todos zero. |
first_value_fourth_part |
Os últimos 64 bits da primeira entrada nos dados codificados (hashes). Se o campo estiver vazio, os últimos 64 bits serão todos zero. |
rice_parameter |
O parâmetro Golomb-Rice. Esse parâmetro precisa estar entre 227 e 254. |
entries_count |
O número de entradas codificadas delta nos dados codificados. Se apenas um número inteiro for codificado, ele será zero e o valor único será armazenado em |
encoded_data |
As deltas codificadas usando o codificador Golomb-Rice. |
RiceDeltaEncoded32Bit
Os dados codificados com Rice-Golomb. Usado para hashes ou índices de remoção. É garantido que cada hash ou índice aqui tenha o mesmo comprimento, e esse comprimento é exatamente de 32 bits.
De modo geral, se você classificar todas as entradas lexicograficamente, vai descobrir que os bits de ordem mais alta tendem a não mudar com a mesma frequência que os de ordem mais baixa. Isso significa que, se também considerarmos a diferença adjacente entre as entradas, os bits de ordem mais alta têm uma alta probabilidade de serem zero. Isso aproveita essa alta probabilidade de zero escolhendo essencialmente um determinado número de bits. Todos os bits mais significativos do que esse valor provavelmente serão zero, então usamos a codificação unária. Consulte o campo rice_parameter.
Observação histórica: a codificação Rice-delta foi usada pela primeira vez na versão 4 desta API. Na V5, duas melhorias significativas foram feitas: primeiro, a codificação Rice-delta agora está disponível com prefixos de hash maiores que 4 bytes. Segundo, os dados codificados agora são tratados como big-endian para evitar uma etapa de classificação custosa.
| Campos | |
|---|---|
first_value |
A primeira entrada nos dados codificados (hashes ou índices) ou, se apenas um único prefixo ou índice de hash tiver sido codificado, o valor dessa entrada. Se o campo estiver vazio, a entrada será zero. |
rice_parameter |
O parâmetro Golomb-Rice. Esse parâmetro precisa estar entre 3 e 30. |
entries_count |
O número de entradas codificadas delta nos dados codificados. Se apenas um número inteiro for codificado, ele será zero e o valor único será armazenado em |
encoded_data |
As deltas codificadas usando o codificador Golomb-Rice. |
RiceDeltaEncoded64Bit
Igual a RiceDeltaEncoded32Bit, exceto por codificar números de 64 bits.
| Campos | |
|---|---|
first_value |
A primeira entrada nos dados codificados (hashes) ou, se apenas um único prefixo de hash foi codificado, o valor dessa entrada. Se o campo estiver vazio, a entrada será zero. |
rice_parameter |
O parâmetro Golomb-Rice. Esse parâmetro precisa estar entre 35 e 62. |
entries_count |
O número de entradas codificadas delta nos dados codificados. Se apenas um número inteiro for codificado, ele será zero e o valor único será armazenado em |
encoded_data |
As deltas codificadas usando o codificador Golomb-Rice. |
SearchHashesRequest
Uma solicitação que o cliente emite para pesquisar prefixos de hash específicos.
Essa ferramenta foi projetada para pesquisar apenas listas de ameaças e não listas que não são de ameaças, como o cache global.
Novidades da V5: os clientes não precisam especificar um ClientInfo ou os estados das listas de hash no banco de dados local. Isso é feito para melhorar a privacidade. Além disso, os clientes não precisam enviar os tipos de ameaças em que estão interessados.
| Campos | |
|---|---|
hash_prefixes[] |
Obrigatório. Os prefixos de hash a serem pesquisados. Os clientes NÃO PODEM enviar mais de 1.000 prefixos de hash. No entanto, seguindo o procedimento de processamento de URL, os clientes NÃO precisam enviar mais de 30 prefixos de hash. Atualmente, cada prefixo de hash precisa ter exatamente 4 bytes. Isso PODE ser relaxado no futuro. |
filter |
Opcional. Se o cliente tiver interesse em filtrar, como apenas recuperar tipos específicos de ameaças, isso poderá ser especificado. Se omitido, todas as ameaças correspondentes são retornadas. É altamente recomendável omitir isso para ter a proteção mais completa que a Navegação segura pode oferecer. O filtro é especificado usando a Common Expression Language do Google, que pode ser encontrada em https://github.com/google/cel-spec, além de exemplos gerais. Confira alguns exemplos específicos que podem ser usados aqui: O filtro O filtro |
SearchHashesResponse
A resposta retornada após a pesquisa de hashes de ameaças.
Se nada for encontrado, o servidor vai retornar um status OK (código de status HTTP 200) com o campo full_hashes vazio, em vez de retornar um status NOT_FOUND (código de status HTTP 404).
Novidades na V5: há uma separação entre FullHash e FullHashDetail. Quando um hash representa um site com várias ameaças (por exemplo, MALWARE e SOCIAL_ENGINEERING), não é necessário enviar o hash completo duas vezes, como na V4. Além disso, a duração do cache foi simplificada em um único campo cache_duration.
| Campos | |
|---|---|
full_hashes[] |
Lista não ordenada. A lista não ordenada de hashes completos encontrados. |
cache_duration |
A duração do cache do lado do cliente. O cliente PRECISA adicionar essa duração ao horário atual para determinar o tempo de expiração. O tempo de expiração se aplica a todos os prefixos de hash consultados pelo cliente na solicitação, independentemente de quantos hashes completos são retornados na resposta. Mesmo que o servidor não retorne hashes completos para um prefixo de hash específico, esse fato também PRECISA ser armazenado em cache pelo cliente. Se e somente se o campo Importante: o cliente NÃO PODE presumir que o servidor vai retornar a mesma duração de cache para todas as respostas. O servidor PODE escolher durações de cache diferentes para respostas diferentes, dependendo da situação. |
SizeConstraints
As restrições nos tamanhos das listas de hash.
| Campos | |
|---|---|
max_update_entries |
O tamanho máximo em número de entradas. A atualização não vai conter mais entradas do que esse valor, mas é possível que ela tenha menos entradas do que esse valor. O valor precisa ser pelo menos 1.024. Se omitido ou zero, nenhum limite de tamanho de atualização é definido. |
max_database_entries |
Define o número máximo de entradas que o cliente quer ter no banco de dados local para a lista. O servidor PODE fazer com que o cliente armazene menos entradas. Se omitido ou zero, nenhum limite de tamanho do banco de dados é definido. |
ThreatAttribute
Atributos de ameaças. Esses atributos podem conferir um significado adicional a uma ameaça específica, mas não afetam o tipo de ameaça. Por exemplo, um atributo pode especificar uma confiança menor, enquanto outro pode especificar uma confiança maior. Mais atributos poderão ser adicionados no futuro.
| Enums | |
|---|---|
THREAT_ATTRIBUTE_UNSPECIFIED |
Atributo desconhecido. Se isso for retornado pelo servidor, o cliente vai ignorar completamente o FullHashDetail que o contém. |
CANARY |
Indica que o threat_type não deve ser usado para aplicação. |
FRAME_ONLY |
Indica que o threat_type só pode ser usado para aplicação em frames. |
ThreatType
Tipos de ameaças.
| Enums | |
|---|---|
THREAT_TYPE_UNSPECIFIED |
Tipo de ameaça desconhecido. Se isso for retornado pelo servidor, o cliente vai ignorar completamente o FullHashDetail que o contém. |
MALWARE |
Tipo de ameaça de malware. Malware é qualquer software ou aplicativo para dispositivos móveis projetado especificamente para causar danos a um computador, dispositivo móvel, bem como a usuários ou outro software. Além disso, o malware apresenta um comportamento malicioso que pode incluir a instalação de software sem o consentimento do usuário e a instalação de software nocivo, como vírus. Saiba mais aqui. |
SOCIAL_ENGINEERING |
Tipo de ameaça de engenharia social. As páginas de engenharia social fingem agir em nome de terceiros com a intenção de confundir os espectadores para que realizem uma ação em que confiariam apenas em um agente real desse terceiro. O phishing é um tipo de engenharia social que engana o usuário para que ele realize a ação específica de fornecer informações, como credenciais de login. Saiba mais aqui. |
UNWANTED_SOFTWARE |
Tipo de ameaça de software indesejado. Software indesejado é qualquer software que não adere aos Princípios de Software do Google, mas não é malware. |
POTENTIALLY_HARMFUL_APPLICATION |
Tipo de ameaça de app potencialmente nocivo usado pelo Google Play Protect para a Play Store. |