Introducción
Nota: Actualmente, esta documentación aún está en desarrollo. Se prevén mejoras en el futuro cercano.
La Navegación segura de Google v5 es una evolución de la Navegación segura de Google v4. Los dos cambios clave que se hicieron en la v5 son la actualización de datos y la privacidad de la IP. Además, se mejoró la superficie de la API para aumentar la flexibilidad, la eficiencia y reducir el sobredimensionamiento. Además, la Navegación segura de Google v5 está diseñada para facilitar la migración de la versión 4.
Actualmente, Google ofrece v4 y v5, y ambas se consideran listas para la producción. Puedes usar la v4 o la v5. No anunciamos una fecha para la desactivación de la versión 4. Si lo hacemos, enviaremos un aviso mínimo de un año. En esta página, se describirá la versión 5 así como una guía para la migración de la versión 4 a la versión 5. La documentación completa de la versión 4 sigue disponible.
Actualidad de los datos
Una mejora significativa de la Navegación segura de Google v5 en comparación con la v4 (específicamente, la API de actualización v4) es la actualización y cobertura de los datos. Dado que la protección depende en gran medida de la base de datos local que mantiene el cliente, el retraso y el tamaño de la actualización de la base de datos local es el principal factor que contribuye a la protección perdida. En la versión 4, un cliente típico tarda entre 20 y 50 minutos en obtener la versión más actualizada de las listas de amenazas. Lamentablemente, los ataques de suplantación de identidad (phishing) se expandieron rápidamente: hasta 2021, el 60% de los sitios que entregan ataques viven menos de 10 minutos. Nuestro análisis muestra que entre el 25 y el 30% de la falta de protección contra la suplantación de identidad (phishing) se debe a la obsolescencia de los datos. Además, algunos dispositivos no están equipados para administrar todas las listas de amenazas de la Navegación segura de Google, que continúa creciendo con el paso del tiempo.
En la versión 5, presentamos un modo de operación conocido como protección en tiempo real. Esto evita el problema de inactividad de los datos que se mencionó anteriormente. En la versión 4, se espera que los clientes descarguen y mantengan una base de datos local, realicen comprobaciones de las listas de amenazas descargadas de forma local y, luego, cuando haya una coincidencia de prefijo parcial, realizar una solicitud para descargar el hash completo. En la v5, aunque los clientes deben continuar descargando y manteniendo una base de datos local de listas de amenazas, ahora también se espera que los clientes descarguen una lista de sitios probables benignos (llamada Caché Global), realicen una verificación local de esta caché global y una verificación de la lista de amenazas locales y, por último, cuando haya una coincidencia parcial de prefijo para las listas de amenazas o una no coincidencia en la caché global, realicen una solicitud para descargar los hashes completos. (Para obtener detalles sobre el procesamiento local requerido por el cliente, consulta el procedimiento proporcionado a continuación). Esto representa un cambio de permitir de forma predeterminada a verificar de forma predeterminada, lo que puede mejorar la protección a la luz de una propagación más rápida de las amenazas en la Web. En otras palabras, se trata de un protocolo diseñado para brindar protección casi en tiempo real: nuestro objetivo es que los clientes se beneficien de los datos más recientes de la Navegación segura de Google.
Privacidad de IP
La Navegación segura de Google (versiones 4 o 5) no procesa ningún elemento asociado con la identidad de un usuario durante la entrega de solicitudes. Si se envían, las cookies se ignoran. Google conoce las direcciones IP de origen de las solicitudes, pero Google solo las usa para necesidades de red esenciales (es decir, para enviar respuestas) y con fines antiDoS.
Al mismo tiempo que con la versión 5, presentamos una API complementaria conocida como API de puerta de enlace de HTTP Oblivious de Navegación segura. Esto usa HTTPOblivious para ocultar de Google las direcciones IP de los usuarios finales. Para ello, hay que hacer que un tercero que no genera conflicto administre una versión encriptada de la solicitud del usuario y, luego, la reenvíe a Google. Por lo tanto, el tercero solo tiene acceso a las direcciones IP y Google solo tiene acceso al contenido de la solicitud. El tercero opera una Retransmisión de HTTP Oblivious (como este servicio de Fastly) y Google opera la puerta de enlace HTTP Oblivious. Esta es una API complementaria opcional. Si se utiliza junto con la Navegación segura de Google, ya no se enviarán a Google las direcciones IP de los usuarios finales.
Uso adecuado
Uso permitido
La API de Navegación segura es solo para uso no comercial (es decir, "no está destinado a la venta ni a la generación de ingresos"). Si necesitas una solución con fines comerciales, consulta Web Risk.
Precios
Todas las APIs de Navegación segura de Google son sin costo.
Cuotas
A los desarrolladores se les asigna una cuota de uso predeterminada cuando habilitan la API de Navegación segura. Puedes ver la asignación y el uso actuales en la Consola para desarrolladores de Google. Si esperas usar una cuota superior a la asignada actualmente, puedes solicitar más cuota en la interfaz de cuotas de Play Console. Revisamos estas solicitudes y solicitamos que nos comuniquemos contigo cuando solicitemos un aumento de cuota para asegurarnos de que la disponibilidad de nuestro servicio satisfaga las necesidades de todos los usuarios.
URLs apropiadas
La Navegación segura de Google está diseñada para actuar sobre las URLs que se mostrarían en la barra de direcciones de un navegador. No está diseñada para comprobar con subrecursos (como JavaScript o una imagen a la que hace referencia un archivo HTML o una URL de WebSocket iniciada por JavaScript). Estas URLs de subrecursos no se deben verificar con la Navegación segura de Google.
Si la visita a una URL genera un redireccionamiento (como HTTP 301), es apropiado que la URL redireccionada se verifique con la Navegación segura de Google. La manipulación de la URL del cliente, como History.pushState
, no genera que se verifiquen las URLs nuevas respecto de la Navegación segura de Google.
Advertencias para los usuarios
Si usas la Navegación segura de Google para advertir a los usuarios sobre los riesgos de determinadas páginas web, se aplican los siguientes lineamientos.
Estos lineamientos ayudan a protegerte a ti y a Google de malentendidos, ya que aclaran que la página no se conoce con 100% de certeza de que sea un recurso web no seguro y que las advertencias solo identifican un posible riesgo.
- En la advertencia visible para los usuarios, no debes hacer creer a los usuarios que la página en cuestión es, sin duda, un recurso web no seguro. Cuando te refieras a la página que se identifica o los riesgos potenciales que podría suponer para los usuarios, debes calificar la advertencia con términos como "supuesta, potencialmente, posible, probable, posible".
- Tu advertencia debe permitir que el usuario obtenga más información al revisar la definición de varias amenazas que establece Google. Se sugieren los siguientes vínculos:
- Ingeniería social: https://developers.google.com/search/docs/monitor-debug/security/social-engineering
- Software malicioso y no deseado: https://developers.google.com/search/docs/monitor-debug/security/malware
- Aplicaciones potencialmente dañinas (solo para Android): https://developers.google.com/android/play-protect/potentially-harmful-applications
- Cuando muestra advertencias para páginas que el servicio de Navegación segura identifica como riesgosas, debe atribuirle la atribución a Google. Para ello, debe incluir la línea "Aviso proporcionado por Google" con un vínculo al Aviso de Navegación segura. Si tu producto también muestra advertencias basadas en otras fuentes, no debes incluir la atribución de Google en las advertencias derivadas de datos de terceros.
En la documentación del producto, debes proporcionar un aviso para informar a los usuarios que la protección que ofrece la Navegación segura de Google no es perfecta. Además, se le debe informar que existe la posibilidad de que se muestren falsos positivos (sitios seguros marcados como riesgosos) y falsos negativos (sitios peligrosos que no se marcaron). Te sugerimos que utilices el siguiente lenguaje:
Google trabaja para proporcionar la información más precisa y actualizada sobre los recursos web no seguros. Sin embargo, Google no puede garantizar que su información sea exhaustiva y no contenga errores. Es posible que algunos sitios peligrosos no se identifiquen y algunos sitios seguros se identifiquen por error.
Modos de operación
La Navegación segura de Google v5 permite a los clientes elegir entre tres modos de funcionamiento.
Modo en tiempo real
Cuando los clientes eligen usar Google Safe Browsing v5 en tiempo real, mantendrán en su base de datos local: (i) una caché global de sitios probables benignos, con el formato de hash SHA256 de expresiones de URL de sufijo host o prefijo de ruta, (ii) un conjunto de listas de amenazas, con el formato de prefijos de hash SHA256 de expresiones URL de sufijo de host/prefijo de ruta. La idea general es que, cada vez que el cliente quiera verificar una URL en particular, se realizará una verificación local con la caché global. Si se aprueba esa verificación, se lleva a cabo una revisión de las listas de amenazas locales. De lo contrario, el cliente continúa con la verificación de hash en tiempo real, como se detalla a continuación.
Además de la base de datos local, el cliente mantendrá una caché local. Este tipo de caché local no necesita estar en el almacenamiento persistente y, en caso de presión de memoria, puede borrarse.
A continuación, se incluye una especificación detallada del procedimiento.
Modo de lista local
Cuando los clientes eligen usar la Navegación segura de Google v5 en este modo, el comportamiento del cliente es similar al de la API de actualización v4, excepto cuando usan la plataforma mejorada de la API de la versión 5. Los clientes mantendrán en su base de datos local un conjunto de listas de amenazas con formato de prefijos hash SHA256 de expresiones URL de sufijo host o prefijo de ruta de acceso. Cada vez que el cliente desea verificar una URL en particular, se realiza una verificación utilizando la lista de amenazas locales. Solo si hay una coincidencia, el cliente se conecta al servidor para continuar con la verificación.
Al igual que con el caso anterior, el cliente también mantendrá una caché local que no necesita estar en el almacenamiento persistente.
Modo en tiempo real sin almacenamiento
Cuando los clientes eligen usar la Navegación segura de Google v5 en el modo en tiempo real sin almacenamiento, no necesitan mantener ninguna base de datos local. Cada vez que el cliente desee verificar una URL en particular, se conectará al servidor para hacerlo. Este modo es similar a lo que pueden implementar los clientes de la API de Lookup v4.
Verifica las URL
Esta sección contiene especificaciones detalladas sobre cómo los clientes verifican las URLs.
Canonicalización de URLs
Antes de verificar las URLs, se espera que el cliente realice una canonicalización en ella.
Para comenzar, suponemos que el cliente analizó la URL y la hizo válida de acuerdo con RFC 2396. Si la URL utiliza un nombre de dominio internacionalizado (IDN), el cliente debe convertir la URL a la representación ASCII en Punycode. La URL debe incluir un componente de ruta de acceso, es decir, debe tener al menos una barra diagonal después del dominio (http://google.com/
en lugar de http://google.com
).
Primero, elimina los caracteres tabulador (0x09), CR (0x0d) y LF (0x0a) de la URL. No quites las secuencias de escape para estos caracteres (p.ej., %0a
).
En segundo lugar, si la URL termina en un fragmento, quítalo. Por ejemplo, reduce http://google.com/#frag
a http://google.com/
.
Tercero, de forma reiterada, anula el escape porcentual de la URL hasta que no haya más escapes porcentuales. (Esto puede hacer que la URL no sea válida).
Para canonicalizar el nombre de host, sigue estos pasos:
Extrae el nombre de host de la URL y luego haz lo siguiente:
- Quita todos los puntos iniciales y finales.
- Reemplaza los puntos consecutivos por un solo punto.
- Si el nombre de host se puede analizar como una dirección IPv4, normalízalo a 4 valores decimales separados por puntos. El cliente debe manejar cualquier codificación de dirección IP legal, incluidas la octal, la hexadecimal y menos de cuatro componentes.
- Si el nombre de host se puede analizar como una dirección IPv6 entre corchetes, normalízalo quitando los ceros iniciales innecesarios en los componentes y contrayendo cero componentes mediante la sintaxis de dos puntos. Por ejemplo,
[2001:0db8:0000::1]
se debe transformar en[2001:db8::1]
. Si el nombre de host es uno de los siguientes dos tipos de dirección IPv6 especiales, transfórmalos a IPv4:- Una dirección IPv6 asignada a IPv4, como
[::ffff:1.2.3.4]
, que se debe transformar en1.2.3.4
. - Una dirección NAT64 con el prefijo conocido 64:ff9b::/96, como
[64:ff9b::1.2.3.4]
, que se debe transformar en1.2.3.4
.
- Una dirección IPv6 asignada a IPv4, como
- Pon en minúscula toda la string.
Sigue estos pasos para canonicalizar la ruta:
- Resuelve las secuencias
/../
y/./
en la ruta de acceso reemplazando/./
por/
y quitando/../
junto con el componente de la ruta de acceso anterior. - Reemplaza las ejecuciones de barras consecutivas por un solo carácter de barra.
No apliques estas canonicalizaciones de ruta a los parámetros de búsqueda.
En la URL, se escape de porcentaje a todos los caracteres que sean <= ASCII 32, >= 127, #
o %
. Se deben usar caracteres hexadecimales en mayúsculas en los escapes.
Expresiones de prefijo de ruta de acceso del sufijo de host
Una vez que la URL esté canonicalizada, el siguiente paso es crear las expresiones de sufijo o prefijo. Cada expresión de sufijo o prefijo consta de un sufijo de host (o host completo) y un prefijo de ruta de acceso (o ruta de acceso completa).
El cliente formará hasta 30 combinaciones posibles de sufijo de host y prefijo de ruta de acceso diferentes. Estas combinaciones solo usan los componentes de host y de ruta de acceso de la URL. Se descartan el esquema, el nombre de usuario, la contraseña y el puerto. Si la URL incluye parámetros de consulta, al menos una combinación incluirá la ruta completa y los parámetros de búsqueda.
Para el host, el cliente intentará como máximo con cinco strings diferentes. Estos son los siguientes:
- Si el nombre de host no es un literal IPv4 o IPv6, se forman hasta cuatro nombres de host comenzando con el dominio eTLD+1 y agregando componentes iniciales sucesivos. La determinación de eTLD+1 debe basarse en la Lista de sufijos públicos. Por ejemplo,
a.b.example.com
generaría el dominio eTLD+1 deexample.com
, así como el host con un componente de host adicionalb.example.com
. - El nombre de host exacto que aparece en la URL Siguiendo el ejemplo anterior, se verificaría
a.b.example.com
.
Para la ruta, el cliente intentará como máximo con seis strings diferentes. Son:
- La ruta exacta de la URL, incluidos los parámetros de búsqueda.
- La ruta exacta de la URL, sin parámetros de búsqueda.
- Las cuatro rutas de acceso formadas al comenzar en la raíz (/) y luego anexar componentes de ruta de acceso, incluida una barra final.
En los siguientes ejemplos, se ilustra el comportamiento de verificación:
Para la URL http://a.b.com/1/2.html?param=1
, el cliente probará estas posibles strings:
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 la URL http://a.b.c.d.e.f.com/1.html
, el cliente probará estas posibles strings:
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/
(Nota: Omite b.c.d.e.f.com
, ya que solo tomaremos los últimos cinco componentes del nombre de host y el nombre de host completo).
Para la URL http://1.2.3.4/1/
, el cliente probará estas posibles strings:
1.2.3.4/1/
1.2.3.4/
Para la URL http://example.co.uk/1
, el cliente probará estas posibles strings:
example.co.uk/1
example.co.uk/
Hashing
La Navegación segura de Google usa exclusivamente SHA256 como función hash. Esta función hash debe aplicarse a las expresiones anteriores.
Según las circunstancias, el hash completo de 32 bytes se truncará a 4 bytes, 8 bytes o 16 bytes:
Cuando se usa el método hashes.search, actualmente requerimos que los hashes de la solicitud se trunquen a exactamente 4 bytes. El envío de bytes adicionales en esta solicitud comprometerá la privacidad del usuario.
Cuando descargas las listas de la base de datos local con el método hashList.get o hashLists.batchGet, la longitud de los hashes que envía el servidor se ve afectada por la naturaleza de la lista y por la preferencia del cliente por la longitud del hash, comunicada por el parámetro
desired_hash_length
.
Procedimiento de verificación de URL en tiempo real
Este procedimiento se utiliza cuando el cliente elige el modo de operación en tiempo real.
Este procedimiento toma una sola URL u
y muestra SAFE
, UNSAFE
o UNSURE
. Si muestra SAFE
, la Navegación segura de Google considera la URL. Si muestra UNSAFE
, la Navegación segura de Google considerará que la URL es potencialmente insegura, y se deben tomar las medidas adecuadas, como mostrar una advertencia al usuario final, mover un mensaje recibido a la carpeta de spam o solicitar una confirmación adicional del usuario antes de continuar. Si muestra UNSURE
, se debe usar el siguiente procedimiento de verificación local después.
- Deja que
expressions
sea una lista de expresiones de sufijo o prefijo generadas por la URLu
. - Permite que
expressionHashes
sea una lista, en la que los elementos sean hash SHA256 de cada expresión enexpressions
. - Para cada
hash
deexpressionHashes
:- Si se puede encontrar
hash
en la caché global, muestraUNSURE
.
- Si se puede encontrar
- Deja que
expressionHashPrefixes
sea una lista, en la que los elementos sean los primeros 4 bytes de cada hash enexpressionHashes
. - Para cada
expressionHashPrefix
deexpressionHashPrefixes
:- Busca
expressionHashPrefix
en la caché local. - Si se encuentra la entrada almacenada en caché, haz lo siguiente:
- Determina si la hora actual es mayor que su tiempo de vencimiento.
- Si es mayor:
- Quita de la caché local la entrada almacenada en caché que se encontró.
- Continúa con el bucle.
- Si no es mayor, haz lo siguiente:
- Quita esta
expressionHashPrefix
en particular deexpressionHashPrefixes
. - Verifica si el hash completo correspondiente dentro de
expressionHashes
se encuentra en la entrada almacenada en caché. - Si lo encuentras, muestra
UNSAFE
. - Si no lo encuentras, continúa con el bucle.
- Quita esta
- Si no se encuentra la entrada almacenada en caché, continúa con el bucle.
- Busca
- Envía
expressionHashPrefixes
al servidor de Navegación segura de Google v5 con RPC SearchHashes o el método REST hashes.search. Si se produjo un error (incluidos errores de red, de HTTP, etc.), muestraUNSURE
. De lo contrario, deja que la respuesta sea elresponse
recibido del servidor SB, que es una lista de hashes completos junto con información auxiliar que identifica la naturaleza de la amenaza (ingeniería social, software malicioso, etc.), así como el tiempo de vencimiento de la cachéexpiration
. - Para cada
fullHash
deresponse
:- Inserta
fullHash
en la caché local, junto conexpiration
.
- Inserta
- Para cada
fullHash
deresponse
:- Deja que
isFound
sea el resultado de encontrarfullHash
enexpressionHashes
. - Si
isFound
es falsa, continúa con el bucle. - Si el valor de
isFound
es True, muestraUNSAFE
.
- Deja que
- Muestra
SAFE
.
Procedimiento de verificación de la URL de la lista de amenazas locales
Este procedimiento se utiliza cuando el cliente opta por el modo de operación de lista local. También se usa cuando el cliente, el procedimiento de RealTimeCheck anterior muestra el valor de UNSURE
.
Este procedimiento toma una sola URL u
y muestra SAFE
o UNSAFE
.
- Deja que
expressions
sea una lista de expresiones de sufijo o prefijo generadas por la URLu
. - Permite que
expressionHashes
sea una lista, en la que los elementos sean hash SHA256 de cada expresión enexpressions
. - Deja que
expressionHashPrefixes
sea una lista, en la que los elementos sean los primeros 4 bytes de cada hash enexpressionHashes
. - Para cada
expressionHashPrefix
deexpressionHashPrefixes
:- Busca
expressionHashPrefix
en la caché local. - Si se encuentra la entrada almacenada en caché, haz lo siguiente:
- Determina si la hora actual es mayor que su tiempo de vencimiento.
- Si es mayor:
- Quita de la caché local la entrada almacenada en caché que se encontró.
- Continúa con el bucle.
- Si no es mayor, haz lo siguiente:
- Quita esta
expressionHashPrefix
en particular deexpressionHashPrefixes
. - Verifica si el hash completo correspondiente dentro de
expressionHashes
se encuentra en la entrada almacenada en caché. - Si lo encuentras, muestra
UNSAFE
. - Si no lo encuentras, continúa con el bucle.
- Quita esta
- Si no se encuentra la entrada almacenada en caché, continúa con el bucle.
- Busca
- Para cada
expressionHashPrefix
deexpressionHashPrefixes
:- Busca
expressionHashPrefix
en la base de datos de la lista de amenazas local. - Si no se puede encontrar
expressionHashPrefix
en la base de datos de la lista de amenazas local, quítalo deexpressionHashPrefixes
.
- Busca
- Envía
expressionHashPrefixes
al servidor de Navegación segura de Google v5 con RPC SearchHashes o el método REST hashes.search. Si se produjo un error (incluidos errores de red, de HTTP, etc.), muestraSAFE
. De lo contrario, deja que la respuesta sea elresponse
recibido del servidor SB, que es una lista de hashes completos junto con información auxiliar que identifica la naturaleza de la amenaza (ingeniería social, software malicioso, etc.), así como el tiempo de vencimiento de la cachéexpiration
. - Para cada
fullHash
deresponse
:- Inserta
fullHash
en la caché local, junto conexpiration
.
- Inserta
- Para cada
fullHash
deresponse
:- Deja que
isFound
sea el resultado de encontrarfullHash
enexpressionHashes
. - Si
isFound
es falsa, continúa con el bucle. - Si el valor de
isFound
es True, muestraUNSAFE
.
- Deja que
- Muestra
SAFE
.
Procedimiento de verificación de URL en tiempo real sin una base de datos local
Este procedimiento se utiliza cuando el cliente elige el modo de operación en tiempo real sin almacenamiento.
Este procedimiento toma una sola URL u
y muestra SAFE
o UNSAFE
.
- Deja que
expressions
sea una lista de expresiones de sufijo o prefijo generadas por la URLu
. - Permite que
expressionHashes
sea una lista, en la que los elementos sean hash SHA256 de cada expresión enexpressions
. - Deja que
expressionHashPrefixes
sea una lista, en la que los elementos sean los primeros 4 bytes de cada hash enexpressionHashes
. - Para cada
expressionHashPrefix
deexpressionHashPrefixes
:- Busca
expressionHashPrefix
en la caché local. - Si se encuentra la entrada almacenada en caché, haz lo siguiente:
- Determina si la hora actual es mayor que su tiempo de vencimiento.
- Si es mayor:
- Quita de la caché local la entrada almacenada en caché que se encontró.
- Continúa con el bucle.
- Si no es mayor, haz lo siguiente:
- Quita esta
expressionHashPrefix
en particular deexpressionHashPrefixes
. - Verifica si el hash completo correspondiente dentro de
expressionHashes
se encuentra en la entrada almacenada en caché. - Si lo encuentras, muestra
UNSAFE
. - Si no lo encuentras, continúa con el bucle.
- Quita esta
- Si no se encuentra la entrada almacenada en caché, continúa con el bucle.
- Busca
- Envía
expressionHashPrefixes
al servidor de Navegación segura de Google v5 con RPC SearchHashes o el método REST hashes.search. Si se produjo un error (incluidos errores de red, de HTTP, etc.), muestraSAFE
. De lo contrario, deja que la respuesta sea elresponse
recibido del servidor SB, que es una lista de hashes completos junto con información auxiliar que identifica la naturaleza de la amenaza (ingeniería social, software malicioso, etc.), así como el tiempo de vencimiento de la cachéexpiration
. - Para cada
fullHash
deresponse
:- Inserta
fullHash
en la caché local, junto conexpiration
.
- Inserta
- Para cada
fullHash
deresponse
:- Deja que
isFound
sea el resultado de encontrarfullHash
enexpressionHashes
. - Si
isFound
es falsa, continúa con el bucle. - Si el valor de
isFound
es True, muestraUNSAFE
.
- Deja que
- Muestra
SAFE
.
Mantenimiento de bases de datos locales
La Navegación segura de Google v5 espera que el cliente mantenga una base de datos local, excepto cuando elige el modo en tiempo real sin almacenamiento. El formato y el almacenamiento de esta base de datos local dependen del cliente. El contenido de esta base de datos local puede considerarse como una carpeta que contiene varias listas como archivos, y su contenido es hash SHA256 o prefijos de hash.
Actualizaciones de bases de datos
El cliente llamará con regularidad al método hashList.get o hashLists.batchGet para actualizar la base de datos. Dado que los clientes típicos querrán actualizar varias listas a la vez, se recomienda usar el método hashLists.batchGet.
Las listas se identifican con sus nombres distintos. Los nombres son cadenas ASCII cortas de pocos caracteres.
A diferencia de la versión 4, en la que las listas se identifican por la tupla de tipo de amenaza, tipo de plataforma y tipo de entrada de amenaza, en la versión 5 las listas simplemente se identifican por nombre. Esto proporciona flexibilidad cuando varias listas v5 podrían compartir el mismo tipo de amenaza. Los tipos de plataformas y los tipos de entradas de amenazas se quitan en la versión 5.
Una vez que se elige un nombre para una lista, no se le cambiará el nombre. Además, una vez que haya aparecido una lista, no se quitará nunca (si la lista ya no es útil, quedará vacía, pero seguirá existiendo). Por lo tanto, es apropiado codificar estos nombres en el código de cliente de Navegación segura de Google.
Tanto el método hashList.get como el método hashLists.batchGet admiten actualizaciones incrementales. El uso de actualizaciones incrementales ahorra ancho de banda y mejora el rendimiento. Las actualizaciones incrementales proporcionan un delta entre la versión de la lista del cliente y la versión más reciente. (Si un cliente se implementó recientemente y no tiene ninguna versión disponible, hay una actualización completa disponible). La actualización incremental contiene índices y adiciones de eliminación. Primero, se espera que el cliente quite las entradas de los índices especificados de su base de datos local y, luego, aplique las adiciones.
Por último, para evitar daños, el cliente debe comparar los datos almacenados con la suma de comprobación que proporciona el servidor. Cuando la suma de verificación no coincide, el cliente debe realizar una actualización completa.
Cómo decodificar el contenido de la lista
Todas las listas se envían con una codificación especial para reducir el tamaño. Esta codificación funciona reconociendo que las listas de la Navegación segura de Google contienen, de forma conceptual, un conjunto de hashes o prefijos de hash, que estadísticamente no pueden distinguirse de los números enteros aleatorios. Si ordenamos estos números enteros y tomemos la diferencia adyacente, se espera que esa diferencia adyacente sea "pequeña" en cierto sentido. Luego, la codificación Golomb-Rice explota esta pequeñez.
La Navegación segura de Google v5 tiene cuatro tipos distintos para administrar datos de 4 bytes, datos de 8 bytes, datos de 16 bytes y datos de 32 bytes. Veamos un ejemplo en el que se codifican tres números enteros consecutivos de 4 bytes. Deja que el parámetro Rice, indicado con k, sea 3. La parte del cociente de la codificación es simplemente el valor de diferencia adyacente desplazado hacia la derecha por k bits. Dado que los números enteros dados son consecutivos, la diferencia adyacente es 1 y, después de desplazarse 3 bits, la parte del cociente es cero. Los k bits menos significativos son 001. El cociente cero se codifica como un solo 0 bits. El resto es 1 y está codificado como 100. Esto se repite de nuevo para formar el flujo de bits 01000100. El flujo de bits resultante se codifica mediante el método Little endian como 00100010. Por lo tanto, corresponde a los siguientes datos:
rice_parameter: 3
entries_count: 2
encoded_data: "\x22"
Después del paso de decodificación anterior para números enteros de 32 bits, el resultado se puede usar directamente como índices o adiciones de eliminación. A diferencia de la v4, no es necesario realizar un intercambio de bytes después.
Listas disponibles
Se recomienda usar las siguientes listas en v5alpha1:
Nombre de la lista | Enum ThreatType v4 correspondiente |
Descripción |
---|---|---|
gc |
Ninguno | Esta es una lista de la caché global. Es una lista especial que solo se usa en el modo de operación En tiempo real. |
se |
SOCIAL_ENGINEERING |
Esta lista contiene amenazas del tipo SOCIAL_ENGINEERING. |
mw |
MALWARE |
Esta lista contiene amenazas del tipo MALWARE para plataformas de escritorio. |
uws |
UNWANTED_SOFTWARE |
Esta lista contiene amenazas del tipo UNWANTED_SOFTWARE para plataformas de escritorio. |
uwsa |
UNWANTED_SOFTWARE |
Esta lista contiene amenazas del tipo de amenaza UNWANTED_SOFTWARE para las plataformas de Android. |
pha |
POTENTIALLY_HARMFUL_APPLICATION |
Esta lista contiene amenazas del tipo POTENTIALLY_HARMFUL_APPLICATION para plataformas de Android. |
Más adelante, habrá listas adicionales disponibles. A partir de ese momento, la tabla anterior se expandirá.
Frecuencia de actualización
El cliente debe inspeccionar el valor que se muestra del servidor en el campo minimum_wait_duration
y usarlo para programar la próxima actualización de la base de datos. Es posible que este valor sea cero, en cuyo caso el cliente debería realizar otra actualización inmediatamente.
Ejemplos de solicitudes
En esta sección, se documentan algunos ejemplos del uso directo de la API de HTTP para acceder a la Navegación segura de Google. Generalmente, se recomienda usar una vinculación de lenguaje generada porque manejará automáticamente la codificación y decodificación de una manera conveniente. Consulta la documentación de esa vinculación.
A continuación, se muestra un ejemplo de solicitud HTTP que usa el método hashes.search:
GET https://safebrowsing.googleapis.com/v5/hashes:search?key=INSERT_YOUR_API_KEY_HERE&hashPrefixes=WwuJdQ
El cuerpo de la respuesta es una carga útil con formato de búfer de protocolo que luego puedes decodificar.
A continuación, se muestra una solicitud HTTP de ejemplo que usa el método hashLists.batchGet:
GET https://safebrowsing.googleapis.com/v5alpha1/hashLists:batchGet?key=INSERT_YOUR_API_KEY_HERE&names=se&names=mw
El cuerpo de la respuesta es, una vez más, una carga útil con formato de búfer de protocolo que luego puedes decodificar.
Guía de migración
Si actualmente usas la API de actualización v4, existe una ruta de migración sin inconvenientes de la versión 4 a la versión 5 sin tener que restablecer ni borrar la base de datos local. En esta sección, se documenta cómo hacerlo.
Cómo convertir actualizaciones de listas
En la versión 4, se usa el métodothreatListUpdates.fetch para descargar listas. En la versión 5, cambiarías al método hashLists.batchGet.
Se deben hacer los siguientes cambios en la solicitud:
- Quita por completo el objeto
ClientInfo
v4. En lugar de proporcionar la identificación de un cliente mediante un campo dedicado, usa el conocido encabezado User-Agent. Aunque no existe un formato prescrito para proporcionar la identificación del cliente en este encabezado, te sugerimos que simplemente incluyas el ID de cliente original y la versión del cliente separados por un carácter de espacio o una barra diagonal. - Para cada objeto
ListUpdateRequest
de la versión 4:- Busca el nombre de la lista de la versión 5 correspondiente en la tabla de arriba y proporciona ese nombre en la solicitud de la versión 5.
- Quita los campos innecesarios, como
threat_entry_type
oplatform_type
. - El campo
state
de la versión 4 es directamente compatible con el campoversions
de la versión 5. La misma cadena de bytes que se enviaría al servidor mediante el campostate
en la versión 4 se puede enviar en la versión 5 con el campoversions
. - Para las restricciones de la versión 4, la versión 5 usa una versión simplificada llamada
SizeConstraints
. Se deben descartar los campos adicionales, comoregion
.
Se deben realizar los siguientes cambios en la respuesta:
- La enum.
ResponseType
v4 solo se reemplaza por un campo booleano llamadopartial_update
. - El campo
minimum_wait_duration
ahora puede omitirse o ser cero. Si es así, se le solicita al cliente que realice otra solicitud de inmediato. Esto solo sucede cuando el cliente especifica enSizeConstraints
una restricción más pequeña en el tamaño máximo de actualización que el tamaño máximo de la base de datos. - Es necesario ajustar el algoritmo de decodificación de Rice para números enteros de 32 bits. La diferencia es que los datos codificados están codificados con un formato endian diferente. En la v4 y la v5, los prefijos hash de 32 bits se ordenan de manera lexicográfica. Sin embargo, en la v4, esos prefijos se tratan como Little endian cuando se ordenan, mientras que en la v5, esos prefijos se tratan como big endian cuando se ordenan. Esto significa que el cliente no necesita hacer ninguna ordenación, ya que la ordenación lexicográfica es idéntica a la ordenación numérica con big endian. Puedes encontrar un ejemplo de este tipo en la implementación de la versión 4 de Chromium aquí. Este tipo de ordenación se puede quitar.
- El algoritmo de decodificación de Rice deberá implementarse para otras longitudes de hash.
Convierte búsquedas de hash
En la versión 4, se usa el método fullHashes.find para obtener hashes completos. El método equivalente en la versión 5 es el método hashes.search.
Se deben hacer los siguientes cambios en la solicitud:
- Estructura el código para enviar solo prefijos de hash que tengan exactamente 4 bytes de longitud.
- Quita por completo los objetos
ClientInfo
v4. En lugar de proporcionar la identificación de un cliente mediante un campo dedicado, usa el conocido encabezado User-Agent. Aunque no existe un formato prescrito para proporcionar la identificación del cliente en este encabezado, te sugerimos que simplemente incluyas el ID de cliente original y la versión del cliente separados por un carácter de espacio o una barra diagonal. - Quita el campo
client_states
. Ya no es necesario. - Ya no es necesario incluir
threat_types
ni campos similares.
Se deben realizar los siguientes cambios en la respuesta:
- Se quitó el campo
minimum_wait_duration
. El cliente siempre puede emitir una solicitud nueva según sea necesario. - El objeto
ThreatMatch
v4 se simplificó en el objetoFullHash
. - El almacenamiento en caché se simplificó a una sola duración de caché. Consulta los procedimientos anteriores para interactuar con la caché.