Welcome Getting started API Reference Samples
Welcome Getting started API Reference Samples

chrome.vpnProvider

Important: This API works only on Chrome OS
  • Description

    Use the chrome.vpnProvider API to implement a VPN client.

  • Permissions
    vpnProvider

Usage #

Typical usage of vpnProvider is as follows:

  • Create VPN configurations using the createConfig method. A VPN configuration is a persistent entry shown to the user in a native Chrome OS UI. The user can select a VPN configuration from a list and connect to it or disconnect from it.

  • Add listeners to the events onPlatformMessage, onPacketReceived and onConfigRemoved.

  • When the user connects to the VPN configuration, onPlatformMessage will be received with the message "connected". We refer to the period between the messages "connected" and "disconnected" as a VPN session. In this time period, the extension that receives the message is said to own the VPN session.

  • Initiate connection to the VPN server and start the VPN client.

  • Set the Parameters of the connection using setParameters.

  • Notify the connection state as "connected" using notifyConnectionStateChanged.

  • When the steps above are completed without errors, a virtual tunnel is created to the network stack of Chrome OS. IP packets can be sent through the tunnel using sendPacket and any packets originating on the Chrome OS device will be received using the event onPacketReceived.

  • When the user disconnects from the VPN configuration, onPlatformMessage will be fired with the message "disconnected".

  • If the VPN configuration is no longer necessary, it can be destroyed using destroyConfig.

Summary

Types

Parameters

Properties

  • address
    string

    IP address for the VPN interface in CIDR notation. IPv4 is currently the only supported mode.

  • broadcastAddress
    string optional

    Broadcast address for the VPN interface. (default: deduced from IP address and mask)

  • dnsServers
    string[]

    A list of IPs for the DNS servers.

  • domainSearch
    string[] optional

    A list of search domains. (default: no search domain)

  • exclusionList
    string[]

    Exclude network traffic to the list of IP blocks in CIDR notation from the tunnel. This can be used to bypass traffic to and from the VPN server. When many rules match a destination, the rule with the longest matching prefix wins. Entries that correspond to the same CIDR block are treated as duplicates. Such duplicates in the collated (exclusionList + inclusionList) list are eliminated and the exact duplicate entry that will be eliminated is undefined.

  • inclusionList
    string[]

    Include network traffic to the list of IP blocks in CIDR notation to the tunnel. This parameter can be used to set up a split tunnel. By default no traffic is directed to the tunnel. Adding the entry "0.0.0.0/0" to this list gets all the user traffic redirected to the tunnel. When many rules match a destination, the rule with the longest matching prefix wins. Entries that correspond to the same CIDR block are treated as duplicates. Such duplicates in the collated (exclusionList + inclusionList) list are eliminated and the exact duplicate entry that will be eliminated is undefined.

  • mtu
    string optional

    MTU setting for the VPN interface. (default: 1500 bytes)

  • reconnect
    string optional

    Whether or not the VPN extension implements auto-reconnection.

    If true, the linkDown, linkUp, linkChanged, suspend, and resume platform messages will be used to signal the respective events. If false, the system will forcibly disconnect the VPN if the network topology changes, and the user will need to reconnect manually. (default: false)

    This property is new in Chrome 51; it will generate an exception in earlier versions. try/catch can be used to conditionally enable the feature based on browser support.

PlatformMessage

The enum is used by the platform to notify the client of the VPN session status.

Enum

"connected", "disconnected", "error", "linkDown", "linkUp", "linkChanged", "suspend", or "resume"

UIEvent

The enum is used by the platform to indicate the event that triggered onUIEvent.

Enum

"showAddDialog", or "showConfigureDialog"

VpnConnectionState

The enum is used by the VPN client to inform the platform of its current state. This helps provide meaningful messages to the user.

Enum

"connected", or "failure"

Methods

createConfig

chrome.vpnProvider.createConfig(name: string, callback: function)

Creates a new VPN configuration that persists across multiple login sessions of the user.

Parameters

  • name
    string

    The name of the VPN configuration.

  • callback
    function

    Called when the configuration is created or if there is an error.

    The callback parameter should be a function that looks like this:

    (id: string) => {...}
    • id
      string

      A unique ID for the created configuration, or undefined on failure.

destroyConfig

chrome.vpnProvider.destroyConfig(id: string, callback: function)

Destroys a VPN configuration created by the extension.

Parameters

  • id
    string

    ID of the VPN configuration to destroy.

  • callback
    function

    Called when the configuration is destroyed or if there is an error.

    The callback parameter should be a function that looks like this:

    () => {...}

notifyConnectionStateChanged

chrome.vpnProvider.notifyConnectionStateChanged(state: VpnConnectionState, callback: function)

Notifies the VPN session state to the platform. This will succeed only when the VPN session is owned by the extension.

Parameters

  • The VPN session state of the VPN client.

  • callback
    function

    Called when the notification is complete or if there is an error.

    The callback parameter should be a function that looks like this:

    () => {...}

sendPacket

chrome.vpnProvider.sendPacket(data: ArrayBuffer, callback: function)

Sends an IP packet through the tunnel created for the VPN session. This will succeed only when the VPN session is owned by the extension.

Parameters

  • data
    ArrayBuffer

    The IP packet to be sent to the platform.

  • callback
    function

    Called when the packet is sent or if there is an error.

    The callback parameter should be a function that looks like this:

    () => {...}

setParameters

chrome.vpnProvider.setParameters(parameters: Parameters, callback: function)

Sets the parameters for the VPN session. This should be called immediately after "connected" is received from the platform. This will succeed only when the VPN session is owned by the extension.

Parameters

  • parameters

    The parameters for the VPN session.

  • callback
    function

    Called when the parameters are set or if there is an error.

    The callback parameter should be a function that looks like this:

    () => {...}

Events

onConfigCreated

chrome.vpnProvider.onConfigCreated.addListener(listener: function)

Triggered when a configuration is created by the platform for the extension.

Event

  • listener
    function

    The listener parameter should be a function that looks like this:

    (id: string, name: string, data: object) => {...}
    • id
      string

      ID of the configuration created.

    • name
      string

      Name of the configuration created.

    • data
      object

      Configuration data provided by the administrator.

onConfigRemoved

chrome.vpnProvider.onConfigRemoved.addListener(listener: function)

Triggered when a configuration created by the extension is removed by the platform.

Event

  • listener
    function

    The listener parameter should be a function that looks like this:

    (id: string) => {...}
    • id
      string

      ID of the removed configuration.

onPacketReceived

chrome.vpnProvider.onPacketReceived.addListener(listener: function)

Triggered when an IP packet is received via the tunnel for the VPN session owned by the extension.

Event

  • listener
    function

    The listener parameter should be a function that looks like this:

    (data: ArrayBuffer) => {...}
    • data
      ArrayBuffer

      The IP packet received from the platform.

onPlatformMessage

chrome.vpnProvider.onPlatformMessage.addListener(listener: function)

Triggered when a message is received from the platform for a VPN configuration owned by the extension.

Event

  • listener
    function

    The listener parameter should be a function that looks like this:

    (id: string, message: PlatformMessage, error: string) => {...}
    • id
      string

      ID of the configuration the message is intended for.

    • The message received from the platform. Note that new message types may be added in future Chrome versions to support new features.

    • error
      string

      Error message when there is an error.

onUIEvent

chrome.vpnProvider.onUIEvent.addListener(listener: function)

Triggered when there is a UI event for the extension. UI events are signals from the platform that indicate to the app that a UI dialog needs to be shown to the user.

Event

  • listener
    function

    The listener parameter should be a function that looks like this:

    (event: UIEvent, id: string) => {...}
    • event

      The UI event that is triggered.

    • id
      string

      ID of the configuration for which the UI event was triggered.

We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.