| /* |
| * Copyright (C) 2011 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package android.net; |
| |
| import static android.system.OsConstants.AF_INET; |
| import static android.system.OsConstants.AF_INET6; |
| |
| import android.annotation.NonNull; |
| import android.annotation.Nullable; |
| import android.annotation.RequiresPermission; |
| import android.annotation.SystemApi; |
| import android.annotation.UnsupportedAppUsage; |
| import android.app.Activity; |
| import android.app.PendingIntent; |
| import android.app.Service; |
| import android.app.admin.DevicePolicyManager; |
| import android.content.ComponentName; |
| import android.content.Context; |
| import android.content.Intent; |
| import android.content.pm.IPackageManager; |
| import android.content.pm.PackageManager; |
| import android.os.Binder; |
| import android.os.IBinder; |
| import android.os.Parcel; |
| import android.os.ParcelFileDescriptor; |
| import android.os.RemoteException; |
| import android.os.ServiceManager; |
| import android.os.UserHandle; |
| |
| import com.android.internal.net.VpnConfig; |
| |
| import java.net.DatagramSocket; |
| import java.net.Inet4Address; |
| import java.net.Inet6Address; |
| import java.net.InetAddress; |
| import java.net.Socket; |
| import java.util.ArrayList; |
| import java.util.List; |
| import java.util.Set; |
| |
| /** |
| * 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. |
| * |
| * <p>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: |
| * <ul> |
| * <li>User action is required the first time an application creates a VPN |
| * connection.</li> |
| * <li>There can be only one VPN connection running at the same time. The |
| * existing interface is deactivated when a new one is created.</li> |
| * <li>A system-managed notification is shown during the lifetime of a |
| * VPN connection.</li> |
| * <li>A system-managed dialog gives the information of the current VPN |
| * connection. It also provides a button to disconnect.</li> |
| * <li>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.</li> |
| * </ul> |
| * |
| * <p>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: |
| * <ol> |
| * <li>When the user presses the button to connect, call {@link #prepare} |
| * and launch the returned intent, if non-null.</li> |
| * <li>When the application becomes prepared, start the service.</li> |
| * <li>Create a tunnel to the remote server and negotiate the network |
| * parameters for the VPN connection.</li> |
| * <li>Supply those parameters to a {@link Builder} and create a VPN |
| * interface by calling {@link Builder#establish}.</li> |
| * <li>Process and exchange packets between the tunnel and the returned |
| * file descriptor.</li> |
| * <li>When {@link #onRevoke} is invoked, close the file descriptor and |
| * shut down the tunnel gracefully.</li> |
| * </ol> |
| * |
| * <p>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}: |
| * <pre> |
| * <service android:name=".ExampleVpnService" |
| * android:permission="android.permission.BIND_VPN_SERVICE"> |
| * <intent-filter> |
| * <action android:name="android.net.VpnService"/> |
| * </intent-filter> |
| * </service></pre> |
| * |
| * <p> 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 |
| * 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. |
| * |
| * <h3>Developer's guide</h3> |
| * |
| * <p>To learn more about developing VPN apps, read the |
| * <a href="{@docRoot}guide/topics/connectivity/vpn">VPN developer's guide</a>. |
| * |
| * @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. |
| * |
| * <p>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}. |
| * |
| * <p>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, |
| * <pre> {@code |
| * <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> |
| * } </pre> |
| * |
| * <p>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 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 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. |
| * |
| * <p>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. |
| * |
| * <p>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. |
| * |
| * <p>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. |
| * |
| * <p>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) { |
| IConnectivityManager cm = getService(); |
| String packageName = context.getPackageName(); |
| try { |
| // Only prepare if we're not already prepared. |
| int userId = context.getUserId(); |
| if (!cm.prepareVpn(packageName, null, userId)) { |
| cm.prepareVpn(null, packageName, userId); |
| } |
| cm.setVpnPackageAuthorization(packageName, userId, true); |
| } 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. |
| * |
| * <p class="note">The socket is NOT closed by this method. |
| * |
| * @return {@code true} on success. |
| */ |
| public boolean protect(int socket) { |
| return NetworkUtils.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 <b>DOES NOT</b> 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. |
| * |
| * <p>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). |
| * |
| * <p>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. |
| * |
| * <p>{@code networks} is one of the following: |
| * <ul> |
| * <li><strong>a non-empty array</strong>: an array of one or more {@link 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.</li> |
| * <li><strong>an empty array</strong>: a zero-element array, meaning that the VPN has no |
| * underlying network connection, and thus, app traffic will not be sent or received.</li> |
| * <li><strong>null</strong>: (default) signifies that the VPN uses whatever is the system's |
| * default network. I.e., it doesn't use the {@code bindSocket} or {@code bindDatagramSocket} |
| * APIs mentioned above to send traffic over specific channels.</li> |
| * </ul> |
| * |
| * <p>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()}. |
| * |
| * <p class="note">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<LinkAddress> mAddresses = new ArrayList<LinkAddress>(); |
| @UnsupportedAppUsage |
| private final List<RouteInfo> mRoutes = new ArrayList<RouteInfo>(); |
| |
| 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. |
| */ |
| @NonNull |
| public Builder setSession(@NonNull 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. |
| */ |
| @NonNull |
| public Builder setConfigureIntent(@NonNull 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. |
| */ |
| @NonNull |
| public Builder setMtu(int mtu) { |
| if (mtu <= 0) { |
| throw new IllegalArgumentException("Bad mtu"); |
| } |
| mConfig.mtu = mtu; |
| return this; |
| } |
| |
| /** |
| * Sets an HTTP proxy for the VPN network. This proxy is only a recommendation |
| * and it is possible that some apps will ignore it. |
| */ |
| @NonNull |
| public Builder setHttpProxy(@NonNull ProxyInfo proxyInfo) { |
| mConfig.proxyInfo = proxyInfo; |
| return this; |
| } |
| |
| /** |
| * 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}. |
| * |
| * Adding an address implicitly allows traffic from that address family |
| * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily |
| * |
| * @throws IllegalArgumentException if the address is invalid. |
| */ |
| @NonNull |
| public Builder addAddress(@NonNull InetAddress address, int prefixLength) { |
| check(address, prefixLength); |
| |
| if (address.isAnyLocalAddress()) { |
| throw new IllegalArgumentException("Bad address"); |
| } |
| mAddresses.add(new LinkAddress(address, prefixLength)); |
| mConfig.updateAllowedFamilies(address); |
| 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. |
| * |
| * Adding an address implicitly allows traffic from that address family |
| * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily |
| * |
| * @throws IllegalArgumentException if the address is invalid. |
| * @see #addAddress(InetAddress, int) |
| */ |
| @NonNull |
| public Builder addAddress(@NonNull 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. |
| * |
| * Adding a route implicitly allows traffic from that address family |
| * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily |
| * |
| * @throws IllegalArgumentException if the route is invalid. |
| */ |
| @NonNull |
| public Builder addRoute(@NonNull 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.add(new RouteInfo(new IpPrefix(address, prefixLength), null)); |
| mConfig.updateAllowedFamilies(address); |
| 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. |
| * |
| * Adding a route implicitly allows traffic from that address family |
| * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily |
| * |
| * @throws IllegalArgumentException if the route is invalid. |
| * @see #addRoute(InetAddress, int) |
| */ |
| @NonNull |
| public Builder addRoute(@NonNull 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. |
| * |
| * Adding a server implicitly allows traffic from that address family |
| * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily |
| * |
| * @throws IllegalArgumentException if the address is invalid. |
| */ |
| @NonNull |
| public Builder addDnsServer(@NonNull InetAddress address) { |
| if (address.isLoopbackAddress() || address.isAnyLocalAddress()) { |
| throw new IllegalArgumentException("Bad address"); |
| } |
| if (mConfig.dnsServers == null) { |
| mConfig.dnsServers = new ArrayList<String>(); |
| } |
| mConfig.dnsServers.add(address.getHostAddress()); |
| return this; |
| } |
| |
| /** |
| * Convenience method to add a DNS server to the VPN connection |
| * using a numeric address string. See {@link InetAddress} for the |
| * definitions of numeric address formats. |
| * |
| * Adding a server implicitly allows traffic from that address family |
| * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily |
| * |
| * @throws IllegalArgumentException if the address is invalid. |
| * @see #addDnsServer(InetAddress) |
| */ |
| @NonNull |
| public Builder addDnsServer(@NonNull String address) { |
| return addDnsServer(InetAddress.parseNumericAddress(address)); |
| } |
| |
| /** |
| * Add a search domain to the DNS resolver. |
| */ |
| @NonNull |
| public Builder addSearchDomain(@NonNull String domain) { |
| if (mConfig.searchDomains == null) { |
| mConfig.searchDomains = new ArrayList<String>(); |
| } |
| mConfig.searchDomains.add(domain); |
| return this; |
| } |
| |
| /** |
| * Allows traffic from the specified address family. |
| * |
| * By default, if no address, route or DNS server of a specific family (IPv4 or IPv6) is |
| * added to this VPN, then all outgoing traffic of that family is blocked. If any address, |
| * route or DNS server is added, that family is allowed. |
| * |
| * This method allows an address family to be unblocked even without adding an address, |
| * route or DNS server of that family. Traffic of that family will then typically |
| * fall-through to the underlying network if it's supported. |
| * |
| * {@code family} must be either {@code AF_INET} (for IPv4) or {@code AF_INET6} (for IPv6). |
| * {@link IllegalArgumentException} is thrown if it's neither. |
| * |
| * @param family The address family ({@code AF_INET} or {@code AF_INET6}) to allow. |
| * |
| * @return this {@link Builder} object to facilitate chaining of method calls. |
| */ |
| @NonNull |
| public Builder allowFamily(int family) { |
| if (family == AF_INET) { |
| mConfig.allowIPv4 = true; |
| } else if (family == AF_INET6) { |
| mConfig.allowIPv6 = true; |
| } else { |
| throw new IllegalArgumentException(family + " is neither " + AF_INET + " nor " + |
| AF_INET6); |
| } |
| return this; |
| } |
| |
| private void verifyApp(String packageName) throws PackageManager.NameNotFoundException { |
| IPackageManager pm = IPackageManager.Stub.asInterface( |
| ServiceManager.getService("package")); |
| try { |
| pm.getApplicationInfo(packageName, 0, UserHandle.getCallingUserId()); |
| } catch (RemoteException e) { |
| throw new IllegalStateException(e); |
| } |
| } |
| |
| /** |
| * Adds an application that's allowed to access the VPN connection. |
| * |
| * If this method is called at least once, only applications added through this method (and |
| * no others) are allowed access. Else (if this method is never called), all applications |
| * are allowed by default. If some applications are added, other, un-added applications |
| * will use networking as if the VPN wasn't running. |
| * |
| * A {@link Builder} may have only a set of allowed applications OR a set of disallowed |
| * ones, but not both. Calling this method after {@link #addDisallowedApplication} has |
| * already been called, or vice versa, will throw an {@link UnsupportedOperationException}. |
| * |
| * {@code packageName} must be the canonical name of a currently installed application. |
| * {@link PackageManager.NameNotFoundException} is thrown if there's no such application. |
| * |
| * @throws PackageManager.NameNotFoundException If the application isn't installed. |
| * |
| * @param packageName The full name (e.g.: "com.google.apps.contacts") of an application. |
| * |
| * @return this {@link Builder} object to facilitate chaining method calls. |
| */ |
| @NonNull |
| public Builder addAllowedApplication(@NonNull String packageName) |
| throws PackageManager.NameNotFoundException { |
| if (mConfig.disallowedApplications != null) { |
| throw new UnsupportedOperationException("addDisallowedApplication already called"); |
| } |
| verifyApp(packageName); |
| if (mConfig.allowedApplications == null) { |
| mConfig.allowedApplications = new ArrayList<String>(); |
| } |
| mConfig.allowedApplications.add(packageName); |
| return this; |
| } |
| |
| /** |
| * Adds an application that's denied access to the VPN connection. |
| * |
| * By default, all applications are allowed access, except for those denied through this |
| * method. Denied applications will use networking as if the VPN wasn't running. |
| * |
| * A {@link Builder} may have only a set of allowed applications OR a set of disallowed |
| * ones, but not both. Calling this method after {@link #addAllowedApplication} has already |
| * been called, or vice versa, will throw an {@link UnsupportedOperationException}. |
| * |
| * {@code packageName} must be the canonical name of a currently installed application. |
| * {@link PackageManager.NameNotFoundException} is thrown if there's no such application. |
| * |
| * @throws PackageManager.NameNotFoundException If the application isn't installed. |
| * |
| * @param packageName The full name (e.g.: "com.google.apps.contacts") of an application. |
| * |
| * @return this {@link Builder} object to facilitate chaining method calls. |
| */ |
| @NonNull |
| public Builder addDisallowedApplication(@NonNull String packageName) |
| throws PackageManager.NameNotFoundException { |
| if (mConfig.allowedApplications != null) { |
| throw new UnsupportedOperationException("addAllowedApplication already called"); |
| } |
| verifyApp(packageName); |
| if (mConfig.disallowedApplications == null) { |
| mConfig.disallowedApplications = new ArrayList<String>(); |
| } |
| mConfig.disallowedApplications.add(packageName); |
| return this; |
| } |
| |
| /** |
| * Allows all apps to bypass this VPN connection. |
| * |
| * By default, all traffic from apps is forwarded through the VPN interface and it is not |
| * possible for apps to side-step the VPN. If this method is called, apps may use methods |
| * such as {@link ConnectivityManager#bindProcessToNetwork} to instead send/receive |
| * directly over the underlying network or any other network they have permissions for. |
| * |
| * @return this {@link Builder} object to facilitate chaining of method calls. |
| */ |
| @NonNull |
| public Builder allowBypass() { |
| mConfig.allowBypass = true; |
| return this; |
| } |
| |
| /** |
| * Sets the VPN interface's file descriptor to be in blocking/non-blocking mode. |
| * |
| * By default, the file descriptor returned by {@link #establish} is non-blocking. |
| * |
| * @param blocking True to put the descriptor into blocking mode; false for non-blocking. |
| * |
| * @return this {@link Builder} object to facilitate chaining method calls. |
| */ |
| @NonNull |
| public Builder setBlocking(boolean blocking) { |
| mConfig.blocking = blocking; |
| return this; |
| } |
| |
| /** |
| * Sets the underlying networks used by the VPN for its upstream connections. |
| * |
| * @see VpnService#setUnderlyingNetworks |
| * |
| * @param networks An array of networks the VPN uses to tunnel traffic to/from its servers. |
| * |
| * @return this {@link Builder} object to facilitate chaining method calls. |
| */ |
| @NonNull |
| public Builder setUnderlyingNetworks(@Nullable Network[] networks) { |
| mConfig.underlyingNetworks = networks != null ? networks.clone() : null; |
| return this; |
| } |
| |
| /** |
| * Marks the VPN network as metered. A VPN network is classified as metered when the user is |
| * sensitive to heavy data usage due to monetary costs and/or data limitations. In such |
| * cases, you should set this to {@code true} so that apps on the system can avoid doing |
| * large data transfers. Otherwise, set this to {@code false}. Doing so would cause VPN |
| * network to inherit its meteredness from its underlying networks. |
| * |
| * <p>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(Networks[]) |
| * @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. |
| * |
| * <p>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. |
| * |
| * <p>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); |
| } |
| } |
| } |
| } |