Índice
SafeBrowsing(interfaz)BatchGetHashListsRequest(mensaje)BatchGetHashListsResponse(mensaje)FullHash(mensaje)FullHash.FullHashDetail(mensaje)GetHashListRequest(mensaje)HashList(mensaje)HashListMetadata(mensaje)HashListMetadata.HashLength(enumeración)LikelySafeType(enumeración)ListHashListsRequest(mensaje)ListHashListsResponse(mensaje)RiceDeltaEncoded128Bit(mensaje)RiceDeltaEncoded256Bit(mensaje)RiceDeltaEncoded32Bit(mensaje)RiceDeltaEncoded64Bit(mensaje)SearchHashesRequest(mensaje)SearchHashesResponse(mensaje)SizeConstraints(mensaje)ThreatAttribute(enumeración)ThreatType(enumeración)
Navegación segura
Las APIs de Safe Browsing permiten que los clientes verifiquen los recursos web (en su mayoría, URLs) con las listas de recursos web no seguros de Google, que se actualizan constantemente.
| BatchGetHashLists |
|---|
|
Obtén varias listas de hash a la vez. Es muy común que un cliente necesite obtener varias listas de hash. Se prefiere usar este método en lugar de usar el método Get normal varias veces. Este es un método de Get por lotes estándar, como se define en https://google.aip.dev/231, y el método HTTP también es GET. |
| GetHashList |
|---|
|
Obtén el contenido más reciente de una lista de hash. Una lista de hash puede ser una lista de amenazas o una lista que no es de amenazas, como la caché global. Este es un método GET estándar, como se define en https://google.aip.dev/131, y el método HTTP también es GET. |
| ListHashLists |
|---|
|
Enumera las listas de hash. En la API de V5, Google nunca quitará una lista de hash que haya mostrado este método. Esto permite que los clientes omitan el uso de este método y simplemente codifiquen todas las listas de hash que necesitan. Este es un método de lista estándar, como se define en https://google.aip.dev/132, y el método HTTP es GET. |
| SearchHashes |
|---|
|
Busca hashes completos que coincidan con los prefijos especificados. Este es un método personalizado según se define en https://google.aip.dev/136 (el método personalizado hace referencia a que este método tiene un nombre personalizado dentro de la nomenclatura general de desarrollo de la API de Google; no se refiere al uso de un método HTTP personalizado). |
BatchGetHashListsRequest
La solicitud para obtener varias listas de hash al mismo tiempo.
| Campos | |
|---|---|
names[] |
Es obligatorio. Los nombres de las listas de hash en particular La lista PUEDE ser una lista de amenazas o la caché global. Los nombres NO DEBEN contener duplicados. De lo contrario, el cliente recibirá un error. |
version[] |
Las versiones de la lista de hash que ya tiene el cliente. Si es la primera vez que el cliente recupera las listas de hash, el campo debe dejarse vacío. De lo contrario, el cliente debe proporcionar las versiones que recibió anteriormente del servidor. El cliente NO DEBE manipular esos bytes. El cliente no necesita enviar las versiones en el mismo orden que los nombres de las listas correspondientes. El cliente puede enviar menos o más versiones en una solicitud que la cantidad de nombres. Sin embargo, el cliente NO DEBE enviar varias versiones que correspondan al mismo nombre. De lo contrario, el cliente recibirá un error. Nota histórica: En la versión 4 de la API, se llamaba |
desired_hash_length |
Es la longitud deseada del prefijo de hash de los valores hash que se muestran en bytes. Luego, el servidor mostrará todos los prefijos de hash con esta longitud especificada. Las diferentes listas de hash tienen diferentes requisitos para los valores aceptables del campo En el caso de |
size_constraints |
Las restricciones de tamaño de cada lista Si se omite, no hay restricciones. Ten en cuenta que los tamaños aquí son por lista, no agregados en todas las listas. |
BatchGetHashListsResponse
La respuesta contiene varias listas de hash.
| Campos | |
|---|---|
hash_lists[] |
Las listas de hash en el mismo orden que se indica en la solicitud |
FullHash
El hash completo identificado con una o más coincidencias
| Campos | |
|---|---|
full_hash |
El hash completo coincidente Este es el hash SHA256. La longitud será exactamente de 32 bytes. |
full_hash_details[] |
Lista sin ordenar. Es un campo repetido que identifica los detalles relevantes para este hash completo. |
FullHashDetail
Detalles sobre un hash completo coincidente
Nota importante sobre la retrocompatibilidad: El servidor puede agregar nuevos tipos y atributos de amenazas en cualquier momento. Esas incorporaciones se consideran cambios de versión menores. Es política de Google no exponer números de versión secundaria en las APIs (consulta https://cloud.google.com/apis/design/versioning para conocer la política de control de versiones), por lo que los clientes DEBEN estar preparados para recibir mensajes FullHashDetail que contengan valores de enumeración ThreatType o ThreatAttribute que el cliente considere no válidos. Por lo tanto, es responsabilidad del cliente verificar la validez de todos los valores de enumeración ThreatType y ThreatAttribute. Si se considera que algún valor no es válido, el cliente DEBE ignorar todo el mensaje FullHashDetail.
| Campos | |
|---|---|
threat_type |
El tipo de amenaza. Este campo nunca estará vacío. |
attributes[] |
Lista sin ordenar. Atributos adicionales sobre esos hashes completos. Puede estar vacío. |
GetHashListRequest
Es una solicitud para obtener una lista de hash, que puede ser una lista de amenazas o una lista que no es de amenazas, como la caché global.
Novedades de la versión 5: Para mayor claridad, se cambió el nombre de states en la versión 4 a version. Las listas ahora tienen nombres, y se quitaron los tipos de plataformas y los tipos de entradas de amenazas. Ahora es posible que varias listas tengan el mismo tipo de amenaza o que una sola lista se ocupe de varios tipos de amenazas. Los clientes tienen la nueva capacidad de especificar una longitud de hash deseada. Esta es parte de la respuesta a los prefijos de hash de longitud variable de la V4, que causaron problemas en muchas implementaciones de clientes: todos los hash de una lista ahora tienen una sola longitud, lo que permite implementaciones de clientes mucho más eficientes. Se simplificaron las restricciones y se quitó el tipo de compresión (siempre se aplica la compresión).
| Campos | |
|---|---|
name |
Es obligatorio. Es el nombre de esta lista de hash en particular. Puede ser una lista de amenazas o la caché global. |
version |
Es la versión de la lista de hash que ya tiene el cliente. Si es la primera vez que el cliente recupera la lista de hash, este campo DEBE estar vacío. De lo contrario, el cliente DEBE proporcionar la versión que recibió anteriormente del servidor. El cliente NO DEBE manipular esos bytes. Novedades de la versión 5: En la versión 4 de la API, se llamaba |
desired_hash_length |
Es la longitud deseada del prefijo de hash de los valores hash que se muestran en bytes. Luego, el servidor mostrará todos los prefijos de hash con esta longitud especificada. Las diferentes listas de hash tienen diferentes requisitos para los valores aceptables del campo |
size_constraints |
Las restricciones de tamaño de la lista Si se omite, no hay restricciones. Se recomiendan restricciones en todos los dispositivos con potencia de procesamiento, ancho de banda o almacenamiento limitados. |
HashList
Es una lista de valores hash identificados por su nombre.
| Campos | |
|---|---|
name |
Es el nombre de la lista de hash. Ten en cuenta que la caché global también es solo una lista de hash y se puede consultar aquí. |
version |
Es la versión de la lista de hash. El cliente NO DEBE manipular esos bytes. |
partial_update |
Cuando es verdadero, se trata de una diferencia parcial que contiene elementos agregados y quitados según lo que el cliente ya tiene. Cuando es falso, esta es la lista de hash completa. Cuando es falso, el cliente DEBE borrar cualquier versión almacenada de forma local para esta lista de hash. Esto significa que la versión que tiene el cliente está muy desactualizada o que se cree que los datos del cliente están dañados. El campo Cuando es verdadero, el cliente DEBE aplicar una actualización incremental mediante la eliminación y, luego, la adición de elementos. |
compressed_removals |
Es la versión codificada con delta-Rice de los índices de eliminación. Dado que cada lista de hash tiene menos de 2^32 entradas, los índices se tratan como números enteros de 32 bits y se codifican. |
minimum_wait_duration |
Los clientes deben esperar al menos este tiempo para volver a obtener la lista de hash. Si se omite o es cero, los clientes DEBEN recuperarlo de inmediato porque indica que el servidor tiene una actualización adicional para enviarle al cliente, pero no pudo hacerlo debido a las restricciones especificadas por el cliente. |
sha256_checksum |
La lista ordenada de todos los hashes, nuevamente con hash SHA256 Esta es la suma de comprobación de la lista ordenada de todos los valores hash presentes en la base de datos después de aplicar la actualización proporcionada. En caso de que no se hayan proporcionado actualizaciones, el servidor omitirá este campo para indicar que el cliente debe usar la suma de verificación existente. |
metadata |
Metadatos sobre la lista de hash. El método |
Campo de unión compressed_additions. Es la versión codificada en Rice-delta de las incorporaciones. Las longitudes de los prefijos hash de las incorporaciones son uniformes en todas las incorporaciones de la lista. Es el desired_hash_length que envía el cliente o un valor que elige el servidor si el cliente omite ese campo. compressed_additions puede ser solo uno de los siguientes: |
|
additions_four_bytes |
Las adiciones de 4 bytes |
additions_eight_bytes |
Las adiciones de 8 bytes |
additions_sixteen_bytes |
Las adiciones de 16 bytes |
additions_thirty_two_bytes |
Las adiciones de 32 bytes |
HashListMetadata
Metadatos sobre una lista de hash en particular
| Campos | |
|---|---|
threat_types[] |
Lista sin ordenar. Si no está vacía, especifica que la lista de hash es un tipo de lista de amenazas y enumera el tipo de amenazas asociadas con los valores hash o los prefijos de hash en esta lista. Puede estar vacío si la entrada no representa una amenaza, es decir, en el caso de que represente un tipo seguro. |
likely_safe_types[] |
Lista sin ordenar. Si no está vacía, especifica que la lista de hash representa una lista de hashes que probablemente sean seguros y enumera las formas en que se consideran seguros. Este campo es mutuamente excluyente con el campo threat_types. |
description |
Es una descripción legible por humanos de esta lista. Debe estar escrito en inglés. |
supported_hash_lengths[] |
Las longitudes de hash compatibles para esta lista de hash. Cada lista de hash admitiría al menos una longitud. Por lo tanto, este campo no estará vacío. |
hash_length |
Es la longitud de hash compatible para esta lista de hash. Cada lista de hash admitirá exactamente una longitud. Si se introduce una longitud de hash diferente para el mismo conjunto de tipos de amenazas o tipos seguros, se incluirá como una lista independiente con un nombre distinto y el conjunto de longitud de hash correspondiente. |
HashLength
Es la longitud de los hashes en una lista de hashes.
| Enumeraciones | |
|---|---|
HASH_LENGTH_UNSPECIFIED |
Longitud no especificada. El servidor no mostrará este valor en las respuestas al cliente (en el campo supported_hash_lengths), pero el cliente puede enviar este valor al servidor (en el campo desired_hash_length), en cuyo caso el servidor elegirá un valor automáticamente. Los clientes DEBEN permitir que el servidor elija un valor. |
FOUR_BYTES |
Cada hash es un prefijo de cuatro bytes. |
EIGHT_BYTES |
Cada hash es un prefijo de ocho bytes. |
SIXTEEN_BYTES |
Cada hash es un prefijo de dieciséis bytes. |
THIRTY_TWO_BYTES |
Cada hash es un hash completo de treinta y dos bytes. |
LikelySafeType
Tipos de sitios que probablemente sean seguros
Ten en cuenta que SearchHashesResponse no contiene LikelySafeType de forma intencional.
| Enumeraciones | |
|---|---|
LIKELY_SAFE_TYPE_UNSPECIFIED |
Desconocido. |
GENERAL_BROWSING |
Es probable que este sitio sea lo suficientemente seguro para la navegación general. Esto también se conoce como caché global. |
CSD |
Es probable que este sitio sea lo suficientemente seguro como para que no sea necesario ejecutar modelos de detección del cliente ni verificaciones de protección con contraseña. |
DOWNLOAD |
Es probable que este sitio sea lo suficientemente seguro como para que no se deban verificar las descargas. |
ListHashListsRequest
La solicitud para enumerar las listas de hash disponibles.
| Campos | |
|---|---|
page_size |
Es la cantidad máxima de listas de hash que se mostrarán. El servicio puede mostrar menos que este valor. Si no se especifica, el servidor elegirá un tamaño de página, que puede ser mayor que la cantidad de listas de hash para que no sea necesaria la paginación. |
page_token |
Un token de página, recibido desde una llamada |
ListHashListsResponse
La respuesta que contiene metadatos sobre las listas de hash
| Campos | |
|---|---|
hash_lists[] |
Las listas de hash en un orden arbitrario Solo se incluirán los metadatos de las listas de hash, no el contenido. |
next_page_token |
Un token, que se puede enviar como |
RiceDeltaEncoded128Bit
Es igual que RiceDeltaEncoded32Bit, excepto que codifica números de 128 bits.
| Campos | |
|---|---|
first_value_hi |
Los 64 bits superiores de la primera entrada de los datos codificados (hashes) Si el campo está vacío, los 64 bits superiores son todos cero. |
first_value_lo |
Los 64 bits inferiores de la primera entrada de los datos codificados (hashes) Si el campo está vacío, los 64 bits inferiores son todos cero. |
rice_parameter |
El parámetro Golomb-Rice Se garantiza que este parámetro esté entre 99 y 126 inclusive. |
entries_count |
Es la cantidad de entradas que se codifican delta en los datos codificados. Si solo se codificó un número entero, este será cero y el valor único se almacenará en |
encoded_data |
Son los deltas codificados con el codificador Golomb-Rice. |
RiceDeltaEncoded256Bit
Es igual que RiceDeltaEncoded32Bit, excepto que codifica números de 256 bits.
| Campos | |
|---|---|
first_value_first_part |
Los primeros 64 bits de la primera entrada de los datos codificados (hashes) Si el campo está vacío, los primeros 64 bits son todos cero. |
first_value_second_part |
Los bits del 65 al 128 de la primera entrada de los datos codificados (hashes) Si el campo está vacío, los bits del 65 al 128 son todos cero. |
first_value_third_part |
Los bits del 129 al 192 de la primera entrada de los datos codificados (hashes) Si el campo está vacío, los bits del 129 al 192 son todos cero. |
first_value_fourth_part |
Los últimos 64 bits de la primera entrada de los datos codificados (hashes) Si el campo está vacío, los últimos 64 bits son todos cero. |
rice_parameter |
El parámetro Golomb-Rice Se garantiza que este parámetro esté entre 227 y 254 inclusive. |
entries_count |
Es la cantidad de entradas que se codifican delta en los datos codificados. Si solo se codificó un número entero, este será cero y el valor único se almacenará en |
encoded_data |
Son los deltas codificados con el codificador Golomb-Rice. |
RiceDeltaEncoded32Bit
Los datos codificados de Rice-Golomb. Se usa para hashes o índices de eliminación. Se garantiza que cada hash o índice tenga la misma longitud, que es exactamente de 32 bits.
En términos generales, si ordenamos todas las entradas de forma lexicográfica, veremos que los bits de orden superior tienden a no cambiar con tanta frecuencia como los de orden inferior. Esto significa que, si también tomamos la diferencia adyacente entre las entradas, los bits de orden superior tienen una alta probabilidad de ser cero. Esto aprovecha esta alta probabilidad de cero eligiendo esencialmente una cantidad determinada de bits. Es probable que todos los bits más significativos que esta sean cero, por lo que usamos la codificación unaria. Consulta el campo rice_parameter.
Nota histórica: La codificación Rice-delta se usó por primera vez en la versión 4 de esta API. En la versión 5, se realizaron dos mejoras significativas: en primer lugar, la codificación Rice-delta ahora está disponible con prefijos de hash de más de 4 bytes; en segundo lugar, los datos codificados ahora se tratan como números grandes para evitar un paso de ordenamiento costoso.
| Campos | |
|---|---|
first_value |
La primera entrada de los datos codificados (hashes o índices) o, si solo se codificó un solo prefijo o índice de hash, el valor de esa entrada. Si el campo está vacío, la entrada es cero. |
rice_parameter |
El parámetro Golomb-Rice Se garantiza que este parámetro esté entre 3 y 30 inclusive. |
entries_count |
Es la cantidad de entradas que se codifican delta en los datos codificados. Si solo se codificó un número entero, este será cero y el valor único se almacenará en |
encoded_data |
Son los deltas codificados con el codificador Golomb-Rice. |
RiceDeltaEncoded64Bit
Es igual que RiceDeltaEncoded32Bit, excepto que codifica números de 64 bits.
| Campos | |
|---|---|
first_value |
La primera entrada de los datos codificados (hashes) o, si solo se codificó un solo prefijo de hash, el valor de esa entrada. Si el campo está vacío, la entrada es cero. |
rice_parameter |
El parámetro Golomb-Rice Se garantiza que este parámetro esté entre 35 y 62 inclusive. |
entries_count |
Es la cantidad de entradas que se codifican delta en los datos codificados. Si solo se codificó un número entero, este será cero y el valor único se almacenará en |
encoded_data |
Son los deltas codificados con el codificador Golomb-Rice. |
SearchHashesRequest
Es una solicitud que emite el cliente para buscar prefijos de hash específicos.
Está diseñado para buscar solo en listas de amenazas y no en listas que no sean de amenazas, como la caché global.
Novedades de la versión 5: Los clientes no necesitan especificar un ClientInfo ni los estados de las listas de hash en su base de datos local. Esto es para mejorar la privacidad. Además, los clientes no necesitan enviar los tipos de amenazas que les interesan.
| Campos | |
|---|---|
hash_prefixes[] |
Es obligatorio. Los prefijos hash que se buscarán. Los clientes NO DEBEN enviar más de 1,000 prefijos de hash. Sin embargo, después de seguir el procedimiento de procesamiento de URLs, los clientes NO DEBEN enviar más de 30 prefijos de hash. Actualmente, cada prefijo de hash debe tener exactamente 4 bytes de longitud. Es POSIBLE que esto se flexibilice en el futuro. |
filter |
Opcional. Si al cliente le interesa filtrar, por ejemplo, solo recuperar tipos específicos de amenazas, se puede especificar. Si se omite, se muestran todas las amenazas que coincidan. Se recomienda omitir esta opción para obtener la protección más completa que puede ofrecer la Navegación segura. El filtro se especifica con el lenguaje de expresión común de Google, que se encuentra en https://github.com/google/cel-spec junto con ejemplos generales. Estos son algunos ejemplos específicos que se pueden usar aquí: El filtro El filtro |
SearchHashesResponse
Es la respuesta que se muestra después de buscar hashes de amenazas.
Si no se encuentra nada, el servidor mostrará un estado OK (código de estado HTTP 200) con el campo full_hashes vacío, en lugar de mostrar un estado NOT_FOUND (código de estado HTTP 404).
Novedades de la versión 5: Hay una separación entre FullHash y FullHashDetail. En el caso de que un hash represente un sitio con varias amenazas (p.ej., MALWARE y SOCIAL_ENGINEERING), no es necesario enviar el hash completo dos veces como en la V4. Además, la duración de la caché se simplificó en un solo campo cache_duration.
| Campos | |
|---|---|
full_hashes[] |
Lista sin ordenar. Se encontró la lista desordenada de hashes completos. |
cache_duration |
Es la duración de la caché del cliente. El cliente DEBE agregar esta duración a la hora actual para determinar la hora de vencimiento. Luego, el tiempo de vencimiento se aplica a cada prefijo de hash que consulta el cliente en la solicitud, independientemente de la cantidad de hashes completos que se muestran en la respuesta. Incluso si el servidor no muestra hashes completos para un prefijo de hash en particular, el cliente TAMBIÉN DEBE almacenar en caché este hecho. Solo si el campo Importante: El cliente NO DEBE suponer que el servidor mostrará la misma duración de la caché para todas las respuestas. El servidor PUEDE elegir diferentes duraciones de almacenamiento en caché para diferentes respuestas según la situación. |
SizeConstraints
Las restricciones sobre los tamaños de las listas de hash
| Campos | |
|---|---|
max_update_entries |
Es el tamaño máximo en cantidad de entradas. La actualización no contendrá más entradas que este valor, pero es posible que contenga menos. DEBE ser de al menos 1,024. Si se omite o se establece en cero, no se establece ningún límite de tamaño de actualización. |
max_database_entries |
Establece la cantidad máxima de entradas que el cliente desea tener en la base de datos local para la lista. (Es POSIBLE que el servidor haga que el cliente almacene menos de esta cantidad de entradas). Si se omite o se establece en cero, no se establece ningún límite de tamaño de la base de datos. |
ThreatAttribute
Atributos de amenazas. Estos atributos pueden otorgar un significado adicional a una amenaza en particular, pero no afectarán el tipo de amenaza. Por ejemplo, un atributo puede especificar una confianza más baja, mientras que otro atributo puede especificar una confianza más alta. Es posible que se agreguen más atributos en el futuro.
| Enumeraciones | |
|---|---|
THREAT_ATTRIBUTE_UNSPECIFIED |
Atributo desconocido. Si el servidor muestra esto, el cliente debe ignorar el FullHashDetail que lo contiene por completo. |
CANARY |
Indica que no se debe usar threat_type para la aplicación forzosa. |
FRAME_ONLY |
Indica que threat_type solo debe usarse para la aplicación forzosa en marcos. |
ThreatType
Tipos de amenazas
| Enumeraciones | |
|---|---|
THREAT_TYPE_UNSPECIFIED |
Tipo de amenaza desconocido. Si el servidor muestra esto, el cliente debe ignorar el FullHashDetail que lo contiene por completo. |
MALWARE |
Tipo de amenaza de software malicioso. Un software malicioso es cualquier software o aplicación que se diseña específicamente para dañar una computadora, un dispositivo móvil, el software que lo ejecuta o a los usuarios. Su objetivo es llevar a cabo una acción malintencionada, como instalar software dañino (por ejemplo, virus) o programas sin el consentimiento del usuario. Puedes obtener más información en este vínculo. |
SOCIAL_ENGINEERING |
Tipo de amenaza de ingeniería social. Las páginas de ingeniería social pretenden actuar falsamente en nombre de un tercero con la intención de confundir a los usuarios para que realicen una acción en la que solo confiarían en un agente real de ese tercero. El phishing es un tipo de ingeniería social que engaña al usuario para que realice la acción específica de proporcionar información, como credenciales de acceso. Puedes obtener más información en este vínculo. |
UNWANTED_SOFTWARE |
Tipo de amenaza de software no deseado. El software no deseado es cualquier software que no cumpla con los Principios de Software de Google, pero que no sea software malicioso. |
POTENTIALLY_HARMFUL_APPLICATION |
Tipo de amenaza de aplicación potencialmente dañina como lo usa Google Play Protect para Play Store. |