2 * Copyright (C) 2011 The Android Open Source Project
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
19 import static android.system.OsConstants.AF_INET;
20 import static android.system.OsConstants.AF_INET6;
22 import android.annotation.SystemApi;
23 import android.app.Activity;
24 import android.app.PendingIntent;
25 import android.app.Service;
26 import android.content.Context;
27 import android.content.Intent;
28 import android.content.pm.IPackageManager;
29 import android.content.pm.PackageManager;
30 import android.net.Network;
31 import android.net.NetworkUtils;
32 import android.os.Binder;
33 import android.os.IBinder;
34 import android.os.Parcel;
35 import android.os.ParcelFileDescriptor;
36 import android.os.RemoteException;
37 import android.os.ServiceManager;
38 import android.os.UserHandle;
40 import com.android.internal.net.VpnConfig;
42 import java.net.DatagramSocket;
43 import java.net.Inet4Address;
44 import java.net.Inet6Address;
45 import java.net.InetAddress;
46 import java.net.Socket;
47 import java.util.ArrayList;
48 import java.util.List;
51 * VpnService is a base class for applications to extend and build their
52 * own VPN solutions. In general, it creates a virtual network interface,
53 * configures addresses and routing rules, and returns a file descriptor
54 * to the application. Each read from the descriptor retrieves an outgoing
55 * packet which was routed to the interface. Each write to the descriptor
56 * injects an incoming packet just like it was received from the interface.
57 * The interface is running on Internet Protocol (IP), so packets are
58 * always started with IP headers. The application then completes a VPN
59 * connection by processing and exchanging packets with the remote server
62 * <p>Letting applications intercept packets raises huge security concerns.
63 * A VPN application can easily break the network. Besides, two of them may
64 * conflict with each other. The system takes several actions to address
65 * these issues. Here are some key points:
67 * <li>User action is required the first time an application creates a VPN
69 * <li>There can be only one VPN connection running at the same time. The
70 * existing interface is deactivated when a new one is created.</li>
71 * <li>A system-managed notification is shown during the lifetime of a
72 * VPN connection.</li>
73 * <li>A system-managed dialog gives the information of the current VPN
74 * connection. It also provides a button to disconnect.</li>
75 * <li>The network is restored automatically when the file descriptor is
76 * closed. It also covers the cases when a VPN application is crashed
77 * or killed by the system.</li>
80 * <p>There are two primary methods in this class: {@link #prepare} and
81 * {@link Builder#establish}. The former deals with user action and stops
82 * the VPN connection created by another application. The latter creates
83 * a VPN interface using the parameters supplied to the {@link Builder}.
84 * An application must call {@link #prepare} to grant the right to use
85 * other methods in this class, and the right can be revoked at any time.
86 * Here are the general steps to create a VPN connection:
88 * <li>When the user presses the button to connect, call {@link #prepare}
89 * and launch the returned intent, if non-null.</li>
90 * <li>When the application becomes prepared, start the service.</li>
91 * <li>Create a tunnel to the remote server and negotiate the network
92 * parameters for the VPN connection.</li>
93 * <li>Supply those parameters to a {@link Builder} and create a VPN
94 * interface by calling {@link Builder#establish}.</li>
95 * <li>Process and exchange packets between the tunnel and the returned
96 * file descriptor.</li>
97 * <li>When {@link #onRevoke} is invoked, close the file descriptor and
98 * shut down the tunnel gracefully.</li>
101 * <p>Services extended this class need to be declared with appropriate
102 * permission and intent filter. Their access must be secured by
103 * {@link android.Manifest.permission#BIND_VPN_SERVICE} permission, and
104 * their intent filter must match {@link #SERVICE_INTERFACE} action. Here
105 * is an example of declaring a VPN service in {@code AndroidManifest.xml}:
107 * <service android:name=".ExampleVpnService"
108 * android:permission="android.permission.BIND_VPN_SERVICE">
109 * <intent-filter>
110 * <action android:name="android.net.VpnService"/>
111 * </intent-filter>
112 * </service></pre>
116 public class VpnService extends Service {
119 * The action must be matched by the intent filter of this service. It also
120 * needs to require {@link android.Manifest.permission#BIND_VPN_SERVICE}
121 * permission so that other applications cannot abuse it.
123 public static final String SERVICE_INTERFACE = VpnConfig.SERVICE_INTERFACE;
126 * Use IConnectivityManager since those methods are hidden and not
127 * available in ConnectivityManager.
129 private static IConnectivityManager getService() {
130 return IConnectivityManager.Stub.asInterface(
131 ServiceManager.getService(Context.CONNECTIVITY_SERVICE));
135 * Prepare to establish a VPN connection. This method returns {@code null}
136 * if the VPN application is already prepared or if the user has previously
137 * consented to the VPN application. Otherwise, it returns an
138 * {@link Intent} to a system activity. The application should launch the
139 * activity using {@link Activity#startActivityForResult} to get itself
140 * prepared. The activity may pop up a dialog to require user action, and
141 * the result will come back via its {@link Activity#onActivityResult}.
142 * If the result is {@link Activity#RESULT_OK}, the application becomes
143 * prepared and is granted to use other methods in this class.
145 * <p>Only one application can be granted at the same time. The right
146 * is revoked when another application is granted. The application
147 * losing the right will be notified via its {@link #onRevoke}. Unless
148 * it becomes prepared again, subsequent calls to other methods in this
151 * <p>The user may disable the VPN at any time while it is activated, in
152 * which case this method will return an intent the next time it is
153 * executed to obtain the user's consent again.
157 public static Intent prepare(Context context) {
159 if (getService().prepareVpn(context.getPackageName(), null, UserHandle.myUserId())) {
162 } catch (RemoteException e) {
165 return VpnConfig.getIntentForConfirmation();
169 * Version of {@link #prepare(Context)} which does not require user consent.
171 * <p>Requires {@link android.Manifest.permission#CONTROL_VPN} and should generally not be
172 * used. Only acceptable in situations where user consent has been obtained through other means.
174 * <p>Once this is run, future preparations may be done with the standard prepare method as this
175 * will authorize the package to prepare the VPN without consent in the future.
180 public static void prepareAndAuthorize(Context context) {
181 IConnectivityManager cm = getService();
182 String packageName = context.getPackageName();
184 // Only prepare if we're not already prepared.
185 int userId = UserHandle.myUserId();
186 if (!cm.prepareVpn(packageName, null, userId)) {
187 cm.prepareVpn(null, packageName, userId);
189 cm.setVpnPackageAuthorization(packageName, userId, true);
190 } catch (RemoteException e) {
196 * Protect a socket from VPN connections. After protecting, data sent
197 * through this socket will go directly to the underlying network,
198 * so its traffic will not be forwarded through the VPN.
199 * This method is useful if some connections need to be kept
200 * outside of VPN. For example, a VPN tunnel should protect itself if its
201 * destination is covered by VPN routes. Otherwise its outgoing packets
202 * will be sent back to the VPN interface and cause an infinite loop. This
203 * method will fail if the application is not prepared or is revoked.
205 * <p class="note">The socket is NOT closed by this method.
207 * @return {@code true} on success.
209 public boolean protect(int socket) {
210 return NetworkUtils.protectFromVpn(socket);
214 * Convenience method to protect a {@link Socket} from VPN connections.
216 * @return {@code true} on success.
219 public boolean protect(Socket socket) {
220 return protect(socket.getFileDescriptor$().getInt$());
224 * Convenience method to protect a {@link DatagramSocket} from VPN
227 * @return {@code true} on success.
230 public boolean protect(DatagramSocket socket) {
231 return protect(socket.getFileDescriptor$().getInt$());
235 * Adds a network address to the VPN interface.
237 * Both IPv4 and IPv6 addresses are supported. The VPN must already be established. Fails if the
238 * address is already in use or cannot be assigned to the interface for any other reason.
240 * Adding an address implicitly allows traffic from that address family (i.e., IPv4 or IPv6) to
241 * be routed over the VPN. @see Builder#allowFamily
243 * @throws IllegalArgumentException if the address is invalid.
245 * @param address The IP address (IPv4 or IPv6) to assign to the VPN interface.
246 * @param prefixLength The prefix length of the address.
248 * @return {@code true} on success.
249 * @see Builder#addAddress
253 public boolean addAddress(InetAddress address, int prefixLength) {
254 check(address, prefixLength);
256 return getService().addVpnAddress(address.getHostAddress(), prefixLength);
257 } catch (RemoteException e) {
258 throw new IllegalStateException(e);
263 * Removes a network address from the VPN interface.
265 * Both IPv4 and IPv6 addresses are supported. The VPN must already be established. Fails if the
266 * address is not assigned to the VPN interface, or if it is the only address assigned (thus
267 * cannot be removed), or if the address cannot be removed for any other reason.
269 * After removing an address, if there are no addresses, routes or DNS servers of a particular
270 * address family (i.e., IPv4 or IPv6) configured on the VPN, that <b>DOES NOT</b> block that
271 * family from being routed. In other words, once an address family has been allowed, it stays
272 * allowed for the rest of the VPN's session. @see Builder#allowFamily
274 * @throws IllegalArgumentException if the address is invalid.
276 * @param address The IP address (IPv4 or IPv6) to assign to the VPN interface.
277 * @param prefixLength The prefix length of the address.
279 * @return {@code true} on success.
283 public boolean removeAddress(InetAddress address, int prefixLength) {
284 check(address, prefixLength);
286 return getService().removeVpnAddress(address.getHostAddress(), prefixLength);
287 } catch (RemoteException e) {
288 throw new IllegalStateException(e);
293 * Sets the underlying networks used by the VPN for its upstream connections.
295 * <p>Used by the system to know the actual networks that carry traffic for apps affected by
296 * this VPN in order to present this information to the user (e.g., via status bar icons).
298 * <p>This method only needs to be called if the VPN has explicitly bound its underlying
299 * communications channels — such as the socket(s) passed to {@link #protect(int)} —
300 * to a {@code Network} using APIs such as {@link Network#bindSocket(Socket)} or
301 * {@link Network#bindSocket(DatagramSocket)}. The VPN should call this method every time
302 * the set of {@code Network}s it is using changes.
304 * <p>{@code networks} is one of the following:
306 * <li><strong>a non-empty array</strong>: an array of one or more {@link Network}s, in
307 * decreasing preference order. For example, if this VPN uses both wifi and mobile (cellular)
308 * networks to carry app traffic, but prefers or uses wifi more than mobile, wifi should appear
309 * first in the array.</li>
310 * <li><strong>an empty array</strong>: a zero-element array, meaning that the VPN has no
311 * underlying network connection, and thus, app traffic will not be sent or received.</li>
312 * <li><strong>null</strong>: (default) signifies that the VPN uses whatever is the system's
313 * default network. I.e., it doesn't use the {@code bindSocket} or {@code bindDatagramSocket}
314 * APIs mentioned above to send traffic over specific channels.</li>
317 * <p>This call will succeed only if the VPN is currently established. For setting this value
318 * when the VPN has not yet been established, see {@link Builder#setUnderlyingNetworks}.
320 * @param networks An array of networks the VPN uses to tunnel traffic to/from its servers.
322 * @return {@code true} on success.
324 public boolean setUnderlyingNetworks(Network[] networks) {
326 return getService().setUnderlyingNetworksForVpn(networks);
327 } catch (RemoteException e) {
328 throw new IllegalStateException(e);
333 * Return the communication interface to the service. This method returns
334 * {@code null} on {@link Intent}s other than {@link #SERVICE_INTERFACE}
335 * action. Applications overriding this method must identify the intent
336 * and return the corresponding interface accordingly.
338 * @see Service#onBind
341 public IBinder onBind(Intent intent) {
342 if (intent != null && SERVICE_INTERFACE.equals(intent.getAction())) {
343 return new Callback();
349 * Invoked when the application is revoked. At this moment, the VPN
350 * interface is already deactivated by the system. The application should
351 * close the file descriptor and shut down gracefully. The default
352 * implementation of this method is calling {@link Service#stopSelf()}.
354 * <p class="note">Calls to this method may not happen on the main thread
359 public void onRevoke() {
364 * Use raw Binder instead of AIDL since now there is only one usage.
366 private class Callback extends Binder {
368 protected boolean onTransact(int code, Parcel data, Parcel reply, int flags) {
369 if (code == IBinder.LAST_CALL_TRANSACTION) {
378 * Private method to validate address and prefixLength.
380 private static void check(InetAddress address, int prefixLength) {
381 if (address.isLoopbackAddress()) {
382 throw new IllegalArgumentException("Bad address");
384 if (address instanceof Inet4Address) {
385 if (prefixLength < 0 || prefixLength > 32) {
386 throw new IllegalArgumentException("Bad prefixLength");
388 } else if (address instanceof Inet6Address) {
389 if (prefixLength < 0 || prefixLength > 128) {
390 throw new IllegalArgumentException("Bad prefixLength");
393 throw new IllegalArgumentException("Unsupported family");
398 * Helper class to create a VPN interface. This class should be always
399 * used within the scope of the outer {@link VpnService}.
403 public class Builder {
405 private final VpnConfig mConfig = new VpnConfig();
406 private final List<LinkAddress> mAddresses = new ArrayList<LinkAddress>();
407 private final List<RouteInfo> mRoutes = new ArrayList<RouteInfo>();
410 mConfig.user = VpnService.this.getClass().getName();
414 * Set the name of this session. It will be displayed in
415 * system-managed dialogs and notifications. This is recommended
418 public Builder setSession(String session) {
419 mConfig.session = session;
424 * Set the {@link PendingIntent} to an activity for users to
425 * configure the VPN connection. If it is not set, the button
426 * to configure will not be shown in system-managed dialogs.
428 public Builder setConfigureIntent(PendingIntent intent) {
429 mConfig.configureIntent = intent;
434 * Set the maximum transmission unit (MTU) of the VPN interface. If
435 * it is not set, the default value in the operating system will be
438 * @throws IllegalArgumentException if the value is not positive.
440 public Builder setMtu(int mtu) {
442 throw new IllegalArgumentException("Bad mtu");
449 * Add a network address to the VPN interface. Both IPv4 and IPv6
450 * addresses are supported. At least one address must be set before
451 * calling {@link #establish}.
453 * Adding an address implicitly allows traffic from that address family
454 * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily
456 * @throws IllegalArgumentException if the address is invalid.
458 public Builder addAddress(InetAddress address, int prefixLength) {
459 check(address, prefixLength);
461 if (address.isAnyLocalAddress()) {
462 throw new IllegalArgumentException("Bad address");
464 mAddresses.add(new LinkAddress(address, prefixLength));
465 mConfig.updateAllowedFamilies(address);
470 * Convenience method to add a network address to the VPN interface
471 * using a numeric address string. See {@link InetAddress} for the
472 * definitions of numeric address formats.
474 * Adding an address implicitly allows traffic from that address family
475 * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily
477 * @throws IllegalArgumentException if the address is invalid.
478 * @see #addAddress(InetAddress, int)
480 public Builder addAddress(String address, int prefixLength) {
481 return addAddress(InetAddress.parseNumericAddress(address), prefixLength);
485 * Add a network route to the VPN interface. Both IPv4 and IPv6
486 * routes are supported.
488 * Adding a route implicitly allows traffic from that address family
489 * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily
491 * @throws IllegalArgumentException if the route is invalid.
493 public Builder addRoute(InetAddress address, int prefixLength) {
494 check(address, prefixLength);
496 int offset = prefixLength / 8;
497 byte[] bytes = address.getAddress();
498 if (offset < bytes.length) {
499 for (bytes[offset] <<= prefixLength % 8; offset < bytes.length; ++offset) {
500 if (bytes[offset] != 0) {
501 throw new IllegalArgumentException("Bad address");
505 mRoutes.add(new RouteInfo(new IpPrefix(address, prefixLength), null));
506 mConfig.updateAllowedFamilies(address);
511 * Convenience method to add a network route to the VPN interface
512 * using a numeric address string. See {@link InetAddress} for the
513 * definitions of numeric address formats.
515 * Adding a route implicitly allows traffic from that address family
516 * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily
518 * @throws IllegalArgumentException if the route is invalid.
519 * @see #addRoute(InetAddress, int)
521 public Builder addRoute(String address, int prefixLength) {
522 return addRoute(InetAddress.parseNumericAddress(address), prefixLength);
526 * Add a DNS server to the VPN connection. Both IPv4 and IPv6
527 * addresses are supported. If none is set, the DNS servers of
528 * the default network will be used.
530 * Adding a server implicitly allows traffic from that address family
531 * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily
533 * @throws IllegalArgumentException if the address is invalid.
535 public Builder addDnsServer(InetAddress address) {
536 if (address.isLoopbackAddress() || address.isAnyLocalAddress()) {
537 throw new IllegalArgumentException("Bad address");
539 if (mConfig.dnsServers == null) {
540 mConfig.dnsServers = new ArrayList<String>();
542 mConfig.dnsServers.add(address.getHostAddress());
547 * Convenience method to add a DNS server to the VPN connection
548 * using a numeric address string. See {@link InetAddress} for the
549 * definitions of numeric address formats.
551 * Adding a server implicitly allows traffic from that address family
552 * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily
554 * @throws IllegalArgumentException if the address is invalid.
555 * @see #addDnsServer(InetAddress)
557 public Builder addDnsServer(String address) {
558 return addDnsServer(InetAddress.parseNumericAddress(address));
562 * Add a search domain to the DNS resolver.
564 public Builder addSearchDomain(String domain) {
565 if (mConfig.searchDomains == null) {
566 mConfig.searchDomains = new ArrayList<String>();
568 mConfig.searchDomains.add(domain);
573 * Allows traffic from the specified address family.
575 * By default, if no address, route or DNS server of a specific family (IPv4 or IPv6) is
576 * added to this VPN, then all outgoing traffic of that family is blocked. If any address,
577 * route or DNS server is added, that family is allowed.
579 * This method allows an address family to be unblocked even without adding an address,
580 * route or DNS server of that family. Traffic of that family will then typically
581 * fall-through to the underlying network if it's supported.
583 * {@code family} must be either {@code AF_INET} (for IPv4) or {@code AF_INET6} (for IPv6).
584 * {@link IllegalArgumentException} is thrown if it's neither.
586 * @param family The address family ({@code AF_INET} or {@code AF_INET6}) to allow.
588 * @return this {@link Builder} object to facilitate chaining of method calls.
590 public Builder allowFamily(int family) {
591 if (family == AF_INET) {
592 mConfig.allowIPv4 = true;
593 } else if (family == AF_INET6) {
594 mConfig.allowIPv6 = true;
596 throw new IllegalArgumentException(family + " is neither " + AF_INET + " nor " +
602 private void verifyApp(String packageName) throws PackageManager.NameNotFoundException {
603 IPackageManager pm = IPackageManager.Stub.asInterface(
604 ServiceManager.getService("package"));
606 pm.getApplicationInfo(packageName, 0, UserHandle.getCallingUserId());
607 } catch (RemoteException e) {
608 throw new IllegalStateException(e);
613 * Adds an application that's allowed to access the VPN connection.
615 * If this method is called at least once, only applications added through this method (and
616 * no others) are allowed access. Else (if this method is never called), all applications
617 * are allowed by default. If some applications are added, other, un-added applications
618 * will use networking as if the VPN wasn't running.
620 * A {@link Builder} may have only a set of allowed applications OR a set of disallowed
621 * ones, but not both. Calling this method after {@link #addDisallowedApplication} has
622 * already been called, or vice versa, will throw an {@link UnsupportedOperationException}.
624 * {@code packageName} must be the canonical name of a currently installed application.
625 * {@link PackageManager.NameNotFoundException} is thrown if there's no such application.
627 * @throws PackageManager.NameNotFoundException If the application isn't installed.
629 * @param packageName The full name (e.g.: "com.google.apps.contacts") of an application.
631 * @return this {@link Builder} object to facilitate chaining method calls.
633 public Builder addAllowedApplication(String packageName)
634 throws PackageManager.NameNotFoundException {
635 if (mConfig.disallowedApplications != null) {
636 throw new UnsupportedOperationException("addDisallowedApplication already called");
638 verifyApp(packageName);
639 if (mConfig.allowedApplications == null) {
640 mConfig.allowedApplications = new ArrayList<String>();
642 mConfig.allowedApplications.add(packageName);
647 * Adds an application that's denied access to the VPN connection.
649 * By default, all applications are allowed access, except for those denied through this
650 * method. Denied applications will use networking as if the VPN wasn't running.
652 * A {@link Builder} may have only a set of allowed applications OR a set of disallowed
653 * ones, but not both. Calling this method after {@link #addAllowedApplication} has already
654 * been called, or vice versa, will throw an {@link UnsupportedOperationException}.
656 * {@code packageName} must be the canonical name of a currently installed application.
657 * {@link PackageManager.NameNotFoundException} is thrown if there's no such application.
659 * @throws PackageManager.NameNotFoundException If the application isn't installed.
661 * @param packageName The full name (e.g.: "com.google.apps.contacts") of an application.
663 * @return this {@link Builder} object to facilitate chaining method calls.
665 public Builder addDisallowedApplication(String packageName)
666 throws PackageManager.NameNotFoundException {
667 if (mConfig.allowedApplications != null) {
668 throw new UnsupportedOperationException("addAllowedApplication already called");
670 verifyApp(packageName);
671 if (mConfig.disallowedApplications == null) {
672 mConfig.disallowedApplications = new ArrayList<String>();
674 mConfig.disallowedApplications.add(packageName);
679 * Allows all apps to bypass this VPN connection.
681 * By default, all traffic from apps is forwarded through the VPN interface and it is not
682 * possible for apps to side-step the VPN. If this method is called, apps may use methods
683 * such as {@link ConnectivityManager#bindProcessToNetwork} to instead send/receive
684 * directly over the underlying network or any other network they have permissions for.
686 * @return this {@link Builder} object to facilitate chaining of method calls.
688 public Builder allowBypass() {
689 mConfig.allowBypass = true;
694 * Sets the VPN interface's file descriptor to be in blocking/non-blocking mode.
696 * By default, the file descriptor returned by {@link #establish} is non-blocking.
698 * @param blocking True to put the descriptor into blocking mode; false for non-blocking.
700 * @return this {@link Builder} object to facilitate chaining method calls.
702 public Builder setBlocking(boolean blocking) {
703 mConfig.blocking = blocking;
708 * Sets the underlying networks used by the VPN for its upstream connections.
710 * @see VpnService#setUnderlyingNetworks
712 * @param networks An array of networks the VPN uses to tunnel traffic to/from its servers.
714 * @return this {@link Builder} object to facilitate chaining method calls.
716 public Builder setUnderlyingNetworks(Network[] networks) {
717 mConfig.underlyingNetworks = networks != null ? networks.clone() : null;
722 * Create a VPN interface using the parameters supplied to this
723 * builder. The interface works on IP packets, and a file descriptor
724 * is returned for the application to access them. Each read
725 * retrieves an outgoing packet which was routed to the interface.
726 * Each write injects an incoming packet just like it was received
727 * from the interface. The file descriptor is put into non-blocking
728 * mode by default to avoid blocking Java threads. To use the file
729 * descriptor completely in native space, see
730 * {@link ParcelFileDescriptor#detachFd()}. The application MUST
731 * close the file descriptor when the VPN connection is terminated.
732 * The VPN interface will be removed and the network will be
733 * restored by the system automatically.
735 * <p>To avoid conflicts, there can be only one active VPN interface
736 * at the same time. Usually network parameters are never changed
737 * during the lifetime of a VPN connection. It is also common for an
738 * application to create a new file descriptor after closing the
739 * previous one. However, it is rare but not impossible to have two
740 * interfaces while performing a seamless handover. In this case, the
741 * old interface will be deactivated when the new one is created
742 * successfully. Both file descriptors are valid but now outgoing
743 * packets will be routed to the new interface. Therefore, after
744 * draining the old file descriptor, the application MUST close it
745 * and start using the new file descriptor. If the new interface
746 * cannot be created, the existing interface and its file descriptor
749 * <p>An exception will be thrown if the interface cannot be created
750 * for any reason. However, this method returns {@code null} if the
751 * application is not prepared or is revoked. This helps solve
752 * possible race conditions between other VPN applications.
754 * @return {@link ParcelFileDescriptor} of the VPN interface, or
755 * {@code null} if the application is not prepared.
756 * @throws IllegalArgumentException if a parameter is not accepted
757 * by the operating system.
758 * @throws IllegalStateException if a parameter cannot be applied
759 * by the operating system.
760 * @throws SecurityException if the service is not properly declared
761 * in {@code AndroidManifest.xml}.
764 public ParcelFileDescriptor establish() {
765 mConfig.addresses = mAddresses;
766 mConfig.routes = mRoutes;
769 return getService().establishVpn(mConfig);
770 } catch (RemoteException e) {
771 throw new IllegalStateException(e);