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: {@link #prepare} and * {@link 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 {@link Builder}. * An application must call {@link #prepare} 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: *
Services extending this class need to be declared with an appropriate * permission and intent filter. Their access must be secured by * {@link android.Manifest.permission#BIND_VPN_SERVICE} permission, and * their intent filter must match {@link #SERVICE_INTERFACE} action. Here * is an example of declaring a VPN service in {@code 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 * {@link android.content.Context#startService startService()}. In Android 8.0 * (API level 26) and higher, the system places VPN apps on the temporary * allowlist 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 Builder */ public class VpnService extends Service { /** * The action must be matched by the intent filter of this service. It also * needs to require {@link android.Manifest.permission#BIND_VPN_SERVICE} * permission so that other applications cannot abuse it. */ public static final String SERVICE_INTERFACE = VpnConfig.SERVICE_INTERFACE; /** * Key for boolean meta-data field indicating whether this VpnService supports always-on mode. * *
For a VPN app targeting {@link android.os.Build.VERSION_CODES#N 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 * {@link DevicePolicyManager#setAlwaysOnVpnPackage}. * *
VPN apps not supporting this feature should opt out by adding this meta-data field to the * {@code VpnService} component of {@code AndroidManifest.xml}. In case there is more than one * {@code VpnService} component defined in {@code AndroidManifest.xml}, opting out any one of * them will opt out the entire app. For example, *
{@code
*
*
*
*
*
* }
*
* This meta-data field defaults to {@code true} if absent. It will only have effect on * {@link android.os.Build.VERSION_CODES#O_MR1} or higher. */ public static final String SERVICE_META_DATA_SUPPORTS_ALWAYS_ON = "android.net.VpnService.SUPPORTS_ALWAYS_ON"; /** * Use IVpnManager since those methods are hidden and not available in VpnManager. */ private static IVpnManager getService() { return IVpnManager.Stub.asInterface( ServiceManager.getService(Context.VPN_MANAGEMENT_SERVICE)); } /** * Prepare to establish a VPN connection. This method returns {@code null} * if the VPN application is already prepared or if the user has previously * consented to the VPN application. Otherwise, it returns an * {@link Intent} to a system activity. The application should launch the * activity using {@link 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 {@link Activity#onActivityResult}. * If the result is {@link 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 {@link #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. * * @see #onRevoke */ public static Intent prepare(Context context) { try { if (getService().prepareVpn(context.getPackageName(), null, context.getUserId())) { return null; } } catch (RemoteException e) { // ignore } return VpnConfig.getIntentForConfirmation(); } /** * Version of {@link #prepare(Context)} which does not require user consent. * *
Requires {@link android.Manifest.permission#CONTROL_VPN} and should generally not be * used. Only acceptable in situations where user consent has been obtained through other means. * *
Once this is run, future preparations may be done with the standard prepare method as this * will authorize the package to prepare the VPN without consent in the future. * * @hide */ @SystemApi @RequiresPermission(android.Manifest.permission.CONTROL_VPN) public static void prepareAndAuthorize(Context context) { IVpnManager vm = getService(); String packageName = context.getPackageName(); try { // Only prepare if we're not already prepared. int userId = context.getUserId(); if (!vm.prepareVpn(packageName, null, userId)) { vm.prepareVpn(null, packageName, userId); } vm.setVpnPackageAuthorization(packageName, userId, VpnManager.TYPE_VPN_SERVICE); } catch (RemoteException e) { // ignore } } /** * 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. * * @return {@code true} on success. */ public boolean protect(int socket) { return NetworkUtilsInternal.protectFromVpn(socket); } /** * Convenience method to protect a {@link Socket} from VPN connections. * * @return {@code true} on success. * @see #protect(int) */ public boolean protect(Socket socket) { return protect(socket.getFileDescriptor$().getInt$()); } /** * Convenience method to protect a {@link DatagramSocket} from VPN * connections. * * @return {@code true} on success. * @see #protect(int) */ public boolean protect(DatagramSocket socket) { return protect(socket.getFileDescriptor$().getInt$()); } /** * Adds a network address to the VPN interface. * * Both IPv4 and IPv6 addresses are supported. The VPN must already be established. Fails if the * address is already in use or cannot be assigned to the interface for any other reason. * * Adding an address implicitly allows traffic from that address family (i.e., IPv4 or IPv6) to * be routed over the VPN. @see Builder#allowFamily * * @throws IllegalArgumentException if the address is invalid. * * @param address The IP address (IPv4 or IPv6) to assign to the VPN interface. * @param prefixLength The prefix length of the address. * * @return {@code true} on success. * @see Builder#addAddress * * @hide */ public boolean addAddress(InetAddress address, int prefixLength) { check(address, prefixLength); try { return getService().addVpnAddress(address.getHostAddress(), prefixLength); } catch (RemoteException e) { throw new IllegalStateException(e); } } /** * Removes a network address from the VPN interface. * * Both IPv4 and IPv6 addresses are supported. The VPN must already be established. Fails if the * address is not assigned to the VPN interface, or if it is the only address assigned (thus * cannot be removed), or if the address cannot be removed for any other reason. * * After removing an address, if there are no addresses, routes or DNS servers of a particular * address family (i.e., IPv4 or IPv6) configured on the VPN, that DOES NOT block that * family from being routed. In other words, once an address family has been allowed, it stays * allowed for the rest of the VPN's session. @see Builder#allowFamily * * @throws IllegalArgumentException if the address is invalid. * * @param address The IP address (IPv4 or IPv6) to assign to the VPN interface. * @param prefixLength The prefix length of the address. * * @return {@code true} on success. * * @hide */ public boolean removeAddress(InetAddress address, int prefixLength) { check(address, prefixLength); try { return getService().removeVpnAddress(address.getHostAddress(), prefixLength); } catch (RemoteException e) { throw new IllegalStateException(e); } } /** * 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 {@link #protect(int)} — * to a {@code Network} using APIs such as {@link Network#bindSocket(Socket)} or * {@link Network#bindSocket(DatagramSocket)}. The VPN should call this method every time * the set of {@code Network}s it is using changes. * *
{@code networks} is one of the following: *
This call will succeed only if the VPN is currently established. For setting this value * when the VPN has not yet been established, see {@link Builder#setUnderlyingNetworks}. * * @param networks An array of networks the VPN uses to tunnel traffic to/from its servers. * * @return {@code true} on success. */ public boolean setUnderlyingNetworks(Network[] networks) { try { return getService().setUnderlyingNetworksForVpn(networks); } catch (RemoteException e) { throw new IllegalStateException(e); } } /** * 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. * * @see DevicePolicyManager#setAlwaysOnVpnPackage(ComponentName, String, boolean, Set) */ public final boolean isAlwaysOn() { try { return getService().isCallerCurrentAlwaysOnVpnApp(); } catch (RemoteException e) { throw e.rethrowFromSystemServer(); } } /** * 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. * * @see DevicePolicyManager#setAlwaysOnVpnPackage(ComponentName, String, boolean, Set) */ public final boolean isLockdownEnabled() { try { return getService().isCallerCurrentAlwaysOnVpnLockdownApp(); } catch (RemoteException e) { throw e.rethrowFromSystemServer(); } } /** * Return the communication interface to the service. This method returns * {@code null} on {@link Intent}s other than {@link #SERVICE_INTERFACE} * action. Applications overriding this method must identify the intent * and return the corresponding interface accordingly. * * @see Service#onBind */ @Override public IBinder onBind(Intent intent) { if (intent != null && SERVICE_INTERFACE.equals(intent.getAction())) { return new Callback(); } return null; } /** * 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 {@link Service#stopSelf()}. * *
Calls to this method may not happen on the main thread
* of the process.
*
* @see #prepare
*/
public void onRevoke() {
stopSelf();
}
/**
* Use raw Binder instead of AIDL since now there is only one usage.
*/
private class Callback extends Binder {
@Override
protected boolean onTransact(int code, Parcel data, Parcel reply, int flags) {
if (code == IBinder.LAST_CALL_TRANSACTION) {
onRevoke();
return true;
}
return false;
}
}
/**
* Private method to validate address and prefixLength.
*/
private static void check(InetAddress address, int prefixLength) {
if (address.isLoopbackAddress()) {
throw new IllegalArgumentException("Bad address");
}
if (address instanceof Inet4Address) {
if (prefixLength < 0 || prefixLength > 32) {
throw new IllegalArgumentException("Bad prefixLength");
}
} else if (address instanceof Inet6Address) {
if (prefixLength < 0 || prefixLength > 128) {
throw new IllegalArgumentException("Bad prefixLength");
}
} else {
throw new IllegalArgumentException("Unsupported family");
}
}
/**
* Helper class to create a VPN interface. This class should be always
* used within the scope of the outer {@link VpnService}.
*
* @see VpnService
*/
public class Builder {
private final VpnConfig mConfig = new VpnConfig();
@UnsupportedAppUsage
private final List VPN apps targeting {@link android.os.Build.VERSION_CODES#Q} or above will be
* considered metered by default.
*
* @param isMetered {@code true} if VPN network should be treated as metered regardless of
* underlying network meteredness
* @return this {@link Builder} object to facilitate chaining method calls
* @see #setUnderlyingNetworks(Network[])
* @see ConnectivityManager#isActiveNetworkMetered()
*/
@NonNull
public Builder setMetered(boolean isMetered) {
mConfig.isMetered = isMetered;
return this;
}
/**
* Create a VPN interface using the parameters supplied to this
* builder. The interface works on IP packets, and a file descriptor
* is returned for the application to access them. Each read
* retrieves an outgoing packet which was routed to the interface.
* Each write injects an incoming packet just like it was received
* from the interface. The file descriptor is put into non-blocking
* mode by default to avoid blocking Java threads. To use the file
* descriptor completely in native space, see
* {@link ParcelFileDescriptor#detachFd()}. The application MUST
* close the file descriptor when the VPN connection is terminated.
* The VPN interface will be removed and the network will be
* restored by the system automatically.
*
* To avoid conflicts, there can be only one active VPN interface
* at the same time. Usually network parameters are never changed
* during the lifetime of a VPN connection. It is also common for an
* application to create a new file descriptor after closing the
* previous one. However, it is rare but not impossible to have two
* interfaces while performing a seamless handover. In this case, the
* old interface will be deactivated when the new one is created
* successfully. Both file descriptors are valid but now outgoing
* packets will be routed to the new interface. Therefore, after
* draining the old file descriptor, the application MUST close it
* and start using the new file descriptor. If the new interface
* cannot be created, the existing interface and its file descriptor
* remain untouched.
*
* An exception will be thrown if the interface cannot be created
* for any reason. However, this method returns {@code null} if the
* application is not prepared or is revoked. This helps solve
* possible race conditions between other VPN applications.
*
* @return {@link ParcelFileDescriptor} of the VPN interface, or
* {@code null} if the application is not prepared.
* @throws IllegalArgumentException if a parameter is not accepted
* by the operating system.
* @throws IllegalStateException if a parameter cannot be applied
* by the operating system.
* @throws SecurityException if the service is not properly declared
* in {@code AndroidManifest.xml}.
* @see VpnService
*/
@Nullable
public ParcelFileDescriptor establish() {
mConfig.addresses = mAddresses;
mConfig.routes = mRoutes;
try {
return getService().establishVpn(mConfig);
} catch (RemoteException e) {
throw new IllegalStateException(e);
}
}
}
}