java.lang.Object | ||||
↳ | android.content.Context | |||
↳ | android.content.ContextWrapper | |||
↳ | android.app.Service | |||
↳ | android.net.VpnService |
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:
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:
prepare(Context)
and launch the returned intent.
VpnService.Builder
and create a VPN
interface by calling
establish()
.
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>
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 class
android.app.Service
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class
android.content.Context
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From interface
android.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
DatagramSocket
from VPN
connections.
|
||||||||||
|
Convenience method to protect a
Socket
from VPN connections.
|
[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
|
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.
Return the communication interface to the service. This method returns
null
on
Intent
s other than
SERVICE_INTERFACE
action. Applications overriding this method must identify the intent
and return the corresponding interface accordingly.
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.
|
---|
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.
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.
Protect a socket from VPN connections. After protecting, data sent through this socket will go directly to the underlying network, so its traffic will not be forwarded through the 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.
true
on success.
Convenience method to protect a
DatagramSocket
from VPN
connections.
true
on success.