Í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(tipo enumerado)
SafeBrowsing
As APIs de Navegação segura permitem que os clientes verifiquem recursos da Web (geralmente URLs) em relação às listas do Google de recursos inseguros da Web, que são constantemente atualizadas.
| BatchGetHashLists |
|---|
|
Receba várias listas de hash de uma só vez. É muito comum que um cliente precise de várias listas de hash. É preferível usar esse método em vez de usar o método GET normal várias vezes. Este é um método GET padrão em lote, conforme definido por https://google.aip.dev/231, e o método HTTP também é GET. |
| GetHashList |
|---|
|
Receber o conteúdo mais recente de uma lista de hash. Uma lista de hash pode ser gerada por uma lista de ameaças ou não relacionada a ameaças, como o cache global. Esse é um método GET padrão, conforme definido por https://google.aip.dev/131 (link em inglês), e o método HTTP também é GET. |
| ListHashLists |
|---|
|
Listar listas de hash. Na API V5, o Google nunca remove uma lista de hash que já foi retornada por esse método. Isso permite que os clientes pulem o uso desse método e codifiquem todas as listas de hash necessárias. Este é um método List padrão, conforme definido por 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 por https://google.aip.dev/136 (link em inglês). Esse método tem um nome personalizado na nomenclatura geral de desenvolvimento de API do Google, não se refere ao uso de um método HTTP personalizado. |
BatchGetHashListsRequest
Solicitação para receber várias listas de hash 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 pode ser o cache global. Os nomes NÃO PODEM conter cópias; se tiverem, o cliente receberá um erro. |
version[] |
As versões da lista de hash que o cliente já tem. Se esta for a primeira vez que o cliente estiver buscando as listas de hash, o campo precisará ser deixado em branco. Caso contrário, o cliente precisará 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 que os nomes das listas correspondentes. O cliente pode enviar menos ou mais 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 tiver enviado, o cliente receberá um erro. Observação histórica: na V4 da API, era chamado de |
desired_hash_length |
O tamanho desejado do prefixo de hash dos hashes retornados em bytes. O servidor retornará todos os prefixos de hash nesse tamanho especificado. Listas de hash diferentes têm requisitos distintos sobre 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. Observe que os tamanhos são por lista, e 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 dada na solicitação. |
FullHash
O hash completo identificado com uma ou mais correspondências.
| Campos | |
|---|---|
full_hash |
O hash completo correspondente. Esse é 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.
Uma observação importante sobre compatibilidade futura: novos tipos de ameaça e atributos de ameaça podem ser adicionados pelo servidor a qualquer momento; essas adições são consideradas pequenas alterações de versão. É política do Google não expor números de versão secundários nas APIs (consulte https://cloud.google.com/apis/design/versioning para a política de controle de versões). Por isso, os clientes PRECISAM estar preparados para receber mensagens FullHashDetail contendo valores de tipo enumerado ThreatType ou valores de tipo enumerado 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. Este campo nunca ficará vazio. |
attributes[] |
Lista não ordenada. Atributos adicionais sobre esses hashes completos. Esse campo pode estar vazio. |
GetHashListRequest
Uma solicitação para receber uma lista de hash, que pode ser uma lista de ameaças ou uma lista não relacionada, como o cache global.
Novidades na V5: o que anteriormente era chamado de states na V4 foi renomeado como version para maior clareza. As listas agora são nomeadas, os tipos de plataforma e os tipos de entrada de ameaças foram removidos. Agora é possível que várias listas tenham o mesmo tipo de ameaça ou uma única lista relacionada a vários tipos de ameaça. Os clientes podem especificar um tamanho de hash desejado. Isso faz parte da resposta aos prefixos de hash de tamanho variável da V4, que causaram problemas em muitas implementações de clientes: todos os hashes em uma lista agora têm um único tamanho, 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 hash 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 hash, esse campo PRECISA ser deixado em branco. Caso contrário, o cliente DEVE fornecer a versão recebida anteriormente do servidor. O cliente NÃO PODE manipular esses bytes. Novidades na V5: na V4 da API, esse recurso era chamado de |
desired_hash_length |
O tamanho desejado do prefixo de hash dos hashes retornados em bytes. O servidor retornará todos os prefixos de hash nesse tamanho especificado. Listas de hash diferentes têm requisitos distintos sobre 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 por seu nome.
| Campos | |
|---|---|
name |
O nome da lista de hash. O cache global também é apenas uma lista de hash e pode ser referenciado aqui. |
version |
A versão da lista de hash. O cliente NÃO PODE manipular esses bytes. |
partial_update |
Quando verdadeiro, essa diferença é parcial, mas contém adições e remoções com base no que o cliente já tem. Quando definido como falso, esta é a lista completa de hash. Quando definido como "false", o cliente PRECISA excluir qualquer versão armazenada localmente para essa lista de hash. Isso significa que a versão que o cliente possui está seriamente desatualizada ou os dados dele estão corrompidos. O campo Quando verdadeiro, o cliente PRECISA aplicar uma atualização incremental aplicando remoções e, em seguida, adições. |
compressed_removals |
A versão codificada de Rice-delta 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 acessar a lista de hashes novamente. Se omitido ou zero, os clientes DEVEM buscar imediatamente porque isso indica que o servidor tem uma atualização adicional a ser enviada ao cliente, mas não conseguiu devido às restrições especificadas pelo cliente. |
metadata |
Metadados sobre a lista de hash. Isso não é preenchido pelo método |
Campo de união compressed_additions. A versão de adições codificada em delta de arroz. O tamanho das adições do prefixo de hash é uniforme em todas as adições na lista. Ele é 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. |
Campo de união checksum. Essa é a soma de verificação da lista classificada de todos os hashes presentes no banco de dados após a atualização fornecida. Este é um campo "oneof" para permitir vários algoritmos de hash. Também é possível que o servidor omita esse campo (caso nenhuma atualização tenha sido fornecida) para indicar que o cliente precisa usar a soma de verificação atual. checksum só pode ser de um dos seguintes tipos: |
|
sha256_checksum |
A lista classificada de todos os hashes, novamente com hash com SHA256. |
HashListMetadata
Metadados sobre uma lista de hash específica.
| Campos | |
|---|---|
threat_types[] |
Lista não ordenada. Se não estiver vazio, especifica que a lista de hash é 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 em branco se a entrada não representar uma ameaça, ou seja, no caso de representar um tipo provável seguro. |
likely_safe_types[] |
Lista não ordenada. Se não estiver vazio, esse atributo especifica que a lista de hash representa uma lista de prováveis hashes seguros e enumera as maneiras como eles são considerados prováveis seguros. Esse campo é mutuamente exclusivo com o campo threat_types. |
mobile_optimized |
Indica se a lista está otimizada para dispositivos móveis (Android e iOS). |
description |
Uma descrição legível sobre esta lista. Escrita em inglês. |
supported_hash_lengths[] |
Os comprimentos de hash compatíveis com esta lista de hash. Cada lista de hash pode ter pelo menos um comprimento. Este campo, portanto, não estará vazio. |
HashLength
O tamanho dos hashes em uma lista de hashes.
| Tipos enumerados | |
|---|---|
HASH_LENGTH_UNSPECIFIED |
Tamanho não especificado. O servidor não vai retornar esse valor nas respostas ao cliente (no campo supported_hash_lengths), mas o cliente tem permissão para enviar esse valor para o servidor (no campo desired_hash_length). Nesse caso, o servidor escolherá um valor automaticamente. Os clientes DEVEM deixar o servidor selecionar 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 que podem ser seguros.
Observe que o SearchHashesResponse intencionalmente não contém LikelySafeType.
| Tipos enumerados | |
|---|---|
LIKELY_SAFE_TYPE_UNSPECIFIED |
Desconhecido. |
GENERAL_BROWSING |
É provável que este site seja seguro o suficiente para a navegação geral. Isso também é conhecido como cache global. |
CSD |
É provável que este 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 de senha. |
DOWNLOAD |
Este site provavelmente é seguro o suficiente para que os downloads do site 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 hash a serem retornadas. O serviço pode retornar menos que esse valor. Se não for especificado, o servidor escolherá um tamanho de página, que pode ser maior do 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 contendo metadados sobre listas de hash.
| Campos | |
|---|---|
hash_lists[] |
O hash é listado em uma ordem arbitrária. Somente os metadados sobre as listas de hash serão incluídos, não o conteúdo. |
next_page_token |
Um token, que pode ser enviado como |
RiceDeltaEnencoded128Bit
Funciona da mesma forma que RiceDeltaEncoded32Bit, mas codifica números de 128 bits.
| Campos | |
|---|---|
first_value_hi |
Os 64 bits mais altos 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 está entre 99 e 126, inclusive. |
entries_count |
O número de entradas com codificação delta nos dados codificados. Se apenas um número inteiro for codificado, esse valor será zero e o valor único será armazenado em |
encoded_data |
Os deltas codificados que são codificados usando o codificador Golomb-Rice. |
RiceDeltaEnencoded256bit
O mesmo que RiceDeltaEncoded32Bit, mas codifica 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 65 a 128 bits da primeira entrada nos dados codificados (hashes). Se o campo estiver vazio, os 65 a 128 bits serão todos zero. |
first_value_third_part |
Os 129 a 192 bits da primeira entrada nos dados codificados (hashes). Se o campo estiver vazio, os 129 a 192 bits 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 está garantido entre 227 e 254. |
entries_count |
O número de entradas com codificação delta nos dados codificados. Se apenas um número inteiro for codificado, esse valor será zero e o valor único será armazenado em |
encoded_data |
Os deltas codificados que são codificados usando o codificador Golomb-Rice. |
RiceDeltaEnencoded32bit
Os dados codificados em Rice-Golomb. Usado para hashes ou índices de remoção. É garantido que cada hash ou índice aqui tenha o mesmo comprimento, e esse comprimento é de exatamente 32 bits.
De modo geral, se classificarmos todas as entradas lexicograficamente, descobriremos que os bits de ordem superior tendem a não mudar com a mesma frequência que os bits de ordem inferior. Isso significa que, se também tomarmos a diferença adjacente entre as entradas, os bits de ordem superior terão uma alta probabilidade de serem zero. Isso explora essa alta probabilidade de zero essencialmente escolhendo um certo número de bits. Todos os bits mais significativos que isso provavelmente são zero, por isso usamos codificação unária. Veja o campo rice_parameter.
Observação histórica: a codificação delta de arroz foi usada pela primeira vez na V4 dessa API. Na V5, duas melhorias significativas foram feitas: primeiro, a codificação delta do arroz agora está disponível com prefixos de hash com mais de 4 bytes; em segundo lugar, os dados codificados agora são tratados como big-endian para evitar uma etapa de classificação dispendiosa.
| Campos | |
|---|---|
first_value |
a primeira entrada nos dados codificados (hashes ou índices) ou, se apenas um prefixo de hash ou índice 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 está entre 3 e 30, inclusive. |
entries_count |
O número de entradas com codificação delta nos dados codificados. Se apenas um número inteiro for codificado, esse valor será zero e o valor único será armazenado em |
encoded_data |
Os deltas codificados que são codificados usando o codificador Golomb-Rice. |
RiceDeltaEnencoded64bit
O mesmo que RiceDeltaEncoded32Bit, mas codifica números de 64 bits.
| Campos | |
|---|---|
first_value |
A primeira entrada nos dados codificados (hashes) ou, se apenas um prefixo 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 certamente está entre 35 e 62. |
entries_count |
O número de entradas com codificação delta nos dados codificados. Se apenas um número inteiro for codificado, esse valor será zero e o valor único será armazenado em |
encoded_data |
Os deltas codificados que são codificados usando o codificador Golomb-Rice. |
SearchHashesRequest
Uma solicitação que o cliente emite para pesquisar prefixos de hash específicos.
Ele foi desenvolvido para pesquisar apenas listas de ameaças, e não listas que não são ameaças, como o Cache global.
Novidades na V5: os clientes não precisam especificar um ClientInfo nem os estados das listas de hash no banco de dados local. Isso é para melhorar a privacidade. Além disso, os clientes não precisam informar quais tipos de ameaça 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 DEVEM enviar mais de 30 prefixos de hash. Atualmente, cada prefixo de hash precisa ter exatamente 4 bytes. Isso PODE ser amenizado no futuro. |
filter |
Opcional. Se o cliente estiver interessado em filtrar, por exemplo, apenas para recuperar tipos específicos de ameaças, isso pode 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 o recurso 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 (link em inglês), além de exemplos gerais. Aqui estão 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ça.
Se nada for encontrado, o servidor 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. No caso em que um hash representa um site que apresenta várias ameaças (por exemplo, MALWARE e SOCIAL_engineERING), o hash completo não precisa ser enviado 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 foi encontrada. |
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 prazo de validade. O prazo de validade é aplicado a cada prefixo de hash consultado pelo cliente na solicitação, independentemente de quantos hashes completos forem 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. Somente se o campo Importante: o cliente NÃO PODE presumir que o servidor retornará a mesma duração de cache para todas as respostas. O servidor PODE escolher durações de cache diferentes para respostas distintas, dependendo da situação. |
SizeConstraints
As restrições dos tamanhos das listas de hash.
| Campos | |
|---|---|
max_update_entries |
O tamanho máximo em número de entradas. A atualização não conterá mais entradas do que esse valor, mas é possível que a atualização contenha menos entradas do que este valor. PRECISA ser pelo menos 1.024. Se omitido ou zero, nenhum limite de tamanho de atualização será definido. |
max_database_entries |
Define o número máximo de entradas que o cliente está disposto a ter no banco de dados local para a lista. O servidor PODE fazer com que o cliente armazene menos que esse número de entradas. Se omitido ou zero, nenhum limite de tamanho do banco de dados será definido. |
ThreatAttribute
Atributos das ameaças. Esses atributos podem conferir um significado adicional a uma ameaça específica, mas não afetam o tipo dela. Por exemplo, um atributo pode especificar uma confiança mais baixa, enquanto um atributo diferente pode especificar uma confiança mais alta. Mais atributos podem ser adicionados no futuro.
| Tipos enumerados | |
|---|---|
THREAT_ATTRIBUTE_UNSPECIFIED |
Atributo desconhecido. Se esse valor for retornado pelo servidor, o cliente precisará desconsiderar completamente o FullHashDetail. |
CANARY |
Indica que o threat_type não deve ser usado para aplicação. |
FRAME_ONLY |
Indica que o threat_type deve ser usado apenas para a aplicação em frames. |
ThreatType
Tipos de ameaças.
| Tipos enumerados | |
|---|---|
THREAT_TYPE_UNSPECIFIED |
Tipo de ameaça desconhecido. Se esse valor for retornado pelo servidor, o cliente precisará desconsiderar completamente o FullHashDetail. |
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. Páginas de engenharia social têm a intenção falsa de agir em nome de terceiros com a intenção de confundir os espectadores, fazendo-os realizar uma ação com a qual eles confiam somente em um agente desse terceiro. Phishing é um tipo de engenharia social que engana o espectador para que 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 esteja em conformidade com os Princípios de software do Google, mas não seja malware. |
POTENTIALLY_HARMFUL_APPLICATION |
Tipo de ameaça de apps potencialmente nocivos usado pelo Google Play Protect na Play Store. |