Overview

Nota: Esta documentación aún está en desarrollo. Se esperan mejoras en un futuro cercano.

La versión 5 de la Navegación segura de Google es una evolución de la versión 4. Los dos cambios clave que se realizaron en la versión 5 son la actualización de los datos y la privacidad de la IP. Además, se mejoró la plataforma de la API para aumentar la flexibilidad y la eficiencia, y reducir el aumento excesivo. Además, la versión 5 de Navegación segura de Google está diseñada para facilitar la migración desde la versión 4.

Actualmente, Google ofrece la versión 4 y la 5, y ambas se consideran listas para la producción. Puedes usar la versión 4 o 5. No anunciamos una fecha para la baja de la versión 4. Si lo hacemos, daremos un aviso mínimo de un año. En esta página, se describirá la versión 5, así como una guía de migración de la versión 4 a la 5. La documentación completa de la versión 4 seguirá disponible.

Actualidad de los datos

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 mencionado anteriormente. En la versión 4, se espera que los clientes descarguen y mantengan una base de datos local, realicen verificaciones en las listas de amenazas descargadas de forma local y, luego, cuando haya una coincidencia parcial de prefijos, realicen una solicitud para descargar el hash completo. En la versión 5, aunque los clientes deben seguir descargando y manteniendo una base de datos local de listas de amenazas, ahora también se espera que descarguen una lista de sitios que probablemente sean benignos (llamada caché global), realicen una verificación local de esta caché global y una verificación local de la lista de amenazas y, por último, cuando haya una coincidencia parcial de prefijos para las listas de amenazas o no haya coincidencias en la caché global, realicen una solicitud para descargar los hashes completos. (Para obtener detalles sobre el procesamiento local que requiere el cliente, consulta el procedimiento que se proporciona a continuación). Esto representa un cambio de permitir de forma predeterminada a verificar de forma predeterminada, lo que puede mejorar la protección en función de la propagación más rápida de las amenazas en la Web. En otras palabras, este es un protocolo diseñado para proporcionar protección casi en tiempo real: nuestro objetivo es que los clientes se beneficien de 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 ningún elemento asociado con la identidad de un usuario durante el envío de solicitudes. Si se envían cookies, se ignoran. Google conoce las direcciones IP de origen de las solicitudes, pero solo las usa para necesidades de red esenciales (es decir, para enviar respuestas) y para fines de prevención de DoS.

De forma simultánea con la versión 5, presentamos una API complementaria conocida como la API de Safe Browsing Oblivious HTTP Gateway. Para ello, se usa Oblivious HTTP para ocultar las direcciones IP de los usuarios finales a Google. Funciona con un tercero que no esté en connivencia para controlar una versión encriptada de la solicitud del usuario y, luego, reenviarla 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 conmutador de retransmisión HTTP sin estado (como este servicio de Fastly) y Google opera la puerta de enlace HTTP sin estado. Esta es una API complementaria opcional. Cuando se usa junto con la Navegación segura de Google, las direcciones IP de los usuarios finales ya no se envían a Google.

Los 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 elijan usar la versión 5 de Navegación segura de Google en modo en tiempo real, mantendrán en su base de datos local lo siguiente: (i) una caché global de sitios probablemente benignos, con formato de hash SHA256 de expresiones de URL de sufijo de host o prefijo de ruta, (ii) un conjunto de listas de amenazas, con formato de prefijos de hash SHA256 de expresiones de URL de sufijo de host o prefijo de ruta. La idea de alto nivel es que cada vez que el cliente desee verificar una URL en particular, se realice una verificación local con la caché global. Si se aprueba esa verificación, se realiza una verificación de 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. Esta caché local no tiene que estar 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 versión 5 de la Navegación segura de Google en este modo, su comportamiento es similar al de la API de Update v4, excepto que usan la plataforma de la API mejorada de la versión 5. Los clientes mantendrán en su base de datos local 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. Cada vez que el cliente desea verificar una URL en particular, se realiza una verificación con la lista de amenazas local. Solo si hay una coincidencia, el cliente se conecta al servidor para continuar con la verificación.

Al igual que en 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 versión 5 de Navegación segura de Google en el modo en tiempo real sin almacenamiento, no es necesario que mantengan ninguna base de datos local persistente. Sin embargo, se espera que el cliente mantenga una caché local. Esta caché local no tiene que estar en el almacenamiento persistente y se puede borrar en caso de presión de memoria.

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

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 es inconveniente para el cliente mantener un estado local persistente.

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 muestra SAFE, la Navegación segura de Google considera que la URL es segura. Si muestra UNSAFE, Navegación segura de Google considera 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.

  1. Supongamos que expressions es una lista de expresiones de sufijos o prefijos que genera la URL u.
  2. Supongamos que expressionHashes es una lista, en la que los elementos son valores 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. Supongamos que expressionHashPrefixes es 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é, ocurre lo siguiente:
      1. Determina si la hora actual es mayor que la hora de vencimiento.
      2. Si es mayor, haz lo siguiente:
        1. Quita la entrada almacenada en caché encontrada de la caché local.
        2. Continúa con el bucle.
      3. Si no es mayor, haz lo siguiente:
        1. Quita este expressionHashPrefix en particular de expressionHashPrefixes.
        2. Comprueba si el hash completo correspondiente dentro de expressionHashes se encuentra en la entrada almacenada en caché.
        3. Si se encuentra, muestra UNSAFE.
        4. De lo contrario, 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 la versión 5 de la Navegación segura de Google con RPC SearchHashes 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 de 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. Supongamos que isFound es el resultado de encontrar fullHash en expressionHashes.
    2. Si isFound es False, continúa con el bucle.
    3. Si isFound es verdadero, muestra UNSAFE.
  9. Muestra SAFE.

Si bien este protocolo especifica cuándo el cliente envía expressionHashPrefixes al servidor, no especifica exactamente cómo enviarlos. Por ejemplo, es aceptable que el cliente envíe todos los expressionHashPrefixes en una sola solicitud y también que envíe cada prefijo individual en expressionHashPrefixes al servidor en solicitudes separadas (quizás de forma simultánea). También se acepta que el cliente envíe prefijos 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 supere los 30.

Procedimiento de verificación de URLs de la lista LocalThreat

Este procedimiento se usa cuando el cliente elige el modo de operación de lista local. También se usa cuando el cliente del procedimiento RealTimeCheck anterior muestra el valor de UNSURE.

Este procedimiento toma una sola URL u y muestra SAFE o UNSAFE.

  1. Supongamos que expressions es una lista de expresiones de sufijos o prefijos que genera la URL u.
  2. Supongamos que expressionHashes es una lista, en la que los elementos son valores hash SHA256 de cada expresión en expressions.
  3. Supongamos que expressionHashPrefixes es 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é, ocurre lo siguiente:
      1. Determina si la hora actual es mayor que la hora de vencimiento.
      2. Si es mayor, haz lo siguiente:
        1. Quita la entrada almacenada en caché encontrada de la caché local.
        2. Continúa con el bucle.
      3. Si no es mayor, haz lo siguiente:
        1. Quita este expressionHashPrefix en particular de expressionHashPrefixes.
        2. Comprueba si el hash completo correspondiente dentro de expressionHashes se encuentra en la entrada almacenada en caché.
        3. Si se encuentra, muestra UNSAFE.
        4. De lo contrario, 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 el expressionHashPrefix en la base de datos de la lista de amenazas local, quítalo de expressionHashPrefixes.
  6. Envía expressionHashPrefixes al servidor de la versión 5 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 de 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. Supongamos que isFound es el resultado de encontrar fullHash en expressionHashes.
    2. Si isFound es False, continúa con el bucle.
    3. Si isFound es verdadero, 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.

Este procedimiento toma una sola URL u y muestra SAFE o UNSAFE.

  1. Supongamos que expressions es una lista de expresiones de sufijos o prefijos que genera la URL u.
  2. Supongamos que expressionHashes es una lista, en la que los elementos son valores hash SHA256 de cada expresión en expressions.
  3. Supongamos que expressionHashPrefixes es 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é, ocurre lo siguiente:
      1. Determina si la hora actual es mayor que la hora de vencimiento.
      2. Si es mayor, haz lo siguiente:
        1. Quita la entrada almacenada en caché encontrada de la caché local.
        2. Continúa con el bucle.
      3. Si no es mayor, haz lo siguiente:
        1. Quita este expressionHashPrefix en particular de expressionHashPrefixes.
        2. Comprueba si el hash completo correspondiente dentro de expressionHashes se encuentra en la entrada almacenada en caché.
        3. Si se encuentra, muestra UNSAFE.
        4. De lo contrario, 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 la versión 5 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 de 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. Supongamos que isFound es el resultado de encontrar fullHash en expressionHashes.
    2. Si isFound es False, continúa con el bucle.
    3. Si isFound es verdadero, muestra UNSAFE.
  8. Muestra SAFE.

Al igual que el procedimiento de verificación de URLs en tiempo real, este 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 también que envíe cada prefijo individual en expressionHashPrefixes al servidor en solicitudes separadas (quizás de forma simultánea). También se acepta que el cliente envíe prefijos 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 supere los 30.

Ejemplos de solicitudes

En esta sección, se documentan algunos ejemplos del uso directo de la API de HTTP para acceder a Navegación segura de Google. Por lo general, se recomienda usar una vinculación de lenguaje generada, ya que controlará 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 puedes decodificar.

Este es un ejemplo de solicitud HTTP 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-4b

El cuerpo de la respuesta es, una vez más, una carga útil con formato de búfer de protocolo que puedes decodificar.