Overview

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:

1. Quita todos los puntos iniciales y finales.
2. Reemplaza los puntos consecutivos por un solo punto.
3. 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.
4. 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 en 1.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 en 1.2.3.4.
5. Pon en minúscula toda la string.

Sigue estos pasos para canonicalizar la ruta:

1. Resuelve las secuencias /../ y /./ en la ruta de acceso reemplazando /./ por / y quitando /../ junto con el componente de la ruta de acceso anterior.
2. 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 de example.com, así como el host con un componente de host adicional b.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.

1. Deja que expressions sea una lista de expresiones de sufijo o prefijo generadas por la URL u.
2. Permite que expressionHashes sea una lista, en la que los elementos sean hash SHA256 de cada expresión en expressions.
3. Para cada hash de expressionHashes:
   1. Si se puede encontrar hash en la caché global, muestra UNSURE.
4. Deja que expressionHashPrefixes sea una lista, en la que los elementos sean los primeros 4 bytes de cada hash en expressionHashes.
5. Para cada expressionHashPrefix de expressionHashPrefixes:
   1. Busca expressionHashPrefix en la caché local.
   2. Si se encuentra la entrada almacenada en caché, haz lo siguiente:
      1. Determina si la hora actual es mayor que su tiempo de vencimiento.
      2. Si es mayor:
         1. Quita de la caché local la entrada almacenada en caché que se encontró.
         2. Continúa con el bucle.
      3. Si no es mayor, haz lo siguiente:
         1. Quita esta expressionHashPrefix en particular de expressionHashPrefixes.
         2. Verifica si el hash completo correspondiente dentro de expressionHashes se encuentra en la entrada almacenada en caché.
         3. Si lo encuentras, muestra UNSAFE.
         4. Si no lo encuentras, continúa con el bucle.
   3. Si no se encuentra la entrada almacenada en caché, continúa con el bucle.
6. 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.), muestra UNSURE. De lo contrario, deja que la respuesta sea el response 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.
7. Para cada fullHash de response:
   1. Inserta fullHash en la caché local, junto con expiration.
8. Para cada fullHash de response:
   1. Deja que isFound sea el resultado de encontrar fullHash en expressionHashes.
   2. Si isFound es falsa, continúa con el bucle.
   3. Si el valor de isFound es True, muestra UNSAFE.
9. 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.

1. Deja que expressions sea una lista de expresiones de sufijo o prefijo generadas por la URL u.
2. Permite que expressionHashes sea una lista, en la que los elementos sean hash SHA256 de cada expresión en expressions.
3. Deja que expressionHashPrefixes sea una lista, en la que los elementos sean los primeros 4 bytes de cada hash en expressionHashes.
4. Para cada expressionHashPrefix de expressionHashPrefixes:
   1. Busca expressionHashPrefix en la caché local.
   2. Si se encuentra la entrada almacenada en caché, haz lo siguiente:
      1. Determina si la hora actual es mayor que su tiempo de vencimiento.
      2. Si es mayor:
         1. Quita de la caché local la entrada almacenada en caché que se encontró.
         2. Continúa con el bucle.
      3. Si no es mayor, haz lo siguiente:
         1. Quita esta expressionHashPrefix en particular de expressionHashPrefixes.
         2. Verifica si el hash completo correspondiente dentro de expressionHashes se encuentra en la entrada almacenada en caché.
         3. Si lo encuentras, muestra UNSAFE.
         4. Si no lo encuentras, continúa con el bucle.
   3. Si no se encuentra la entrada almacenada en caché, continúa con el bucle.
5. Para cada expressionHashPrefix de expressionHashPrefixes:
   1. Busca expressionHashPrefix en la base de datos de la lista de amenazas local.
   2. Si no se puede encontrar expressionHashPrefix en la base de datos de la lista de amenazas local, quítalo de expressionHashPrefixes.
6. 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.), muestra SAFE. De lo contrario, deja que la respuesta sea el response 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.
7. Para cada fullHash de response:
   1. Inserta fullHash en la caché local, junto con expiration.
8. Para cada fullHash de response:
   1. Deja que isFound sea el resultado de encontrar fullHash en expressionHashes.
   2. Si isFound es falsa, continúa con el bucle.
   3. Si el valor de isFound es True, muestra UNSAFE.
9. 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.

1. Deja que expressions sea una lista de expresiones de sufijo o prefijo generadas por la URL u.
2. Permite que expressionHashes sea una lista, en la que los elementos sean hash SHA256 de cada expresión en expressions.
3. Deja que expressionHashPrefixes sea una lista, en la que los elementos sean los primeros 4 bytes de cada hash en expressionHashes.
4. Para cada expressionHashPrefix de expressionHashPrefixes:
   1. Busca expressionHashPrefix en la caché local.
   2. Si se encuentra la entrada almacenada en caché, haz lo siguiente:
      1. Determina si la hora actual es mayor que su tiempo de vencimiento.
      2. Si es mayor:
         1. Quita de la caché local la entrada almacenada en caché que se encontró.
         2. Continúa con el bucle.
      3. Si no es mayor, haz lo siguiente:
         1. Quita esta expressionHashPrefix en particular de expressionHashPrefixes.
         2. Verifica si el hash completo correspondiente dentro de expressionHashes se encuentra en la entrada almacenada en caché.
         3. Si lo encuentras, muestra UNSAFE.
         4. Si no lo encuentras, continúa con el bucle.
   3. Si no se encuentra la entrada almacenada en caché, continúa con el bucle.
5. 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.), muestra SAFE. De lo contrario, deja que la respuesta sea el response 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.
6. Para cada fullHash de response:
   1. Inserta fullHash en la caché local, junto con expiration.
7. Para cada fullHash de response:
   1. Deja que isFound sea el resultado de encontrar fullHash en expressionHashes.
   2. Si isFound es falsa, continúa con el bucle.
   3. Si el valor de isFound es True, muestra UNSAFE.
8. 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:

1. 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.
2. 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 o platform_type.
   • El campo state de la versión 4 es directamente compatible con el campo versions de la versión 5. La misma cadena de bytes que se enviaría al servidor mediante el campo state en la versión 4 se puede enviar en la versión 5 con el campo versions.
   • 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, como region.

Se deben realizar los siguientes cambios en la respuesta:

1. La enum. ResponseType v4 solo se reemplaza por un campo booleano llamado partial_update.
2. 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 en SizeConstraints 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.
3. 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.
4. 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:

1. Estructura el código para enviar solo prefijos de hash que tengan exactamente 4 bytes de longitud.
2. 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.
3. Quita el campo client_states. Ya no es necesario.
4. Ya no es necesario incluir threat_types ni campos similares.

Se deben realizar los siguientes cambios en la respuesta:

1. Se quitó el campo minimum_wait_duration. El cliente siempre puede emitir una solicitud nueva según sea necesario.
2. El objeto ThreatMatch v4 se simplificó en el objeto FullHash.
3. El almacenamiento en caché se simplificó a una sola duración de caché. Consulta los procedimientos anteriores para interactuar con la caché.