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:

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: 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 presses the button to connect, call prepare(Context)
and launch the returned intent, if non-null.

When the application becomes prepared, start the service.

Create a tunnel to the remote server and negotiate the network
parameters for the VPN connection.

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 extending this class need to be declared with an 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:

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.

Flag for bindService(Intent, ServiceConnection, int): If binding from an activity, allow the
target service's process importance to be raised based on whether the
activity is visible to the user, regardless whether another flag is
used to reduce the amount that the client process's overall importance
is used to impact it.

This constant was deprecated
in API level 23.
MODE_MULTI_PROCESS does not work reliably in
some versions of Android, and furthermore does not provide any
mechanism for reconciling concurrent modifications across
processes. Applications should not attempt to use it. Instead,
they should use an explicit cross-process data management
approach such as ContentProvider.

This constant was deprecated
in API level 17.
Creating world-readable files is very dangerous, and likely
to cause security holes in applications. It is strongly
discouraged; instead, applications should use more formal
mechanism for interactions such as ContentProvider,
BroadcastReceiver, and Service.
There are no guarantees that this access mode will remain on
a file, such as when it goes through a backup and restore.

This constant was deprecated
in API level 17.
Creating world-writable files is very dangerous, and likely
to cause security holes in applications. It is strongly
discouraged; instead, applications should use more formal
mechanism for interactions such as ContentProvider,
BroadcastReceiver, and Service.
There are no guarantees that this access mode will remain on
a file, such as when it goes through a backup and restore.

Level for onTrimMemory(int): the process is around the middle
of the background LRU list; freeing memory can help the system keep
other processes running later in the list for better overall performance.

Level for onTrimMemory(int): the process is not an expendable
background process, but the device is running extremely low on memory
and is about to not be able to keep any background processes running.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

Broadcast the given intent to all interested BroadcastReceivers, delivering
them one at a time to allow more preferred receivers to consume the
broadcast before it is delivered to less preferred receivers.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

Broadcast the given intent to all interested BroadcastReceivers, delivering
them one at a time to allow more preferred receivers to consume the
broadcast before it is delivered to less preferred receivers.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

Causes the current thread to wait until another thread invokes the
notify() method or the
notifyAll() method for this object, or
some other thread interrupts the current thread, or a certain
amount of real time has elapsed.

Public constructors

VpnService

Public methods

onBind

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

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.

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 stopSelf().

Calls to this method may not happen on the main thread
of the process.

prepare

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

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.

protect

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.

setUnderlyingNetworks

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 bindSocket(Socket) or
bindSocket(DatagramSocket). The VPN should call this method every time
the set of Networks it is using changes.

networks is one of the following:

a non-empty array: an array of one or more Networks, 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.

an empty array: a zero-element array, meaning that the VPN has no
underlying network connection, and thus, app traffic will not be sent or received.

null: (default) signifies that the VPN uses whatever is the system's
default network. I.e., it doesn't use the 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 setUnderlyingNetworks(Network[]).

Parameters

networks

Network: An array of networks the VPN uses to tunnel traffic to/from its servers.