Update VpnService API documentation.
The goal of blocking an address family by default is to prevent unintended
security holes. For example, a VPN that only deals with IPv4 doesn't know or
care about IPv6 at all, so it doesn't do anything for IPv6. An app shouldn't be
able to get around (bypass) the VPN by using IPv6.
Therefore, it is not necessary to block an address family in removeAddress().
The VPN was clearly aware of the address family (since it had configured such an
address before), so if it wants to block that family, it should add a default
route for that family and explicitly drop/block/reject those packets.
Bug: 15972465
Bug: 15409819
Change-Id: I845426fa90dc2358d3e11bc601db0b4bd5d3b7ac
diff --git a/core/java/android/net/VpnService.java b/core/java/android/net/VpnService.java
index 1d89eae..e9de79d 100644
--- a/core/java/android/net/VpnService.java
+++ b/core/java/android/net/VpnService.java
@@ -199,6 +199,9 @@
* Both IPv4 and IPv6 addresses are supported. The VPN must already be established. Fails if the
* address is already in use or cannot be assigned to the interface for any other reason.
*
+ * Adding an address implicitly allows traffic from that address family (i.e., IPv4 or IPv6) to
+ * be routed over the VPN. @see Builder#allowFamily
+ *
* @throws {@link IllegalArgumentException} if the address is invalid.
*
* @param address The IP address (IPv4 or IPv6) to assign to the VPN interface.
@@ -219,6 +222,11 @@
* address is not assigned to the VPN interface, or if it is the only address assigned (thus
* cannot be removed), or if the address cannot be removed for any other reason.
*
+ * After removing an address, if there are no addresses, routes or DNS servers of a particular
+ * address family (i.e., IPv4 or IPv6) configured on the VPN, that <b>DOES NOT</b> block that
+ * family from being routed. In other words, once an address family has been allowed, it stays
+ * allowed for the rest of the VPN's session. @see Builder#allowFamily
+ *
* @throws {@link IllegalArgumentException} if the address is invalid.
*
* @param address The IP address (IPv4 or IPv6) to assign to the VPN interface.