VpnService is a base class for applications to extend and build their own VPN solutions. In general, it creates a virtual network interface, configures addresses and routing rules, and returns a file descriptor to the application. Each read from the descriptor retrieves an outgoing packet which was routed to the interface. Each write to the descriptor injects an incoming packet just like it was received from the interface. The interface is running on Internet Protocol (IP), so packets are always started with IP headers. The application then completes a VPN connection by processing and exchanging packets with the remote server over a tunnel.

Letting applications intercept packets raises huge security concerns. A VPN application can easily break the network. Besides, two of them may conflict with each other. The system takes several actions to address these issues. Here are some key points:

• User action is required the first time an application creates a VPN connection.
• There can be only one VPN connection running at the same time. The existing interface is deactivated when a new one is created.
• A system-managed notification is shown during the lifetime of a VPN connection.
• A system-managed dialog gives the information of the current VPN connection. It also provides a button to disconnect.
• The network is restored automatically when the file descriptor is closed. It also covers the cases when a VPN application is crashed or killed by the system.

There are two primary methods in this class: VpnService.Prepare(Android.Content.Context) and NoType:android/net/VpnService$Builder;Href=../../../reference/android/net/VpnService.Builder.html#establish(). The former deals with user action and stops the VPN connection created by another application. The latter creates a VPN interface using the parameters supplied to the NoType:android/net/VpnService$Builder;Href=../../../reference/android/net/VpnService.Builder.html. An application must call VpnService.Prepare(Android.Content.Context) to grant the right to use other methods in this class, and the right can be revoked at any time. Here are the general steps to create a VPN connection:

1. When the user presses the button to connect, call VpnService.Prepare(Android.Content.Context) and launch the returned intent, if non-null.
2. When the application becomes prepared, start the service.
3. Create a tunnel to the remote server and negotiate the network parameters for the VPN connection.
4. Supply those parameters to a NoType:android/net/VpnService$Builder;Href=../../../reference/android/net/VpnService.Builder.html and create a VPN interface by calling NoType:android/net/VpnService$Builder;Href=../../../reference/android/net/VpnService.Builder.html#establish().
5. Process and exchange packets between the tunnel and the returned file descriptor.
6. When VpnService.OnRevoke is invoked, close the file descriptor and shut down the tunnel gracefully.

Services extended this class need to be declared with appropriate permission and intent filter. Their access must be secured by NoType:android/Manifest$permission;Href=../../../reference/android/Manifest.permission.html#BIND_VPN_SERVICE permission, and their intent filter must match VpnService.ServiceInterface action. Here is an example of declaring a VPN service in AndroidManifest.xml:

 <service android:name=".ExampleVpnService"
         android:permission="android.permission.BIND_VPN_SERVICE">
     <intent-filter>
         <action android:name="android.net.VpnService"/>
     </intent-filter>
 </service>

See Also

• NoType:android/net/VpnService$Builder;Href=../../../reference/android/net/VpnService.Builder.html

[Android Documentation]