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 extended this class need to be declared with 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>* * @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; /** * Use IConnectivityManager since those methods are hidden and not * available in ConnectivityManager. */ private static IConnectivityManager getService() { return IConnectivityManager.Stub.asInterface( ServiceManager.getService(Context.CONNECTIVITY_SERVICE)); } /** * Prepare to establish a VPN connection. This method returns {@code null} * if the VPN application is already prepared. 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. * * @see #onRevoke */ public static Intent prepare(Context context) { try { if (getService().prepareVpn(context.getPackageName(), null)) { return null; } } catch (RemoteException e) { // ignore } return VpnConfig.getIntentForConfirmation(); } /** * 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. * * @return {@code true} on success. */ public boolean protect(int socket) { ParcelFileDescriptor dup = null; try { dup = ParcelFileDescriptor.fromFd(socket); return getService().protectVpn(dup); } catch (Exception e) { return false; } finally { try { dup.close(); } catch (Exception e) { // ignore } } } /** * 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$()); } /** * 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;
}
}
/**
* 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();
private final StringBuilder mAddresses = new StringBuilder();
private final StringBuilder mRoutes = new StringBuilder();
public Builder() {
mConfig.user = VpnService.this.getClass().getName();
}
/**
* Set the name of this session. It will be displayed in
* system-managed dialogs and notifications. This is recommended
* not required.
*/
public Builder setSession(String session) {
mConfig.session = session;
return this;
}
/**
* Set the {@link PendingIntent} to an activity for users to
* configure the VPN connection. If it is not set, the button
* to configure will not be shown in system-managed dialogs.
*/
public Builder setConfigureIntent(PendingIntent intent) {
mConfig.configureIntent = intent;
return this;
}
/**
* Set the maximum transmission unit (MTU) of the VPN interface. If
* it is not set, the default value in the operating system will be
* used.
*
* @throws IllegalArgumentException if the value is not positive.
*/
public Builder setMtu(int mtu) {
if (mtu <= 0) {
throw new IllegalArgumentException("Bad mtu");
}
mConfig.mtu = mtu;
return this;
}
/**
* Private method to validate address and prefixLength.
*/
private 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");
}
}
/**
* Add a network address to the VPN interface. Both IPv4 and IPv6
* addresses are supported. At least one address must be set before
* calling {@link #establish}.
*
* @throws IllegalArgumentException if the address is invalid.
*/
public Builder addAddress(InetAddress address, int prefixLength) {
check(address, prefixLength);
if (address.isAnyLocalAddress()) {
throw new IllegalArgumentException("Bad address");
}
mAddresses.append(' ' + address.getHostAddress() + '/' + prefixLength);
return this;
}
/**
* Convenience method to add a network address to the VPN interface
* using a numeric address string. See {@link InetAddress} for the
* definitions of numeric address formats.
*
* @throws IllegalArgumentException if the address is invalid.
* @see #addAddress(InetAddress, int)
*/
public Builder addAddress(String address, int prefixLength) {
return addAddress(InetAddress.parseNumericAddress(address), prefixLength);
}
/**
* Add a network route to the VPN interface. Both IPv4 and IPv6
* routes are supported.
*
* @throws IllegalArgumentException if the route is invalid.
*/
public Builder addRoute(InetAddress address, int prefixLength) {
check(address, prefixLength);
int offset = prefixLength / 8;
byte[] bytes = address.getAddress();
if (offset < bytes.length) {
for (bytes[offset] <<= prefixLength % 8; offset < bytes.length; ++offset) {
if (bytes[offset] != 0) {
throw new IllegalArgumentException("Bad address");
}
}
}
mRoutes.append(String.format(" %s/%d", address.getHostAddress(), prefixLength));
return this;
}
/**
* Convenience method to add a network route to the VPN interface
* using a numeric address string. See {@link InetAddress} for the
* definitions of numeric address formats.
*
* @throws IllegalArgumentException if the route is invalid.
* @see #addRoute(InetAddress, int)
*/
public Builder addRoute(String address, int prefixLength) {
return addRoute(InetAddress.parseNumericAddress(address), prefixLength);
}
/**
* Add a DNS server to the VPN connection. Both IPv4 and IPv6
* addresses are supported. If none is set, the DNS servers of
* the default network will be used.
*
* @throws IllegalArgumentException if the address is invalid.
*/
public Builder addDnsServer(InetAddress address) {
if (address.isLoopbackAddress() || address.isAnyLocalAddress()) {
throw new IllegalArgumentException("Bad address");
}
if (mConfig.dnsServers == null) {
mConfig.dnsServers = new ArrayList 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
*/
public ParcelFileDescriptor establish() {
mConfig.addresses = mAddresses.toString();
mConfig.routes = mRoutes.toString();
try {
return getService().establishVpn(mConfig);
} catch (RemoteException e) {
throw new IllegalStateException(e);
}
}
}
}