Letting applications intercept packets raises huge security concerns. + * Besides, a VPN application can easily break the network, and two of them + * may conflict with each other. The framework takes several actions to + * address these issues. Here are some key points: + *
There are two primary methods in this class: {@link #prepare} and + * {@link #establish}. The former deals with the user action and stops + * the existing VPN connection created by another application. The latter + * creates a VPN interface using the parameters supplied to this builder. + * An application must call {@link #prepare} to grant the right to create + * an interface, and it can be revoked at any time by another application. + * The application got revoked is notified by an {@link #ACTION_VPN_REVOKED} + * broadcast. Here are the general steps to create a VPN connection: + *
Using this class requires + * {@link android.Manifest.permission#VPN} permission. + * @hide + */ +public class VpnBuilder { + + /** + * Broadcast intent action indicating that the VPN application has been + * revoked. This can be only received by the target application on the + * receiver explicitly registered using {@link Context#registerReceiver}. + * + *
This is a protected intent that can only be sent by the system. + */ + public static final String ACTION_VPN_REVOKED = VpnConfig.ACTION_VPN_REVOKED; + + /** + * Use IConnectivityManager instead 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 to the application through its + * {@link Activity#onActivityResult}. The application becomes prepared if + * the result is {@link Activity#RESULT_OK}, and it is granted to create a + * VPN interface by calling {@link #establish}. + * + *
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 by an {@link #ACTION_VPN_REVOKED}
+ * broadcast, and its VPN interface will be deactivated by the system.
+ * The application should then notify the remote server and disconnect
+ * gracefully. Unless the application becomes prepared again, subsequent
+ * calls to {@link #establish} will return {@code null}.
+ *
+ * @see #establish
+ * @see #ACTION_VPN_REVOKED
+ */
+ public static Intent prepare(Context context) {
+ try {
+ if (getService().prepareVpn(context.getPackageName(), null)) {
+ return null;
+ }
+ } catch (RemoteException e) {
+ // ignore
+ }
+ return VpnConfig.getIntentForConfirmation();
+ }
+
+ private VpnConfig mConfig = new VpnConfig();
+ private StringBuilder mAddresses = new StringBuilder();
+ private StringBuilder mRoutes = new StringBuilder();
+
+ /**
+ * Set the name of this session. It will be displayed in system-managed
+ * dialogs and notifications. This is recommended not required.
+ */
+ public VpnBuilder 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 VpnBuilder 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 VpnBuilder setMtu(int mtu) {
+ if (mtu <= 0) {
+ throw new IllegalArgumentException("Bad mtu");
+ }
+ mConfig.mtu = mtu;
+ return this;
+ }
+
+ /**
+ * 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");
+ }
+ }
+
+ /**
+ * 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 VpnBuilder addAddress(String address, int prefixLength) {
+ return addAddress(InetAddress.parseNumericAddress(address), prefixLength);
+ }
+
+ /**
+ * 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 VpnBuilder addAddress(InetAddress address, int prefixLength) {
+ check(address, prefixLength);
+
+ if (address.isAnyLocalAddress()) {
+ throw new IllegalArgumentException("Bad address");
+ }
+
+ mAddresses.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.
+ *
+ * @see #addRoute(InetAddress, int)
+ * @throws IllegalArgumentException if the route is invalid.
+ */
+ public VpnBuilder addRoute(String address, int prefixLength) {
+ return addRoute(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 VpnBuilder addRoute(InetAddress address, int prefixLength) {
+ check(address, prefixLength);
+
+ int offset = prefixLength / 8;
+ byte[] bytes = address.getAddress();
+ if (offset < bytes.length) {
+ if ((byte)(bytes[offset] << (prefixLength % 8)) != 0) {
+ throw new IllegalArgumentException("Bad address");
+ }
+ while (++offset < bytes.length) {
+ 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 DNS server to the VPN connection
+ * using a numeric address string. See {@link InetAddress} for the
+ * definitions of numeric address formats.
+ *
+ * @throws IllegalArgumentException if the address is invalid.
+ * @see #addDnsServer(InetAddress)
+ */
+ public VpnBuilder addDnsServer(String address) {
+ return addDnsServer(InetAddress.parseNumericAddress(address));
+ }
+
+ /**
+ * 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 VpnBuilder 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 configured 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 by another application. This helps solve
+ * possible race conditions while handling {@link #ACTION_VPN_REVOKED}
+ * broadcasts.
+ *
+ * @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.
+ * @see #prepare
+ */
+ public ParcelFileDescriptor establish() {
+ mConfig.addresses = mAddresses.toString();
+ mConfig.routes = mRoutes.toString();
+
+ try {
+ return getService().establishVpn(mConfig);
+ } catch (RemoteException e) {
+ throw new IllegalStateException(e);
+ }
+ }
+
+ /**
+ * 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.
+ *
+ * The socket is NOT closed by this method.
+ *
+ * @return {@code true} on success.
+ */
+ public static 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
+ }
+ }
+ }
+
+ /**
+ * Protect a {@link Socket} from VPN connections.
+ *
+ * @return {@code true} on success.
+ * @see #protect(int)
+ */
+ public static boolean protect(Socket socket) {
+ return protect(socket.getFileDescriptor$().getInt$());
+ }
+
+ /**
+ * Protect a {@link DatagramSocket} from VPN connections.
+ *
+ * @return {@code true} on success.
+ * @see #protect(int)
+ */
+ public static boolean protect(DatagramSocket socket) {
+ return protect(socket.getFileDescriptor$().getInt$());
+ }
+}