Document that WebView doesn't honor "uses cleartext traffic" flag.

Bug: 19215516
Change-Id: I5dbbaa03f3cae007c0b9b68fcf8cc8f250c16a62

4 files changed, 26 insertions, 16 deletions

diff --git a/core/java/android/content/pm/ApplicationInfo.java b/core/java/android/content/pm/ApplicationInfo.java
index e2701ee..6c32873 100644
--- a/core/java/android/content/pm/ApplicationInfo.java
+++ b/core/java/android/content/pm/ApplicationInfo.java
@@ -339,8 +339,14 @@ public class ApplicationInfo extends PackageItemInfo implements Parcelable {
      * (e.g., HTTP rather than HTTPS; WebSockets rather than WebSockets Secure; XMPP, IMAP, STMP
      * without STARTTLS or TLS). If {@code false}, the app declares that it does not intend to use
      * cleartext network traffic, in which case platform components (e.g., HTTP stacks,
-     * {@code WebView}, {@code DownloadManager}, {@code MediaPlayer}) will refuse app's requests to
-     * use cleartext traffic. Third-party libraries are encouraged to honor this flag as well.
+     * {@code DownloadManager}, {@code MediaPlayer}) will refuse app's requests to use cleartext
+     * traffic. Third-party libraries are encouraged to honor this flag as well.
+     *
+     * <p>NOTE: {@code WebView} does not honor this flag.
+     *
+     * <p>This flag comes from
+     * {@link android.R.styleable#AndroidManifestApplication_usesCleartextTraffic
+     * android:usesCleartextTraffic} of the &lt;application&gt; tag.
      */
     public static final int FLAG_USES_CLEARTEXT_TRAFFIC = 1<<27;
 
diff --git a/core/java/android/security/NetworkSecurityPolicy.java b/core/java/android/security/NetworkSecurityPolicy.java
index 70cd388..7e87717 100644
--- a/core/java/android/security/NetworkSecurityPolicy.java
+++ b/core/java/android/security/NetworkSecurityPolicy.java
@@ -46,9 +46,9 @@ public class NetworkSecurityPolicy {
      * without TLS or STARTTLS) is permitted for this process.
      *
      * <p>When cleartext network traffic is not permitted, the platform's components (e.g. HTTP and
-     * FTP stacks, {@link android.webkit.WebView}, {@link android.app.DownloadManager},
-     * {@link android.media.MediaPlayer}) will refuse this process's requests to use cleartext
-     * traffic. Third-party libraries are strongly encouraged to honor this setting as well.
+     * FTP stacks, {@link android.app.DownloadManager}, {@link android.media.MediaPlayer}) will
+     * refuse this process's requests to use cleartext traffic. Third-party libraries are strongly
+     * encouraged to honor this setting as well.
      *
      * <p>This flag is honored on a best effort basis because it's impossible to prevent all
      * cleartext traffic from Android applications given the level of access provided to them. For
@@ -56,6 +56,8 @@ public class NetworkSecurityPolicy {
      * because it cannot determine whether its traffic is in cleartext. However, most network
      * traffic from applications is handled by higher-level network stacks/components which can
      * honor this aspect of the policy.
+     *
+     * <p>NOTE: {@link android.webkit.WebView} does not honor this flag.
      */
     public boolean isCleartextTrafficPermitted() {
         return libcore.net.NetworkSecurityPolicy.isCleartextTrafficPermitted();
diff --git a/core/res/res/values/attrs_manifest.xml b/core/res/res/values/attrs_manifest.xml
index 12d7e60..0c685e0 100644
--- a/core/res/res/values/attrs_manifest.xml
+++ b/core/res/res/values/attrs_manifest.xml
@@ -393,8 +393,9 @@
          WebSockets rather than WebSockets Secure; XMPP, IMAP, STMP without STARTTLS or TLS.
          Defaults to true. If set to false {@code false}, the application declares that it does not
          intend to use cleartext network traffic, in which case platform components (e.g. HTTP
-         stacks, {@code WebView}, {@code MediaPlayer}) will refuse applications's requests to use
-         cleartext traffic. Third-party libraries are encouraged to honor this flag as well. -->
+         stacks, {@code DownloadManager}, {@code MediaPlayer}) will refuse applications's requests
+         to use cleartext traffic. Third-party libraries are encouraged to honor this flag as well.
+         -->
     <attr name="usesCleartextTraffic" format="boolean" />
 
     <!-- Declare that code from this application will need to be loaded into other
@@ -1228,9 +1229,9 @@
              HTTPS; WebSockets rather than WebSockets Secure; XMPP, IMAP, STMP without STARTTLS or
              TLS). Defaults to true. If set to false {@code false}, the application declares that it
              does not intend to use cleartext network traffic, in which case platform components
-             (e.g. HTTP stacks, {@code WebView}, {@code MediaPlayer}) will refuse applications's
-             requests to use cleartext traffic. Third-party libraries are encouraged to honor this
-             flag as well. -->
+             (e.g. HTTP stacks, {@code DownloadManager}, {@code MediaPlayer}) will refuse
+             applications's requests to use cleartext traffic. Third-party libraries are encouraged
+             to honor this flag as well. -->
         <attr name="usesCleartextTraffic" />
         <attr name="multiArch" />
         <attr name="extractNativeLibs" />
diff --git a/docs/html/guide/topics/manifest/application-element.jd b/docs/html/guide/topics/manifest/application-element.jd
index d6ad656..e63ba71 100644
--- a/docs/html/guide/topics/manifest/application-element.jd
+++ b/docs/html/guide/topics/manifest/application-element.jd
@@ -452,12 +452,11 @@ href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guide.<
 The default value is {@code "true"}.
 
 <p>When the attribute is set to {@code "false"}, platform components (for example, HTTP and FTP
-stacks, {@link android.webkit.WebView}, {@link android.app.DownloadManager},
-{@link android.media.MediaPlayer}) will refuse the app's requests to use cleartext traffic.
-Third-party libraries are strongly encouraged to honor this setting as well. The key reason for
-avoiding cleartext traffic is the lack of confidentiality, authenticity, and protections against
-tampering: a network attacker can eavesdrop on transmitted data and also modify it without being
-detected.
+stacks, {@link android.app.DownloadManager}, {@link android.media.MediaPlayer}) will refuse the
+app's requests to use cleartext traffic. Third-party libraries are strongly encouraged to honor this
+setting as well. The key reason for avoiding cleartext traffic is the lack of confidentiality,
+authenticity, and protections against tampering: a network attacker can eavesdrop on transmitted
+data and also modify it without being detected.
 
 <p>This flag is honored on a best effort basis because it's impossible to prevent all cleartext
 traffic from Android applications given the level of access provided to them. For example, there's
@@ -467,6 +466,8 @@ handled by higher-level network stacks/components which can honor this flag by e
 from {@link android.content.pm.ApplicationInfo#flags ApplicationInfo.flags} or
 {@link android.security.NetworkSecurityPolicy#isCleartextTrafficPermitted() NetworkSecurityPolicy.isCleartextTrafficPermitted()}.
 
+<p>NOTE: {@link android.webkit.WebView} does not honor this flag.
+
 <p>During app development, StrictMode can be used to identify any cleartext traffic from the app: see
 {@link android.os.StrictMode.VmPolicy.Builder#detectCleartextNetwork() StrictMode.VmPolicy.Builder.detectCleartextNetwork()}.