browser.vpnProvider

Descripción

Usa la API de chrome.vpnProvider para implementar un cliente de VPN.

Permisos

vpnProvider

Disponibilidad

Chrome 43 y versiones posteriores browser.* desde Chrome 148 Solo en ChromeOS

Conceptos y uso

El uso típico de browser.vpnProvider es el siguiente:

  • Crea parámetros de configuración de VPN llamando a createConfig(). Una configuración de VPN es una entrada persistente que se muestra al usuario en una IU de ChromeOS. El usuario puede seleccionar una configuración de VPN de una lista y conectarse a ella o desconectarse.

  • Agrega objetos de escucha a los eventos onPlatformMessage, onPacketReceived y onConfigRemoved.

  • Cuando el usuario se conecte a la configuración de la VPN, se recibirá onPlatformMessage con el mensaje "connected". El período entre los mensajes "connected" y "disconnected" se denomina "sesión de VPN". En este período, se dice que la extensión que recibe el mensaje es propietaria de la sesión de VPN.

  • Inicia la conexión con el servidor de VPN y, luego, el cliente de VPN.

  • Establece los parámetros de la conexión llamando a setParameters().

  • Notifica el estado de la conexión como "connected" llamando a notifyConnectionStateChanged().

  • Cuando los pasos anteriores se completan sin errores, se crea un túnel virtual a la pila de red de ChromeOS. Los paquetes IP se pueden enviar a través del túnel llamando a sendPacket(), y los paquetes que se originen en el dispositivo ChromeOS se recibirán con el controlador de eventos onPacketReceived.

  • Cuando el usuario se desconecte de la configuración de la VPN, se activará onPlatformMessage con el mensaje "disconnected".

  • Si la configuración de la VPN ya no es necesaria, se puede destruir llamando a destroyConfig().

Tipos

Parameters

Propiedades

  • dirección

    string

    Es la dirección IP de la interfaz de VPN en notación CIDR. Por el momento, IPv4 es el único modo compatible.

  • broadcastAddress

    string opcional

    Es la dirección de broadcast de la interfaz de VPN. (predeterminado: se deduce de la dirección IP y la máscara)

  • dnsServers

    string[]

    Es una lista de IPs para los servidores DNS.

  • domainSearch

    string[] opcional

    Es una lista de dominios de búsqueda. (valor predeterminado: sin dominio de búsqueda)

  • exclusionList

    string[]

    Excluye del túnel el tráfico de red a la lista de bloques de IP en notación CIDR. Esto se puede usar para omitir el tráfico hacia y desde el servidor de VPN. Cuando muchas reglas coinciden con un destino, gana la regla con el prefijo coincidente más largo. Las entradas que corresponden al mismo bloque CIDR se tratan como duplicados. Esos duplicados en la lista recopilada (exclusionList + inclusionList) se eliminan, y la entrada duplicada exacta que se eliminará no está definida.

  • inclusionList

    string[]

    Incluye el tráfico de red a la lista de bloques de IP en notación CIDR al túnel. Este parámetro se puede usar para configurar un túnel dividido. De forma predeterminada, no se dirige tráfico al túnel. Si agregas la entrada "0.0.0.0/0" a esta lista, se redireccionará todo el tráfico de los usuarios al túnel. Cuando muchas reglas coinciden con un destino, gana la regla con el prefijo coincidente más largo. Las entradas que corresponden al mismo bloque CIDR se tratan como duplicados. Esos duplicados en la lista recopilada (exclusionList + inclusionList) se eliminan, y la entrada duplicada exacta que se eliminará no está definida.

  • mtu

    string opcional

    Es el parámetro de configuración de MTU para la interfaz de VPN. (valor predeterminado: 1,500 bytes)

  • reconnect

    string opcional

    Chrome 51 y versiones posteriores browser.* desde Chrome 148

    Indica si la extensión de VPN implementa la reconexión automática.

    Si es verdadero, se usarán los mensajes de la plataforma linkDown, linkUp, linkChanged, suspend y resume para indicar los eventos respectivos. Si es falso, el sistema desconectará la VPN de forma forzosa si cambia la topología de red, y el usuario deberá volver a conectarse de forma manual. (predeterminado: false)

    Esta propiedad es nueva en Chrome 51; generará una excepción en versiones anteriores. Se puede usar try/catch para habilitar la función de forma condicional según la compatibilidad del navegador.

PlatformMessage

La plataforma usa la enumeración para notificar al cliente el estado de la sesión de VPN.

Enum

"connected"
Indica que se conectó la configuración de la VPN.

"disconnected"
Indica que se desconectó la configuración de la VPN.

"error"
Indica que se produjo un error en la conexión de VPN, por ejemplo, un tiempo de espera. Se proporciona una descripción del error como el argumento de error para onPlatformMessage.

"linkDown"
Indica que la conexión de red física predeterminada está inactiva.

"linkUp"
Indica que la conexión de red física predeterminada se restableció.

"linkChanged"
Indica que cambió la conexión de red física predeterminada, p.ej., de Wi-Fi a móvil.

"suspend"
Indica que el SO se está preparando para suspenderse, por lo que la VPN debe interrumpir su conexión. No se garantiza que la extensión reciba este evento antes de suspenderse.

"resume"
Indica que el SO se reanudó y el usuario volvió a acceder, por lo que la VPN debería intentar volver a conectarse.

UIEvent

La plataforma usa la enumeración para indicar el evento que activó onUIEvent.

Enum

"showAddDialog"
Solicita que el cliente de VPN muestre el cuadro de diálogo para agregar la configuración al usuario.

"showConfigureDialog"
Solicita que el cliente de VPN muestre el cuadro de diálogo de configuración al usuario.

VpnConnectionState

El cliente de VPN usa la enumeración para informar a la plataforma sobre su estado actual. Esto ayuda a proporcionar mensajes significativos al usuario.

Enum

"connected"
Especifica que la conexión de VPN se realizó correctamente.

"failure"
Especifica que la conexión de VPN falló.

Métodos

createConfig()

browser.vpnProvider.createConfig(
  name: string,
): Promise<string>

Crea una nueva configuración de VPN que persiste en varias sesiones de acceso del usuario.

Parámetros

  • nombre

    string

    Es el nombre de la configuración de la VPN.

Muestra

  • Promise<string>

    Chrome 96 y versiones posteriores browser.* desde Chrome 148

    Devuelve una promesa que se resuelve cuando se crea la configuración o se rechaza si hay un error.

destroyConfig()

browser.vpnProvider.destroyConfig(
  id: string,
): Promise<void>

Destruye una configuración de VPN creada por la extensión.

Parámetros

  • id

    string

    Es el ID de la configuración de VPN que se destruirá.

Muestra

  • Promise<void>

    Chrome 96 y versiones posteriores browser.* desde Chrome 148

    Devuelve una promesa que se resuelve cuando se destruye la configuración o se rechaza si hay un error.

notifyConnectionStateChanged()

browser.vpnProvider.notifyConnectionStateChanged(
  state: VpnConnectionState,
): Promise<void>

Notifica el estado de la sesión de VPN a la plataforma. Esto solo se realizará correctamente cuando la extensión sea propietaria de la sesión de VPN.

Parámetros

Muestra

  • Promise<void>

    Chrome 96 y versiones posteriores browser.* desde Chrome 148

    Devuelve una promesa que se resuelve cuando se completa la notificación o se rechaza si hay un error.

sendPacket()

browser.vpnProvider.sendPacket(
  data: ArrayBuffer,
): Promise<void>

Envía un paquete IP a través del túnel creado para la sesión de VPN. Esto solo se realizará correctamente cuando la sesión de VPN sea propiedad de la extensión.

Parámetros

  • datos

    ArrayBuffer

    Es el paquete IP que se enviará a la plataforma.

Muestra

  • Promise<void>

    Chrome 96 y versiones posteriores browser.* desde Chrome 148

    Devuelve una promesa que se resuelve cuando se envía el paquete o se rechaza si hay un error.

setParameters()

browser.vpnProvider.setParameters(
  parameters: Parameters,
): Promise<void>

Establece los parámetros para la sesión de VPN. Se debe llamar inmediatamente después de que se reciba "connected" de la plataforma. Esto solo se realizará correctamente cuando la sesión de VPN sea propiedad de la extensión.

Parámetros

  • Parámetros

    Parámetros

    Son los parámetros de la sesión de VPN.

Muestra

  • Promise<void>

    Chrome 96 y versiones posteriores browser.* desde Chrome 148

    Devuelve una promesa que se resuelve cuando se establecen los parámetros o se rechaza si hay un error.

Eventos

onConfigCreated

browser.vpnProvider.onConfigCreated.addListener(
  callback: function,
)

Se activa cuando la plataforma crea una configuración para la extensión.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (id: string, name: string, data: object) => void

    • id

      string

    • nombre

      string

    • datos

      objeto

onConfigRemoved

browser.vpnProvider.onConfigRemoved.addListener(
  callback: function,
)

Se activa cuando la plataforma quita una configuración creada por la extensión.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (id: string) => void

    • id

      string

onPacketReceived

browser.vpnProvider.onPacketReceived.addListener(
  callback: function,
)

Se activa cuando se recibe un paquete IP a través del túnel para la sesión de VPN que pertenece a la extensión.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (data: ArrayBuffer) => void

    • datos

      ArrayBuffer

onPlatformMessage

browser.vpnProvider.onPlatformMessage.addListener(
  callback: function,
)

Se activa cuando se recibe un mensaje de la plataforma para una configuración de VPN que pertenece a la extensión.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (id: string, message: PlatformMessage, error: string) => void

onUIEvent

browser.vpnProvider.onUIEvent.addListener(
  callback: function,
)

Se activa cuando hay un evento de IU para la extensión. Los eventos de la IU son indicadores de la plataforma que le indican a la app que se debe mostrar un diálogo de la IU al usuario.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (event: UIEvent, id?: string) => void

    • evento

      UIEvent

    • id

      string opcional