| java.lang.Object | ||||
| ↳ | android.content.Context | |||
| ↳ | android.content.ContextWrapper | |||
| ↳ | android.app.Service | |||
| ↳ | android.net.VpnService | |||
Class Overview
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 to create 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: prepare(Context) and 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 VpnService.Builder. An application must call prepare(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:
- When the user press the button to connect, call
prepare(Context)and launch the returned intent. - When the application becomes prepared, start the service.
- Create a tunnel to the remote server and negotiate the network parameters for the VPN connection.
- Supply those parameters to a
VpnService.Builderand create a VPN interface by callingestablish(). - Process and exchange packets between the tunnel and the returned file descriptor.
- When
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 BIND_VPN_SERVICE permission, and their intent filter must match SERVICE_INTERFACE 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
VpnService.Builder
Summary
| Nested Classes | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| VpnService.Builder | Helper class to create a VPN interface. | ||||||||||
| Constants | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| String | SERVICE_INTERFACE | The action must be matched by the intent filter of this service. | |||||||||
| [Expand] Inherited Constants | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| From classandroid.app.Service | |||||||||||
| From classandroid.content.Context | |||||||||||
| From interfaceandroid.content.ComponentCallbacks2 | |||||||||||
| Public Constructors | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Return the communication interface to the service. | |||||||||||
Invoked when the application is revoked. | |||||||||||
Prepare to establish a VPN connection. | |||||||||||
Protect a socket from VPN connections. | |||||||||||
Convenience method to protect a | |||||||||||
Convenience method to protect a | |||||||||||
| [Expand] Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| From class android.app.Service | |||||||||||
| From class android.content.ContextWrapper | |||||||||||
| From class android.content.Context | |||||||||||
| From class java.lang.Object | |||||||||||
| From interface android.content.ComponentCallbacks | |||||||||||
| From interface android.content.ComponentCallbacks2 | |||||||||||
Constants
public static final String SERVICE_INTERFACE
Added in API level 14
The action must be matched by the intent filter of this service. It also needs to require BIND_VPN_SERVICE permission so that other applications cannot abuse it.
Constant Value: "android.net.VpnService"
Public Constructors
public VpnService ()
Added in API level 14
Public Methods
public IBinder onBind (Intent intent)
Added in API level 14
Return the communication interface to the service. This method returns null on Intents other than SERVICE_INTERFACE action. Applications overriding this method must identify the intent and return the corresponding interface accordingly.
Parameters
| intent | The Intent that was used to bind to this service, as given to Context.bindService. Note that any extras that were included with the Intent at that point will not be seen here. |
|---|
Returns
- Return an IBinder through which clients can call on to the service.
See Also
onBind(Intent)
public void onRevoke ()
Added in API level 14
Invoked when the application is revoked. At this moment, the VPN interface is already deactivated by the system. The application should close the file descriptor and shut down gracefully. The default implementation of this method is calling stopSelf().
Calls to this method may not happen on the main thread of the process.
See Also
prepare(Context)
public static Intent prepare (Context context)
Added in API level 14
Prepare to establish a VPN connection. This method returns null if the VPN application is already prepared. Otherwise, it returns an Intent to a system activity. The application should launch the activity using startActivityForResult(Intent, int) to get itself prepared. The activity may pop up a dialog to require user action, and the result will come back via its onActivityResult(int, int, Intent). If the result is RESULT_OK, the application becomes prepared and is granted to use other methods in this class.
Only one application can be granted at the same time. The right is revoked when another application is granted. The application losing the right will be notified via its onRevoke(). Unless it becomes prepared again, subsequent calls to other methods in this class will fail.
See Also
onRevoke()
public boolean protect (int socket)
Added in API level 14
Protect a socket from VPN connections. The socket will be bound to the current default network interface, so its traffic will not be forwarded through VPN. This method is useful if some connections need to be kept outside of VPN. For example, a VPN tunnel should protect itself if its destination is covered by VPN routes. Otherwise its outgoing packets will be sent back to the VPN interface and cause an infinite loop. This method will fail if the application is not prepared or is revoked.
The socket is NOT closed by this method.
Returns
trueon success.
public boolean protect (DatagramSocket socket)
Added in API level 14
Convenience method to protect a DatagramSocket from VPN connections.
Returns
trueon success.
See Also
protect(int)
public boolean protect (Socket socket)
Added in API level 14
Convenience method to protect a Socket from VPN connections.
Returns
trueon success.
See Also
protect(int)
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 4.2r1 —
About Android| Legal| Support
