1 /* 2 * Copyright (C) 2011 The Android Open Source Project 3 * 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 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 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. 15 */ 16 17 package android.net; 18 19 import static android.system.OsConstants.AF_INET; 20 import static android.system.OsConstants.AF_INET6; 21 22 import android.app.Activity; 23 import android.app.PendingIntent; 24 import android.app.Service; 25 import android.content.Context; 26 import android.content.Intent; 27 import android.content.pm.IPackageManager; 28 import android.content.pm.PackageManager; 29 import android.net.NetworkUtils; 30 import android.os.Binder; 31 import android.os.IBinder; 32 import android.os.Parcel; 33 import android.os.ParcelFileDescriptor; 34 import android.os.RemoteException; 35 import android.os.ServiceManager; 36 import android.os.UserHandle; 37 38 import com.android.internal.net.VpnConfig; 39 40 import java.net.DatagramSocket; 41 import java.net.Inet4Address; 42 import java.net.Inet6Address; 43 import java.net.InetAddress; 44 import java.net.Socket; 45 import java.util.ArrayList; 46 import java.util.List; 47 48 /** 49 * VpnService is a base class for applications to extend and build their 50 * own VPN solutions. In general, it creates a virtual network interface, 51 * configures addresses and routing rules, and returns a file descriptor 52 * to the application. Each read from the descriptor retrieves an outgoing 53 * packet which was routed to the interface. Each write to the descriptor 54 * injects an incoming packet just like it was received from the interface. 55 * The interface is running on Internet Protocol (IP), so packets are 56 * always started with IP headers. The application then completes a VPN 57 * connection by processing and exchanging packets with the remote server 58 * over a tunnel. 59 * 60 * <p>Letting applications intercept packets raises huge security concerns. 61 * A VPN application can easily break the network. Besides, two of them may 62 * conflict with each other. The system takes several actions to address 63 * these issues. Here are some key points: 64 * <ul> 65 * <li>User action is required the first time an application creates a VPN 66 * connection.</li> 67 * <li>There can be only one VPN connection running at the same time. The 68 * existing interface is deactivated when a new one is created.</li> 69 * <li>A system-managed notification is shown during the lifetime of a 70 * VPN connection.</li> 71 * <li>A system-managed dialog gives the information of the current VPN 72 * connection. It also provides a button to disconnect.</li> 73 * <li>The network is restored automatically when the file descriptor is 74 * closed. It also covers the cases when a VPN application is crashed 75 * or killed by the system.</li> 76 * </ul> 77 * 78 * <p>There are two primary methods in this class: {@link #prepare} and 79 * {@link Builder#establish}. The former deals with user action and stops 80 * the VPN connection created by another application. The latter creates 81 * a VPN interface using the parameters supplied to the {@link Builder}. 82 * An application must call {@link #prepare} to grant the right to use 83 * other methods in this class, and the right can be revoked at any time. 84 * Here are the general steps to create a VPN connection: 85 * <ol> 86 * <li>When the user presses the button to connect, call {@link #prepare} 87 * and launch the returned intent, if non-null.</li> 88 * <li>When the application becomes prepared, start the service.</li> 89 * <li>Create a tunnel to the remote server and negotiate the network 90 * parameters for the VPN connection.</li> 91 * <li>Supply those parameters to a {@link Builder} and create a VPN 92 * interface by calling {@link Builder#establish}.</li> 93 * <li>Process and exchange packets between the tunnel and the returned 94 * file descriptor.</li> 95 * <li>When {@link #onRevoke} is invoked, close the file descriptor and 96 * shut down the tunnel gracefully.</li> 97 * </ol> 98 * 99 * <p>Services extended this class need to be declared with appropriate 100 * permission and intent filter. Their access must be secured by 101 * {@link android.Manifest.permission#BIND_VPN_SERVICE} permission, and 102 * their intent filter must match {@link #SERVICE_INTERFACE} action. Here 103 * is an example of declaring a VPN service in {@code AndroidManifest.xml}: 104 * <pre> 105 * <service android:name=".ExampleVpnService" 106 * android:permission="android.permission.BIND_VPN_SERVICE"> 107 * <intent-filter> 108 * <action android:name="android.net.VpnService"/> 109 * </intent-filter> 110 * </service></pre> 111 * 112 * @see Builder 113 */ 114 public class VpnService extends Service { 115 116 /** 117 * The action must be matched by the intent filter of this service. It also 118 * needs to require {@link android.Manifest.permission#BIND_VPN_SERVICE} 119 * permission so that other applications cannot abuse it. 120 */ 121 public static final String SERVICE_INTERFACE = VpnConfig.SERVICE_INTERFACE; 122 123 /** 124 * Use IConnectivityManager since those methods are hidden and not 125 * available in ConnectivityManager. 126 */ 127 private static IConnectivityManager getService() { 128 return IConnectivityManager.Stub.asInterface( 129 ServiceManager.getService(Context.CONNECTIVITY_SERVICE)); 130 } 131 132 /** 133 * Prepare to establish a VPN connection. This method returns {@code null} 134 * if the VPN application is already prepared or if the user has previously 135 * consented to the VPN application. Otherwise, it returns an 136 * {@link Intent} to a system activity. The application should launch the 137 * activity using {@link Activity#startActivityForResult} to get itself 138 * prepared. The activity may pop up a dialog to require user action, and 139 * the result will come back via its {@link Activity#onActivityResult}. 140 * If the result is {@link Activity#RESULT_OK}, the application becomes 141 * prepared and is granted to use other methods in this class. 142 * 143 * <p>Only one application can be granted at the same time. The right 144 * is revoked when another application is granted. The application 145 * losing the right will be notified via its {@link #onRevoke}. Unless 146 * it becomes prepared again, subsequent calls to other methods in this 147 * class will fail. 148 * 149 * <p>The user may disable the VPN at any time while it is activated, in 150 * which case this method will return an intent the next time it is 151 * executed to obtain the user's consent again. 152 * 153 * @see #onRevoke 154 */ 155 public static Intent prepare(Context context) { 156 try { 157 if (getService().prepareVpn(context.getPackageName(), null)) { 158 return null; 159 } 160 } catch (RemoteException e) { 161 // ignore 162 } 163 return VpnConfig.getIntentForConfirmation(); 164 } 165 166 /** 167 * Protect a socket from VPN connections. After protecting, data sent 168 * through this socket will go directly to the underlying network, 169 * so its traffic will not be forwarded through the VPN. 170 * This method is useful if some connections need to be kept 171 * outside of VPN. For example, a VPN tunnel should protect itself if its 172 * destination is covered by VPN routes. Otherwise its outgoing packets 173 * will be sent back to the VPN interface and cause an infinite loop. This 174 * method will fail if the application is not prepared or is revoked. 175 * 176 * <p class="note">The socket is NOT closed by this method. 177 * 178 * @return {@code true} on success. 179 */ 180 public boolean protect(int socket) { 181 return NetworkUtils.protectFromVpn(socket); 182 } 183 184 /** 185 * Convenience method to protect a {@link Socket} from VPN connections. 186 * 187 * @return {@code true} on success. 188 * @see #protect(int) 189 */ 190 public boolean protect(Socket socket) { 191 return protect(socket.getFileDescriptor$().getInt$()); 192 } 193 194 /** 195 * Convenience method to protect a {@link DatagramSocket} from VPN 196 * connections. 197 * 198 * @return {@code true} on success. 199 * @see #protect(int) 200 */ 201 public boolean protect(DatagramSocket socket) { 202 return protect(socket.getFileDescriptor$().getInt$()); 203 } 204 205 /** 206 * Adds a network address to the VPN interface. 207 * 208 * Both IPv4 and IPv6 addresses are supported. The VPN must already be established. Fails if the 209 * address is already in use or cannot be assigned to the interface for any other reason. 210 * 211 * Adding an address implicitly allows traffic from that address family (i.e., IPv4 or IPv6) to 212 * be routed over the VPN. @see Builder#allowFamily 213 * 214 * @throws {@link IllegalArgumentException} if the address is invalid. 215 * 216 * @param address The IP address (IPv4 or IPv6) to assign to the VPN interface. 217 * @param prefixLength The prefix length of the address. 218 * 219 * @return {@code true} on success. 220 * @see Builder#addAddress 221 * 222 * @hide 223 */ 224 public boolean addAddress(InetAddress address, int prefixLength) { 225 check(address, prefixLength); 226 try { 227 return getService().addVpnAddress(address.getHostAddress(), prefixLength); 228 } catch (RemoteException e) { 229 throw new IllegalStateException(e); 230 } 231 } 232 233 /** 234 * Removes a network address from the VPN interface. 235 * 236 * Both IPv4 and IPv6 addresses are supported. The VPN must already be established. Fails if the 237 * address is not assigned to the VPN interface, or if it is the only address assigned (thus 238 * cannot be removed), or if the address cannot be removed for any other reason. 239 * 240 * After removing an address, if there are no addresses, routes or DNS servers of a particular 241 * address family (i.e., IPv4 or IPv6) configured on the VPN, that <b>DOES NOT</b> block that 242 * family from being routed. In other words, once an address family has been allowed, it stays 243 * allowed for the rest of the VPN's session. @see Builder#allowFamily 244 * 245 * @throws {@link IllegalArgumentException} if the address is invalid. 246 * 247 * @param address The IP address (IPv4 or IPv6) to assign to the VPN interface. 248 * @param prefixLength The prefix length of the address. 249 * 250 * @return {@code true} on success. 251 * 252 * @hide 253 */ 254 public boolean removeAddress(InetAddress address, int prefixLength) { 255 check(address, prefixLength); 256 try { 257 return getService().removeVpnAddress(address.getHostAddress(), prefixLength); 258 } catch (RemoteException e) { 259 throw new IllegalStateException(e); 260 } 261 } 262 263 /** 264 * Return the communication interface to the service. This method returns 265 * {@code null} on {@link Intent}s other than {@link #SERVICE_INTERFACE} 266 * action. Applications overriding this method must identify the intent 267 * and return the corresponding interface accordingly. 268 * 269 * @see Service#onBind 270 */ 271 @Override 272 public IBinder onBind(Intent intent) { 273 if (intent != null && SERVICE_INTERFACE.equals(intent.getAction())) { 274 return new Callback(); 275 } 276 return null; 277 } 278 279 /** 280 * Invoked when the application is revoked. At this moment, the VPN 281 * interface is already deactivated by the system. The application should 282 * close the file descriptor and shut down gracefully. The default 283 * implementation of this method is calling {@link Service#stopSelf()}. 284 * 285 * <p class="note">Calls to this method may not happen on the main thread 286 * of the process. 287 * 288 * @see #prepare 289 */ 290 public void onRevoke() { 291 stopSelf(); 292 } 293 294 /** 295 * Use raw Binder instead of AIDL since now there is only one usage. 296 */ 297 private class Callback extends Binder { 298 @Override 299 protected boolean onTransact(int code, Parcel data, Parcel reply, int flags) { 300 if (code == IBinder.LAST_CALL_TRANSACTION) { 301 onRevoke(); 302 return true; 303 } 304 return false; 305 } 306 } 307 308 /** 309 * Private method to validate address and prefixLength. 310 */ 311 private static void check(InetAddress address, int prefixLength) { 312 if (address.isLoopbackAddress()) { 313 throw new IllegalArgumentException("Bad address"); 314 } 315 if (address instanceof Inet4Address) { 316 if (prefixLength < 0 || prefixLength > 32) { 317 throw new IllegalArgumentException("Bad prefixLength"); 318 } 319 } else if (address instanceof Inet6Address) { 320 if (prefixLength < 0 || prefixLength > 128) { 321 throw new IllegalArgumentException("Bad prefixLength"); 322 } 323 } else { 324 throw new IllegalArgumentException("Unsupported family"); 325 } 326 } 327 328 /** 329 * Helper class to create a VPN interface. This class should be always 330 * used within the scope of the outer {@link VpnService}. 331 * 332 * @see VpnService 333 */ 334 public class Builder { 335 336 private final VpnConfig mConfig = new VpnConfig(); 337 private final List<LinkAddress> mAddresses = new ArrayList<LinkAddress>(); 338 private final List<RouteInfo> mRoutes = new ArrayList<RouteInfo>(); 339 340 public Builder() { 341 mConfig.user = VpnService.this.getClass().getName(); 342 } 343 344 /** 345 * Set the name of this session. It will be displayed in 346 * system-managed dialogs and notifications. This is recommended 347 * not required. 348 */ 349 public Builder setSession(String session) { 350 mConfig.session = session; 351 return this; 352 } 353 354 /** 355 * Set the {@link PendingIntent} to an activity for users to 356 * configure the VPN connection. If it is not set, the button 357 * to configure will not be shown in system-managed dialogs. 358 */ 359 public Builder setConfigureIntent(PendingIntent intent) { 360 mConfig.configureIntent = intent; 361 return this; 362 } 363 364 /** 365 * Set the maximum transmission unit (MTU) of the VPN interface. If 366 * it is not set, the default value in the operating system will be 367 * used. 368 * 369 * @throws IllegalArgumentException if the value is not positive. 370 */ 371 public Builder setMtu(int mtu) { 372 if (mtu <= 0) { 373 throw new IllegalArgumentException("Bad mtu"); 374 } 375 mConfig.mtu = mtu; 376 return this; 377 } 378 379 /** 380 * Add a network address to the VPN interface. Both IPv4 and IPv6 381 * addresses are supported. At least one address must be set before 382 * calling {@link #establish}. 383 * 384 * Adding an address implicitly allows traffic from that address family 385 * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily 386 * 387 * @throws IllegalArgumentException if the address is invalid. 388 */ 389 public Builder addAddress(InetAddress address, int prefixLength) { 390 check(address, prefixLength); 391 392 if (address.isAnyLocalAddress()) { 393 throw new IllegalArgumentException("Bad address"); 394 } 395 mAddresses.add(new LinkAddress(address, prefixLength)); 396 mConfig.updateAllowedFamilies(address); 397 return this; 398 } 399 400 /** 401 * Convenience method to add a network address to the VPN interface 402 * using a numeric address string. See {@link InetAddress} for the 403 * definitions of numeric address formats. 404 * 405 * Adding an address implicitly allows traffic from that address family 406 * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily 407 * 408 * @throws IllegalArgumentException if the address is invalid. 409 * @see #addAddress(InetAddress, int) 410 */ 411 public Builder addAddress(String address, int prefixLength) { 412 return addAddress(InetAddress.parseNumericAddress(address), prefixLength); 413 } 414 415 /** 416 * Add a network route to the VPN interface. Both IPv4 and IPv6 417 * routes are supported. 418 * 419 * Adding a route implicitly allows traffic from that address family 420 * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily 421 * 422 * @throws IllegalArgumentException if the route is invalid. 423 */ 424 public Builder addRoute(InetAddress address, int prefixLength) { 425 check(address, prefixLength); 426 427 int offset = prefixLength / 8; 428 byte[] bytes = address.getAddress(); 429 if (offset < bytes.length) { 430 for (bytes[offset] <<= prefixLength % 8; offset < bytes.length; ++offset) { 431 if (bytes[offset] != 0) { 432 throw new IllegalArgumentException("Bad address"); 433 } 434 } 435 } 436 mRoutes.add(new RouteInfo(new LinkAddress(address, prefixLength), null)); 437 mConfig.updateAllowedFamilies(address); 438 return this; 439 } 440 441 /** 442 * Convenience method to add a network route to the VPN interface 443 * using a numeric address string. See {@link InetAddress} for the 444 * definitions of numeric address formats. 445 * 446 * Adding a route implicitly allows traffic from that address family 447 * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily 448 * 449 * @throws IllegalArgumentException if the route is invalid. 450 * @see #addRoute(InetAddress, int) 451 */ 452 public Builder addRoute(String address, int prefixLength) { 453 return addRoute(InetAddress.parseNumericAddress(address), prefixLength); 454 } 455 456 /** 457 * Add a DNS server to the VPN connection. Both IPv4 and IPv6 458 * addresses are supported. If none is set, the DNS servers of 459 * the default network will be used. 460 * 461 * Adding a server implicitly allows traffic from that address family 462 * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily 463 * 464 * @throws IllegalArgumentException if the address is invalid. 465 */ 466 public Builder addDnsServer(InetAddress address) { 467 if (address.isLoopbackAddress() || address.isAnyLocalAddress()) { 468 throw new IllegalArgumentException("Bad address"); 469 } 470 if (mConfig.dnsServers == null) { 471 mConfig.dnsServers = new ArrayList<String>(); 472 } 473 mConfig.dnsServers.add(address.getHostAddress()); 474 return this; 475 } 476 477 /** 478 * Convenience method to add a DNS server to the VPN connection 479 * using a numeric address string. See {@link InetAddress} for the 480 * definitions of numeric address formats. 481 * 482 * Adding a server implicitly allows traffic from that address family 483 * (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily 484 * 485 * @throws IllegalArgumentException if the address is invalid. 486 * @see #addDnsServer(InetAddress) 487 */ 488 public Builder addDnsServer(String address) { 489 return addDnsServer(InetAddress.parseNumericAddress(address)); 490 } 491 492 /** 493 * Add a search domain to the DNS resolver. 494 */ 495 public Builder addSearchDomain(String domain) { 496 if (mConfig.searchDomains == null) { 497 mConfig.searchDomains = new ArrayList<String>(); 498 } 499 mConfig.searchDomains.add(domain); 500 return this; 501 } 502 503 /** 504 * Allows traffic from the specified address family. 505 * 506 * By default, if no address, route or DNS server of a specific family (IPv4 or IPv6) is 507 * added to this VPN, then all outgoing traffic of that family is blocked. If any address, 508 * route or DNS server is added, that family is allowed. 509 * 510 * This method allows an address family to be unblocked even without adding an address, 511 * route or DNS server of that family. Traffic of that family will then typically 512 * fall-through to the underlying network if it's supported. 513 * 514 * {@code family} must be either {@code AF_INET} (for IPv4) or {@code AF_INET6} (for IPv6). 515 * {@link IllegalArgumentException} is thrown if it's neither. 516 * 517 * @param family The address family ({@code AF_INET} or {@code AF_INET6}) to allow. 518 * 519 * @return this {@link Builder} object to facilitate chaining of method calls. 520 */ 521 public Builder allowFamily(int family) { 522 if (family == AF_INET) { 523 mConfig.allowIPv4 = true; 524 } else if (family == AF_INET6) { 525 mConfig.allowIPv6 = true; 526 } else { 527 throw new IllegalArgumentException(family + " is neither " + AF_INET + " nor " + 528 AF_INET6); 529 } 530 return this; 531 } 532 533 private void verifyApp(String packageName) throws PackageManager.NameNotFoundException { 534 IPackageManager pm = IPackageManager.Stub.asInterface( 535 ServiceManager.getService("package")); 536 try { 537 pm.getApplicationInfo(packageName, 0, UserHandle.getCallingUserId()); 538 } catch (RemoteException e) { 539 throw new IllegalStateException(e); 540 } 541 } 542 543 /** 544 * Adds an application that's allowed to access the VPN connection. 545 * 546 * If this method is called at least once, only applications added through this method (and 547 * no others) are allowed access. Else (if this method is never called), all applications 548 * are allowed by default. If some applications are added, other, un-added applications 549 * will use networking as if the VPN wasn't running. 550 * 551 * A {@link Builder} may have only a set of allowed applications OR a set of disallowed 552 * ones, but not both. Calling this method after {@link #addDisallowedApplication} has 553 * already been called, or vice versa, will throw an {@link UnsupportedOperationException}. 554 * 555 * {@code packageName} must be the canonical name of a currently installed application. 556 * {@link PackageManager.NameNotFoundException} is thrown if there's no such application. 557 * 558 * @throws {@link PackageManager.NameNotFoundException} If the application isn't installed. 559 * 560 * @param packageName The full name (e.g.: "com.google.apps.contacts") of an application. 561 * 562 * @return this {@link Builder} object to facilitate chaining method calls. 563 */ 564 public Builder addAllowedApplication(String packageName) 565 throws PackageManager.NameNotFoundException { 566 if (mConfig.disallowedApplications != null) { 567 throw new UnsupportedOperationException("addDisallowedApplication already called"); 568 } 569 verifyApp(packageName); 570 if (mConfig.allowedApplications == null) { 571 mConfig.allowedApplications = new ArrayList<String>(); 572 } 573 mConfig.allowedApplications.add(packageName); 574 return this; 575 } 576 577 /** 578 * Adds an application that's denied access to the VPN connection. 579 * 580 * By default, all applications are allowed access, except for those denied through this 581 * method. Denied applications will use networking as if the VPN wasn't running. 582 * 583 * A {@link Builder} may have only a set of allowed applications OR a set of disallowed 584 * ones, but not both. Calling this method after {@link #addAllowedApplication} has already 585 * been called, or vice versa, will throw an {@link UnsupportedOperationException}. 586 * 587 * {@code packageName} must be the canonical name of a currently installed application. 588 * {@link PackageManager.NameNotFoundException} is thrown if there's no such application. 589 * 590 * @throws {@link PackageManager.NameNotFoundException} If the application isn't installed. 591 * 592 * @param packageName The full name (e.g.: "com.google.apps.contacts") of an application. 593 * 594 * @return this {@link Builder} object to facilitate chaining method calls. 595 */ 596 public Builder addDisallowedApplication(String packageName) 597 throws PackageManager.NameNotFoundException { 598 if (mConfig.allowedApplications != null) { 599 throw new UnsupportedOperationException("addAllowedApplication already called"); 600 } 601 verifyApp(packageName); 602 if (mConfig.disallowedApplications == null) { 603 mConfig.disallowedApplications = new ArrayList<String>(); 604 } 605 mConfig.disallowedApplications.add(packageName); 606 return this; 607 } 608 609 /** 610 * Allows all apps to bypass this VPN connection. 611 * 612 * By default, all traffic from apps is forwarded through the VPN interface and it is not 613 * possible for apps to side-step the VPN. If this method is called, apps may use methods 614 * such as {@link ConnectivityManager#setProcessDefaultNetwork} to instead send/receive 615 * directly over the underlying network or any other network they have permissions for. 616 * 617 * @return this {@link Builder} object to facilitate chaining of method calls. 618 */ 619 public Builder allowBypass() { 620 mConfig.allowBypass = true; 621 return this; 622 } 623 624 /** 625 * Sets the VPN interface's file descriptor to be in blocking/non-blocking mode. 626 * 627 * By default, the file descriptor returned by {@link #establish} is non-blocking. 628 * 629 * @param blocking True to put the descriptor into blocking mode; false for non-blocking. 630 * 631 * @return this {@link Builder} object to facilitate chaining method calls. 632 */ 633 public Builder setBlocking(boolean blocking) { 634 mConfig.blocking = blocking; 635 return this; 636 } 637 638 /** 639 * Create a VPN interface using the parameters supplied to this 640 * builder. The interface works on IP packets, and a file descriptor 641 * is returned for the application to access them. Each read 642 * retrieves an outgoing packet which was routed to the interface. 643 * Each write injects an incoming packet just like it was received 644 * from the interface. The file descriptor is put into non-blocking 645 * mode by default to avoid blocking Java threads. To use the file 646 * descriptor completely in native space, see 647 * {@link ParcelFileDescriptor#detachFd()}. The application MUST 648 * close the file descriptor when the VPN connection is terminated. 649 * The VPN interface will be removed and the network will be 650 * restored by the system automatically. 651 * 652 * <p>To avoid conflicts, there can be only one active VPN interface 653 * at the same time. Usually network parameters are never changed 654 * during the lifetime of a VPN connection. It is also common for an 655 * application to create a new file descriptor after closing the 656 * previous one. However, it is rare but not impossible to have two 657 * interfaces while performing a seamless handover. In this case, the 658 * old interface will be deactivated when the new one is created 659 * successfully. Both file descriptors are valid but now outgoing 660 * packets will be routed to the new interface. Therefore, after 661 * draining the old file descriptor, the application MUST close it 662 * and start using the new file descriptor. If the new interface 663 * cannot be created, the existing interface and its file descriptor 664 * remain untouched. 665 * 666 * <p>An exception will be thrown if the interface cannot be created 667 * for any reason. However, this method returns {@code null} if the 668 * application is not prepared or is revoked. This helps solve 669 * possible race conditions between other VPN applications. 670 * 671 * @return {@link ParcelFileDescriptor} of the VPN interface, or 672 * {@code null} if the application is not prepared. 673 * @throws IllegalArgumentException if a parameter is not accepted 674 * by the operating system. 675 * @throws IllegalStateException if a parameter cannot be applied 676 * by the operating system. 677 * @throws SecurityException if the service is not properly declared 678 * in {@code AndroidManifest.xml}. 679 * @see VpnService 680 */ 681 public ParcelFileDescriptor establish() { 682 mConfig.addresses = mAddresses; 683 mConfig.routes = mRoutes; 684 685 try { 686 return getService().establishVpn(mConfig); 687 } catch (RemoteException e) { 688 throw new IllegalStateException(e); 689 } 690 } 691 } 692 } 693