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