Merge "VPN: add VpnBuilder as the public API of user space VPN."

1 files changed, 413 insertions, 0 deletions

diff --git a/core/java/android/net/VpnBuilder.java b/core/java/android/net/VpnBuilder.java
new file mode 100644
index 0000000..4582523
--- /dev/null
+++ b/core/java/android/net/VpnBuilder.java
@@ -0,0 +1,413 @@
+/*
+ * 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 android.app.Activity;
+import android.app.PendingIntent;
+import android.content.Context;
+import android.content.Intent;
+import android.os.ParcelFileDescriptor;
+import android.os.RemoteException;
+import android.os.ServiceManager;
+
+import com.android.internal.net.VpnConfig;
+
+import java.net.InetAddress;
+import java.net.Inet4Address;
+import java.net.Inet6Address;
+import java.net.DatagramSocket;
+import java.net.Socket;
+import java.util.ArrayList;
+
+/**
+ * VpnBuilder is a framework which enables applications to 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 framework 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 a remote server
+ * over a secured tunnel.
+ *
+ * <p>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:
+ * <ul>
+ *   <li>User action is required to create 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 #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:
+ * <ol>
+ *   <li>When the user press the button to connect, call {@link #prepare}
+ *       and launch the intent if necessary.</li>
+ *   <li>Register a receiver for {@link #ACTION_VPN_REVOKED} broadcasts.
+ *   <li>Connect to the remote server and negotiate the network parameters
+ *       of the VPN connection.</li>
+ *   <li>Use those parameters to configure a VpnBuilder and create a VPN
+ *       interface by calling {@link #establish}.</li>
+ *   <li>Start processing packets between the returned file descriptor and
+ *       the VPN tunnel.</li>
+ *   <li>When an {@link #ACTION_VPN_REVOKED} broadcast is received, the
+ *       interface is already deactivated by the framework. Close the file
+ *       descriptor and shut down the VPN tunnel gracefully.
+ * </ol>
+ * Methods in this class can be used in activities and services. However,
+ * the intent returned from {@link #prepare} must be launched from an
+ * activity. The broadcast receiver can be registered at any time, but doing
+ * it before calling {@link #establish} effectively avoids race conditions.
+ *
+ * <p class="note">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}.
+     *
+     * <p>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}.
+     *
+     * <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 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<String>();
+        }
+        mConfig.dnsServers.add(address.getHostAddress());
+        return this;
+    }
+
+    /**
+     * Add a search domain to the DNS resolver.
+     */
+    public VpnBuilder addSearchDomain(String domain) {
+        if (mConfig.searchDomains == null) {
+            mConfig.searchDomains = new ArrayList<String>();
+        }
+        mConfig.searchDomains.add(domain);
+        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
+     * framework 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 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.
+     *
+     * <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 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.
+     *
+     * <p>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$());
+    }
+}