# Print output for @column tags ?>
public
class
VpnService
extends Service
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
Builder#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 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, if non-null.Builder
and create a VPN
interface by calling Builder#establish
.onRevoke()
is invoked, close the file descriptor and
shut down the tunnel gracefully.Services extending this class need to be declared with an appropriate
permission and intent filter. Their access must be secured by
Manifest.permission.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>
The Android system starts a VPN in the background by calling
startService()
. In Android 8.0
(API level 26) and higher, the system places VPN apps on the temporary
whitelist for a short period so the app can start in the background. The VPN
app must promote itself to the foreground after it's launched or the system
will shut down the app.
To learn more about developing VPN apps, read the VPN developer's guide.
See also:
Nested classes | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
class |
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. |
String |
SERVICE_META_DATA_SUPPORTS_ALWAYS_ON
Key for boolean meta-data field indicating whether this VpnService supports always-on mode. |
Inherited constants | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
From class
android.app.Service
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class
android.content.Context
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From interface
android.content.ComponentCallbacks2
|
Public constructors | |
---|---|
VpnService()
|
Public methods | |
---|---|
final
boolean
|
isAlwaysOn()
Returns whether the service is running in always-on VPN mode. |
final
boolean
|
isLockdownEnabled()
Returns whether the service is running in always-on VPN lockdown mode. |
IBinder
|
onBind(Intent intent)
Return the communication interface to the service. |
void
|
onRevoke()
Invoked when the application is revoked. |
static
Intent
|
prepare(Context context)
Prepare to establish a VPN connection. |
boolean
|
protect(Socket socket)
Convenience method to protect a |
boolean
|
protect(int socket)
Protect a socket from VPN connections. |
boolean
|
protect(DatagramSocket socket)
Convenience method to protect a |
boolean
|
setUnderlyingNetworks(Network[] networks)
Sets the underlying networks used by the VPN for its upstream connections. |
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.ComponentCallbacks2
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From interface
android.content.ComponentCallbacks
|
public static final String SERVICE_INTERFACE
The action must be matched by the intent filter of this service. It also
needs to require Manifest.permission.BIND_VPN_SERVICE
permission so that other applications cannot abuse it.
Constant Value: "android.net.VpnService"
public static final String SERVICE_META_DATA_SUPPORTS_ALWAYS_ON
Key for boolean meta-data field indicating whether this VpnService supports always-on mode.
For a VPN app targeting API 24
or above, Android
provides users with the ability to set it as always-on, so that VPN connection is
persisted after device reboot and app upgrade. Always-on VPN can also be enabled by device
owner and profile owner apps through
DevicePolicyManager#setAlwaysOnVpnPackage
.
VPN apps not supporting this feature should opt out by adding this meta-data field to the
VpnService
component of AndroidManifest.xml
. In case there is more than one
VpnService
component defined in AndroidManifest.xml
, opting out any one of
them will opt out the entire app. For example,
<service android:name=".ExampleVpnService"
android:permission="android.permission.BIND_VPN_SERVICE">
<intent-filter>
<action android:name="android.net.VpnService"/>
</intent-filter>
<meta-data android:name="android.net.VpnService.SUPPORTS_ALWAYS_ON"
android:value=false/>
</service>
This meta-data field defaults to true
if absent. It will only have effect on
Build.VERSION_CODES.O_MR1
or higher.
Constant Value: "android.net.VpnService.SUPPORTS_ALWAYS_ON"
public VpnService ()
public final boolean isAlwaysOn ()
Returns whether the service is running in always-on VPN mode. In this mode the system ensures that the service is always running by restarting it when necessary, e.g. after reboot.
Returns | |
---|---|
boolean |
public final boolean isLockdownEnabled ()
Returns whether the service is running in always-on VPN lockdown mode. In this mode the system ensures that the service is always running and that the apps aren't allowed to bypass the VPN.
Returns | |
---|---|
boolean |
public IBinder onBind (Intent intent)
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.
Parameters | |
---|---|
intent |
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 | |
---|---|
IBinder |
Return an IBinder through which clients can call on to the service. |
See also:
public void onRevoke ()
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 Service#stopSelf()
.
Calls to this method may not happen on the main thread of the process.
See also:
public static Intent prepare (Context context)
Prepare to establish a VPN connection. This method returns null
if the VPN application is already prepared or if the user has previously
consented to the VPN application. Otherwise, it returns an
Intent
to a system activity. The application should launch the
activity using Activity#startActivityForResult
to get itself
prepared. The activity may pop up a dialog to require user action, and
the result will come back via its Activity#onActivityResult
.
If the result is Activity#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.
The user may disable the VPN at any time while it is activated, in which case this method will return an intent the next time it is executed to obtain the user's consent again.
Parameters | |
---|---|
context |
Context |
Returns | |
---|---|
Intent |
See also:
public boolean protect (Socket socket)
Convenience method to protect a Socket
from VPN connections.
Parameters | |
---|---|
socket |
Socket |
Returns | |
---|---|
boolean |
true on success. |
See also:
public boolean protect (int socket)
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.
Parameters | |
---|---|
socket |
int |
Returns | |
---|---|
boolean |
true on success. |
public boolean protect (DatagramSocket socket)
Convenience method to protect a DatagramSocket
from VPN
connections.
Parameters | |
---|---|
socket |
DatagramSocket |
Returns | |
---|---|
boolean |
true on success. |
See also:
public boolean setUnderlyingNetworks (Network[] networks)
Sets the underlying networks used by the VPN for its upstream connections.
Used by the system to know the actual networks that carry traffic for apps affected by this VPN in order to present this information to the user (e.g., via status bar icons).
This method only needs to be called if the VPN has explicitly bound its underlying
communications channels — such as the socket(s) passed to protect(int)
—
to a Network
using APIs such as Network#bindSocket(Socket)
or
Network#bindSocket(DatagramSocket)
. The VPN should call this method every time
the set of Network
s it is using changes.
networks
is one of the following:
Network
s, in
decreasing preference order. For example, if this VPN uses both wifi and mobile (cellular)
networks to carry app traffic, but prefers or uses wifi more than mobile, wifi should appear
first in the array.bindSocket
or bindDatagramSocket
APIs mentioned above to send traffic over specific channels.This call will succeed only if the VPN is currently established. For setting this value
when the VPN has not yet been established, see Builder#setUnderlyingNetworks
.
Parameters | |
---|---|
networks |
Network : An array of networks the VPN uses to tunnel traffic to/from its servers. |
Returns | |
---|---|
boolean |
true on success. |
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 7.0 r1 —