chrome.vpnProvider

Description: Use the chrome.vpnProvider API to implement a VPN client.
Availability: Since Chrome 43.
Permissions: "vpnProvider"

Important: This API works only on Chrome OS.

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

Methods
createConfig − chrome.vpnProvider.createConfig(string name, function callback)
destroyConfig − chrome.vpnProvider.destroyConfig(string id, function callback)
setParameters − chrome.vpnProvider.setParameters(object parameters, function callback)
sendPacket − chrome.vpnProvider.sendPacket(ArrayBuffer data, function callback)
notifyConnectionStateChanged − chrome.vpnProvider.notifyConnectionStateChanged(enum of "connected", or "failure" state, function callback)
Events
onPlatformMessage
onPacketReceived
onConfigRemoved
onConfigCreated
onUIEvent

Methods

createConfig

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

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

Parameters
string name

The name of the VPN configuration.

function callback

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

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

function(string id) {...};
string id

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

destroyConfig

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

Destroys a VPN configuration created by the extension.

Parameters
string id

ID of the VPN configuration to destroy.

function (optional) callback

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

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

setParameters

chrome.vpnProvider.setParameters(object parameters, function callback)

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
object parameters

The parameters for the VPN session.

string address

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

string (optional) broadcastAddress

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

string (optional) mtu

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

array of string exclusionList

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.

array of string inclusionList

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.

array of string (optional) domainSearch

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

array of string dnsServers

A list of IPs for the DNS servers.

string (optional) reconnect

Since Chrome 51.

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.
function callback

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

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

function() {...};

sendPacket

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

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
ArrayBuffer data

The IP packet to be sent to the platform.

function (optional) callback

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

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

notifyConnectionStateChanged

chrome.vpnProvider.notifyConnectionStateChanged(enum of "connected", or "failure" state, function callback)

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

Parameters
enum of "connected", or "failure" state

The VPN session state of the VPN client.

connected
VPN connection was successful.
failure
VPN connection failed.
function (optional) callback

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

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

Events

onPlatformMessage

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

addListener

chrome.vpnProvider.onPlatformMessage.addListener(function callback)
Parameters
function callback

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

function(string id, enum of "connected", "disconnected", "error", "linkDown", "linkUp", "linkChanged", "suspend", or "resume" message, string error) {...};
string id

ID of the configuration the message is intended for.

enum of "connected", "disconnected", "error", "linkDown", "linkUp", "linkChanged", "suspend", or "resume" message

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

connected
VPN configuration connected.
disconnected
VPN configuration disconnected.
error
An error occurred in VPN connection, for example a timeout. A description of the error is given as the error argument to onPlatformMessage.
linkDown
The default physical network connection is down.
linkUp
The default physical network connection is back up.
linkChanged
The default physical network connection changed, e.g. wifi->mobile.
suspend
The OS is preparing to suspend, so the VPN should drop its connection. The extension is not guaranteed to receive this event prior to suspending.
resume
The OS has resumed and the user has logged back in, so the VPN should try to reconnect.
string error

Error message when there is an error.

onPacketReceived

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

addListener

chrome.vpnProvider.onPacketReceived.addListener(function callback)
Parameters
function callback

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

function(ArrayBuffer data) {...};
ArrayBuffer data

The IP packet received from the platform.

onConfigRemoved

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

addListener

chrome.vpnProvider.onConfigRemoved.addListener(function callback)
Parameters
function callback

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

function(string id) {...};
string id

ID of the removed configuration.

onConfigCreated

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

addListener

chrome.vpnProvider.onConfigCreated.addListener(function callback)
Parameters
function callback

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

function(string id, string name, object data) {...};
string id

ID of the configuration created.

string name

Name of the configuration created.

object data

Configuration data provided by the administrator.

onUIEvent

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.

addListener

chrome.vpnProvider.onUIEvent.addListener(function callback)
Parameters
function callback

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

function(enum of "showAddDialog", or "showConfigureDialog" event, string id) {...};
enum of "showAddDialog", or "showConfigureDialog" event

The UI event that is triggered.

showAddDialog
Request the VPN client to show add configuration dialog to the user.
showConfigureDialog
Request the VPN client to show configuration settings dialog to the user.
string (optional) id

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