Overview

Introducción

Nota: Esta documentación aún está en desarrollo. Se esperan mejoras próximamente.

La Navegación segura de Google v5 es una evolución de la Navegación segura de Google v4. Los dos cambios clave de la versión 5 son la actualidad de los datos y la privacidad de la IP. Además, se mejoró la superficie de la API para aumentar la flexibilidad y 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 las versiones 4 y 5, y ambas se consideran listas para la producción. Puedes usar la v4 o v5. No anunciamos una fecha para la baja de la versión 4. Si lo hacemos, enviaremos un aviso mínimo de un año. En esta página, se describirá la v5, así como una guía de migración de la v4 a la v5. La documentación completa de la v4 permanece disponible.

Actualidad de los datos

Una mejora significativa de la versión 5 de la Navegación segura de Google en comparación con la versión 4 (específicamente, la versión 4 de la API de Update) es la actualidad y la cobertura de los datos. Dado que la protección depende en gran medida de la base de datos local mantenida por el cliente, el retraso y el tamaño de la actualización de la base de datos local es lo que más contribuye a la pérdida de protección. En la v4, el 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 phishing se expanden rápido: hasta 2021, el 60% de los sitios que realizan ataques vivían menos de 10 minutos. Nuestro análisis muestra que alrededor del 25 al 30% de la falta de protección contra los ataques de 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 sigue creciendo con el tiempo.

En la v5, presentamos un modo de operación conocido como protección en tiempo real. Esto evita el problema de obsolescencia de los datos anterior. En la v4, 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 parcial de prefijo, realicen 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 probablemente benignos (llamados Caché global), realicen una verificación local para esta caché global y una verificación de lista de amenazas locales y, por último, cuando haya una coincidencia de prefijo parcial para las listas de amenazas o una sin 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 la opción de permitir la configuración predeterminada a la de verificación predeterminada, lo que puede mejorar la protección ante la 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 (v4 o v5) no procesa nada asociado con la identidad de un usuario durante la entrega de solicitudes. Las cookies, si se envían, se ignoran. Google conoce las direcciones IP de origen de las solicitudes, pero Google solo las utiliza para las necesidades esenciales de red (es decir, para enviar respuestas) y con fines anti-DoS.

De forma simultánea a la v5, presentamos una API complementaria conocida como la API de Oblivious HTTP Gateway para la Navegación segura. Esta opción usa HTTP exclusiva para ocultarle a Google las direcciones IP de los usuarios finales. Funciona cuando un tercero sin colisión controla una versión encriptada de la solicitud del usuario y, luego, la reenvía 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 un Relay HTTP Oblivious (como este servicio de Fastly) y Google opera la Oblivious HTTP Gateway. Esta es una API complementaria opcional. Cuando se utiliza junto con la Navegación segura de Google, ya no se envían las direcciones IP de los usuarios finales a Google.

Uso adecuado

Uso permitido

La API de Safe Browsing es solo para uso no comercial (es decir, “no para la venta ni para 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 se habilita la API de Safe Browsing. Puedes consultar la asignación y el uso actuales en Google Developers Console. Si esperas usar más que la cuota asignada actualmente, puedes solicitar una cuota adicional desde la interfaz de cuotas de Play Console. Revisamos estas solicitudes y solicitamos que nos comuniquemos con usted cuando solicitemos un aumento de cuota para asegurarnos de que nuestra disponibilidad del servicio satisfaga las necesidades de todos los usuarios.

URLs apropiadas

La Navegación segura de Google está diseñada para actuar en las URLs que se muestran en la barra de direcciones de un navegador. No está diseñado para usarse para verificar subrecursos (como JavaScript o una imagen a la que hace referencia un archivo HTML, o una URL de WebSocket iniciada por JavaScript). No se deben verificar las URLs de esos subrecursos con la Navegación segura de Google.

Si visitar una URL genera un redireccionamiento (como HTTP 301), es recomendable que verifiques la URL de redireccionamiento en la Navegación segura de Google. La manipulación de URLs del cliente, como History.pushState, no provoca que se verifiquen las URLs nuevas en la Navegación segura de Google.

Advertencias para los usuarios

Si utilizas 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 te protegen a ti y a Google contra malentendidos, ya que aclaran que la página no se conoce con una certeza del 100% de que es un recurso web no seguro, y que las advertencias solo identifican un posible riesgo.

• En la advertencia visible para el usuario, no debe hacer creer a los usuarios que la página en cuestión es, sin duda, un recurso web no seguro. Cuando mencionas la página que se identifica o los riesgos potenciales que podría representar para los usuarios, debes calificar la advertencia con términos como: posible, posible, probable y probable.
• Tu advertencia debe permitirle al usuario obtener más información revisando la definición de Google sobre diversas amenazas. Te sugerimos 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 muestres advertencias para páginas identificadas como riesgosas por el servicio de Navegación segura, debes incluir la línea "Asesoría proporcionada por Google" con un vínculo al Aviso de Navegación segura para atribuirla a Google. 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 que no sean de Google.

• En la documentación de tu producto, debes incluir un aviso para informar a los usuarios que la protección que ofrece la Navegación segura de Google no es perfecta. Debe informarles que existe la posibilidad de obtener 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 completa y esté libre de errores: es posible que no se identifiquen algunos sitios riesgosos y que otros sitios seguros se identifiquen por error.

Modos de operación

La versión 5 de la Navegación segura de Google permite a los clientes elegir entre tres modos de operación.

Modo En tiempo real

Cuando los clientes eligen usar la Navegación segura de Google v5 en modo en tiempo real, mantendrán en su base de datos local: (i) una caché global de sitios probablemente benignos, con el formato de hash SHA256 de expresiones de URL con prefijo de host/sufijo de ruta, (ii) un conjunto de listas de amenazas con el formato de prefijos de hash SHA256 de expresiones de URL de sufijo de host o prefijo de ruta de acceso. La idea de alto nivel es que cuando el cliente desea verificar una URL en particular, se realiza una verificación local con la caché global. Si esa verificación se aprueba, se realiza 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. No es necesario que este tipo de caché local esté en el almacenamiento persistente y se puede borrar en caso de presión de memoria.

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, su comportamiento es similar al de la API de Update v4, excepto que usan la plataforma de API mejorada de la v5. Los clientes mantendrán en su base de datos local un conjunto de listas de amenazas con formato de prefijos hash SHA256 de expresiones de URL de sufijo de host/prefijo de ruta de acceso. Cada vez que el cliente desee verificar una URL en particular, se realiza una comprobación mediante la lista de amenazas locales. Siempre y cuando haya una coincidencia, el cliente se conecta al servidor para continuar con la verificación.

Al igual que con el ejemplo anterior, el cliente también mantendrá una caché local que no necesita estar en un 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 persistente. Sin embargo, se espera que el cliente conserve una caché local. No es necesario que este tipo de caché local esté en el almacenamiento persistente y se puede borrar en caso de presión de memoria.

Cada vez que el cliente desea revisar una URL en particular, siempre se conecta al servidor para realizar una verificación. Este modo es similar a lo que los clientes de la API v4 Lookup pueden implementar.

En comparación con el modo en tiempo real, este modo puede usar más ancho de banda de red, pero puede ser más adecuado si no es conveniente para el cliente mantener un estado local persistente.

Verifica las URL

Esta sección contiene especificaciones detalladas acerca de cómo los clientes verifican las URL.

Canonicalización de las URL

Antes de que se verifiquen las URLs, se espera que el cliente realice una canonicalización en esa URL.

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 en la representación de Punycode ASCII. La URL debe incluir un componente de ruta de acceso; es decir, debe tener, al menos, una barra después del dominio (http://google.com/ en lugar de http://google.com).

Primero, quita los caracteres de tabulación (0x09), CR (0x0d) y LF (0x0a) de la URL. No quites secuencias de escape para esos caracteres (p.ej., %0a).

En segundo lugar, si la URL termina en un fragmento, quítalo. Por ejemplo, acorta http://google.com/#frag a http://google.com/.

Tercero, elimina el escape porcentual de manera repetida de la URL hasta que no tenga 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 valores decimales separados con 4 puntos. El cliente debe manejar cualquier codificación de dirección IP legal, incluidos los componentes octal, hexadecimal y menos de cuatro.
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 los ceros con la sintaxis de dos puntos. Por ejemplo, [2001:0db8:0000::1] debe transformarse en [2001:db8::1]. Si el nombre de host es uno de los dos tipos de dirección IPv6 especiales que se indican a continuación, transfórmalo en 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 que usa el prefijo conocido 64:ff9b::/96, como [64:ff9b::1.2.3.4], que se debería transformar en 1.2.3.4.
5. Pon en minúscula toda la string.

Para canonicalizar la ruta de acceso, sigue estos pasos:

1. Para resolver las secuencias /../ y /./ de la ruta, reemplaza /./ por / y quita /../ junto con el componente de ruta 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 evitan todos los caracteres de escape porcentuales que sean <= ASCII 32, >= 127, # o %. Se deben usar caracteres hexadecimales en mayúsculas en los escapes.

Expresiones de prefijo de ruta de acceso de sufijo host

Una vez que la URL esté canónica, 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 diferentes de sufijo de host y prefijo de ruta de acceso. Estas combinaciones solo utilizan 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 de acceso completa y los parámetros de búsqueda.

Para el host, el cliente intentará como máximo con cinco strings diferentes. Son los siguientes:

• Si el nombre de host no es un literal de IPv4 o IPv6, hasta cuatro nombres de host formados a partir del dominio eTLD+1 y agregando componentes principales sucesivos. La determinación de eTLD+1 debe basarse en la lista de sufijos públicos. Por ejemplo, a.b.example.com daría como resultado 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 en la URL. Siguiendo el ejemplo anterior, a.b.example.com se verificaría.

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.
• Son las cuatro rutas de acceso formadas comenzando por la raíz (/) y agregando sucesivamente los componentes de la ruta, 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 utiliza exclusivamente SHA256 como función de hash. Esta función hash se debe aplicar a las expresiones anteriores.

Según las circunstancias, el hash completo de 32 bytes se truncará a 4, 8 o 16 bytes:

• Cuando se usa el método hashes.search, es necesario que los hashes de la solicitud se trunquen a exactamente 4 bytes. Si envías bytes adicionales en esta solicitud, se comprometerá la privacidad del usuario.

• Cuando descargas las listas para la base de datos local con el método hashList.get o el método hashLists.batchGet, la longitud de los hashes que envía el servidor se ve afectada por la naturaleza de la lista y la preferencia del cliente en cuanto a la longitud del hash, que se comunica mediante el parámetro desired_hash_length.

Procedimiento de verificación de URL en tiempo real

Este procedimiento se usa 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 devuelve SAFE, la Navegación segura de Google considerará que la URL es segura. Si muestra UNSAFE, la Navegación segura de Google considera que la URL es potencialmente no segura y se deben tomar las medidas correspondientes, como mostrar una advertencia al usuario final, mover un mensaje recibido a la carpeta de spam o solicitar una confirmación adicional por parte del usuario antes de continuar. Si muestra UNSURE, se debe usar el siguiente procedimiento de verificación local después.

1. Permite que expressions sea una lista de expresiones de sufijo o prefijo generadas por la URL u.
2. Supongamos que expressionHashes sea una lista, en la que los elementos son hash SHA256 de cada expresión en expressions.
3. Para cada hash de expressionHashes:
   1. Si se encuentra hash en la caché global, muestra UNSURE.
4. Supongamos que expressionHashPrefixes sea una lista, en la que los elementos son 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 posterior a la fecha de vencimiento.
      2. Si es mayor, haz lo siguiente:
         1. Quita la entrada en caché encontrada de la caché local.
         2. Continúa con el bucle.
      3. De lo contrario, haz lo siguiente:
         1. Quitar este expressionHashPrefix específico de expressionHashPrefixes.
         2. Verifica si el hash completo correspondiente dentro de expressionHashes se encuentra en la entrada almacenada en caché.
         3. Si lo encuentra, 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 v5 de la Navegación segura de Google con SearchHashes de RPC o el método REST hashes.search. Si se produjo un error (incluidos errores de red, errores 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 falso, continúa con el bucle.
   3. Si isFound es verdadero, se muestra UNSAFE.
9. Muestra SAFE.

Si bien este protocolo especifica cuándo el cliente envía expressionHashPrefixes al servidor, deliberadamente no especifica cómo enviarlos. Por ejemplo, es aceptable que el cliente envíe todos los expressionHashPrefixes en una sola solicitud y que envíe cada prefijo individual de expressionHashPrefixes al servidor en solicitudes separadas (quizás se realicen en paralelo). También es aceptable que el cliente envíe prefijos de hash no relacionados o generados de forma aleatoria junto con los prefijos hash en expressionHashPrefixes, siempre que la cantidad de prefijos hash enviados en una sola solicitud no sea superior a 30.

Procedimiento de verificación de URL de la lista de amenazas locales

Este procedimiento se usa 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.

En este procedimiento, se toma una sola URL u y se muestra SAFE o UNSAFE.

1. Permite que expressions sea una lista de expresiones de sufijo o prefijo generadas por la URL u.
2. Supongamos que expressionHashes sea una lista, en la que los elementos son hash SHA256 de cada expresión en expressions.
3. Supongamos que expressionHashPrefixes sea una lista, en la que los elementos son 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 posterior a la fecha de vencimiento.
      2. Si es mayor, haz lo siguiente:
         1. Quita la entrada en caché encontrada de la caché local.
         2. Continúa con el bucle.
      3. De lo contrario, haz lo siguiente:
         1. Quitar este expressionHashPrefix específico de expressionHashPrefixes.
         2. Verifica si el hash completo correspondiente dentro de expressionHashes se encuentra en la entrada almacenada en caché.
         3. Si lo encuentra, 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 encuentra expressionHashPrefix en la base de datos de la lista de amenazas local, quítala de expressionHashPrefixes.
6. Envía expressionHashPrefixes al servidor v5 de la Navegación segura de Google con SearchHashes de RPC o el método REST hashes.search. Si se produjo un error (incluidos errores de red, errores 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 falso, continúa con el bucle.
   3. Si isFound es verdadero, se muestra UNSAFE.
9. Muestra SAFE.

Procedimiento de verificación de URL en tiempo real sin una base de datos local

Este procedimiento se usa cuando el cliente elige el modo de operación en tiempo real sin almacenamiento.

En este procedimiento, se toma una sola URL u y se muestra SAFE o UNSAFE.

1. Permite que expressions sea una lista de expresiones de sufijo o prefijo generadas por la URL u.
2. Supongamos que expressionHashes sea una lista, en la que los elementos son hash SHA256 de cada expresión en expressions.
3. Supongamos que expressionHashPrefixes sea una lista, en la que los elementos son 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 posterior a la fecha de vencimiento.
      2. Si es mayor, haz lo siguiente:
         1. Quita la entrada en caché encontrada de la caché local.
         2. Continúa con el bucle.
      3. De lo contrario, haz lo siguiente:
         1. Quitar este expressionHashPrefix específico de expressionHashPrefixes.
         2. Verifica si el hash completo correspondiente dentro de expressionHashes se encuentra en la entrada almacenada en caché.
         3. Si lo encuentra, 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 v5 de la Navegación segura de Google con SearchHashes de RPC o el método REST hashes.search. Si se produjo un error (incluidos errores de red, errores 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 falso, continúa con el bucle.
   3. Si isFound es verdadero, se muestra UNSAFE.
8. Muestra SAFE.

Al igual que el procedimiento de verificación de URL en tiempo real, este procedimiento no especifica exactamente cómo enviar los prefijos de hash al servidor. Por ejemplo, es aceptable que el cliente envíe todos los expressionHashPrefixes en una sola solicitud y que envíe cada prefijo individual de expressionHashPrefixes al servidor en solicitudes separadas (quizás se realicen en paralelo). También es aceptable que el cliente envíe prefijos de hash no relacionados o generados de forma aleatoria junto con los prefijos hash en expressionHashPrefixes, siempre que la cantidad de prefijos hash enviados en una sola solicitud no sea superior a 30.

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. Depende del cliente el formato y el almacenamiento de esta base de datos local. El contenido de esta base de datos local puede considerarse conceptualmente como una carpeta que contiene varias listas como archivos, y el contenido de estos archivos son 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 el cliente típico querrá actualizar varias listas a la vez, se recomienda usar el método hashLists.batchGet.

Las listas se identifican por sus distintos nombres. Los nombres son cadenas ASCII cortas de unos pocos caracteres.

A diferencia de la V4, donde las listas se identifican por la tupla de tipo de amenaza, el tipo de plataforma y el tipo de entrada de amenaza, las listas de la v5 se identifican simplemente por nombre. Esto proporciona flexibilidad cuando múltiples listas v5 podrían compartir el mismo tipo de amenaza. Los tipos de plataforma y de entrada de amenazas se quitan en la v5.

Una vez que se elige un nombre para una lista, no se le cambiará el nombre. Además, una vez que aparezca una lista, nunca se eliminará (si ya no es útil, estará 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.

Los método hashList.get y hashLists.batchGet admiten las actualizaciones incrementales. El uso de actualizaciones incrementales ahorra ancho de banda y mejora el rendimiento. Las actualizaciones incrementales funcionan mediante la entrega de un delta entre la versión del cliente de la lista y la última versión de la lista. (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 de eliminación y adiciones. 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 comprobación no coincide, el cliente debe realizar una actualización completa.

Decodifica el contenido de la lista

Decodificación de hashes y prefijos de hash

Todas las listas se envían con una codificación especial para reducir el tamaño. Esta codificación funciona al reconocer que las listas de Navegación segura de Google contienen, conceptualmente, un conjunto de hash o prefijos de hash, que no se distinguen estadísticamente de los números enteros aleatorios. Si ordenamos estos números enteros y tomemos su diferencia adyacente, se espera que esa diferencia adyacente sea "pequeña" en cierto sentido. Luego, la codificación Golomb-Rice explota esta pequeñez.

Supongamos que se deben transmitir tres expresiones de prefijo de ruta de acceso del sufijo de host, específicamente a.example.com/, b.example.com/ y y.example.com/, mediante prefijos hash de 4 bytes. Además, supongamos que el parámetro Arroz, indicado por k, se elige para que sea 30. El servidor comenzaría por calcular el hash completo para estas cadenas, que, respectivamente, son las siguientes:

291bc5421f1cd54d99afcc55d166e2b9fe42447025895bf09dd41b2110a687dc  a.example.com/
1d32c5084a360e58f1b87109637a6810acad97a861a7769e8f1841410d2a960c  b.example.com/
f7a502e56e8b01c6dc242b35122683c9d25d07fb1f532d9853eb0ef3ff334f03  y.example.com/

Luego, el servidor forma prefijos hash de 4 bytes para cada uno de los valores anteriores, que son los primeros 4 bytes del hash completo de 32 bytes, interpretados como números enteros big-endian de 32 bits. El formato endian se refiere al hecho de que el primer byte del hash completo se convierte en el byte más importante del número entero de 32 bits. Este paso da como resultado los números enteros 0x291bc542, 0x1d32c508 y 0xf7a502e5.

Es necesario que el servidor ordene estos tres prefijos hash de manera lexicográfica (equivalente a la ordenación numérica en big endian) y el resultado del ordenamiento es 0x1d32c508, 0x291bc542, 0xf7a502e5. El primer prefijo de hash se almacena sin cambios en el campo first_value.

Luego, el servidor calcula las dos diferencias adyacentes, que son 0xbe9003a y 0xce893da3, respectivamente. Dado que se elige k para que sea 30, el servidor divide estos dos números en las partes de cociente y en las partes restantes de 2 y 30 bits, respectivamente. Para el primer número, la parte del cociente es cero y el resto es 0xbe9003a; para el segundo número, la parte del cociente es 3 porque los dos bits más significativos son 11 en binario y el resto es 0xe893da3. Para un cociente determinado q, se codifica en (1 << q) - 1 con exactamente 1 + q bits; el resto se codifica directamente con k bits. La parte del cociente del primer número se codifica como 0 y la parte restante es 001011111010010000000000111010; la parte del cociente del segundo número es 0111 y la parte restante es 00111010001001010101010101010101010101

Cuando estos números se forman en una cadena de bytes, se usa Little endian. Conceptualmente, es más fácil imaginar que una cadena de bits larga se forma a partir de los bits menos significativos. Tomamos la parte del cociente del primer número y antecedimos la parte restante del primer número. Luego, antecedemos la parte del cociente del segundo número y antecedimos la parte restante. Esto debería dar como resultado el siguiente número grande (saltos de línea y comentarios agregados para mayor claridad):

001110100010010011110110100011 # Second number, remainder part
0111 # Second number, quotient part
001011111010010000000000111010 # First number, remainder part
0 # First number, quotient part

Escrita en una sola línea,

00111010001001001111011010001101110010111110100100000000001110100

Obviamente, este número supera los 8 bits disponibles en un solo byte. Luego, la codificación Little endian toma los 8 bits menos significativos de ese número y lo muestra como el primer byte, que es 01110100. Para mayor claridad, podemos agrupar la cadena de bits anterior en grupos de ocho empezando por los bits menos significativos:

0 01110100 01001001 11101101 00011011 10010111 11010010 00000000 01110100

Luego, la codificación Little Endian toma cada byte de la derecha y lo coloca en una cadena de bytes:

01110100
00000000
11010010
10010111
00011011
11101101
01001001
01110100
00000000

Como se ve, como prepend las partes nuevas de forma conceptual al número grande de la izquierda (es decir, se agregan más bits significativos), pero codificamos desde la derecha (es decir, los bits menos significativos), la codificación y la decodificación se pueden realizar de forma incremental.

Esto, finalmente, da como resultado

additions_four_bytes {
  first_value: 489866504
  rice_parameter: 30
  entries_count: 2
  encoded_data: "t\000\322\227\033\355It\000"
}

El cliente simplemente sigue los pasos anteriores al revés para decodificar los prefijos de hash. A diferencia de la v4, no es necesario realizar un intercambio de bytes al final debido al hecho de que los números enteros del prefijo de hash se interpretan como big endian.

Índices de eliminación de decodificación

Los índices de eliminación se codifican usando exactamente la misma técnica anterior, con números enteros de 32 bits. La codificación y decodificación de los índices de eliminación no cambiaron entre las versiones 4 y 5.

Listas disponibles

Se recomienda usar las siguientes listas en v5alpha1:

Nombre de la lista	Enum de la v4 ThreatType correspondiente	Descripción
gc	Ninguno	Esta lista es una lista de 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 de amenaza SOCIAL_ENGINEERING.
mw	MALWARE	Esta lista contiene amenazas del tipo de amenaza MALWARE para plataformas de escritorio.
uws	UNWANTED_SOFTWARE	Esta lista contiene amenazas del tipo de amenaza UNWANTED_SOFTWARE para plataformas de escritorio.
uwsa	UNWANTED_SOFTWARE	Esta lista contiene amenazas del tipo de amenaza UNWANTED_SOFTWARE para plataformas de Android.
pha	POTENTIALLY_HARMFUL_APPLICATION	Esta lista contiene amenazas del tipo de amenaza POTENTIALLY_HARMFUL_APPLICATION para plataformas de Android.

Las listas adicionales estarán disponibles más adelante. A partir de ese momento, se expandirá la tabla anterior.

El cliente puede utilizar un servidor proxy de almacenamiento en caché para recuperar algunas o todas las listas anteriores y luego hacer que el cliente se comunique con el servidor proxy. Si se implementa, recomendamos una duración breve de la caché, como cinco minutos. En el futuro, esta duración de la caché se puede comunicar mediante el encabezado HTTP Cache-Control estándar.

Frecuencia de actualización

El cliente debe inspeccionar el valor que muestra el 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 (falta el campo minimum_wait_duration). En ese caso, el cliente DEBE realizar otra actualización de inmediato.

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 idioma generada porque manejará automáticamente la codificación y la decodificación de una manera conveniente. Consulta la documentación de dicha vinculación.

A continuación, se muestra un ejemplo de una 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.

Esta es 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 interrupciones de la v4 a la v5 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 usaría el métodothreatListUpdates.fetch para descargar listas. En la v5, se cambiaría al método hashLists.batchGet.

Se deben realizar los siguientes cambios en la solicitud:

1. Quita el objeto ClientInfo de la versión 4 por completo. En lugar de proporcionar la identificación de un cliente con un campo dedicado, simplemente usa el conocido encabezado User-Agent. Si bien no hay un formato prescrito para proporcionar la identificación de cliente en este encabezado, sugerimos incluir el ID de cliente original y la versión del cliente separados por un carácter de espacio o una barra.
2. Para cada objeto ListUpdateRequest de la versión 4:
   • Busca el nombre de la lista de la v5 correspondiente en la tabla anterior y proporciona ese nombre en la solicitud de la v5.
   • 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 de la versions de la versión 5. La misma cadena de bytes que se enviaría al servidor con el campo state en la versión 4 puede enviarse simplemente en la versión 5 con el campo versions.
   • Para las restricciones de la v4, la v5 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 de la v4 simplemente se reemplaza por un campo booleano llamado partial_update.
2. El campo minimum_wait_duration ahora puede ser cero o también omitirse. Si es así, se le solicita inmediatamente al cliente que realice otra solicitud. 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. Se deberá ajustar el algoritmo de decodificación de arroz para números enteros de 32 bits. La diferencia es que los datos codificados se codifican con una endianidad diferente. Tanto en la v4 como en la v5, los prefijos hash de 32 bits se ordenan de manera lexicográfica. Sin embargo, en la v4, esos prefijos se tratan como endian poco cuando se ordenan, mientras que en la v5 se tratan como big endian cuando se ordenan. Esto significa que el cliente no necesita hacer ningún ordenamiento, ya que la ordenación lexicográfica es idéntica a la ordenación numérica con big endian. Aquí encontrarás un ejemplo de este tipo en la implementación de Chromium de la versión 4. Esta clasificación puede quitarse.
4. El algoritmo de decodificación de arroz deberá implementarse para otras longitudes de hash.

Conversión de búsquedas con hash

En la v4, se usaría 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 realizar los siguientes cambios en la solicitud:

1. Estructura el código para enviar solo prefijos hash que tengan exactamente 4 bytes de longitud.
2. Quita por completo los objetos ClientInfo de la versión 4. En lugar de proporcionar la identificación de un cliente con un campo dedicado, simplemente usa el conocido encabezado User-Agent. Si bien no hay un formato prescrito para proporcionar la identificación de cliente en este encabezado, sugerimos incluir el ID de cliente original y la versión del cliente separados por un carácter de espacio o una barra.
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 nueva solicitud según sea necesario.
2. El objeto ThreatMatch de la versión 4 se simplificó en el objeto FullHash.
3. El almacenamiento en caché se simplificó en una sola duración de caché. Consulta los procedimientos anteriores para interactuar con la caché.