Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit e35cefbf authored by Alex Klyubin's avatar Alex Klyubin
Browse files

Document usesCleartextTraffic app-level attribute. 

This updates the documentation of the application element of
AndroidManifest.xml to mention the new android:usesCleartextTraffic
attribute.

This also updates the Javadoc of
android.security.NetworkSecurityPolicy and ApplicationInfo to match.

Bug: 19215516
Change-Id: I5c221b56addae8988b4db51994d18ae379d0fbe3
parent 2eabe5b7

core/java/android/content/pm/ApplicationInfo.java

+2 −2
Original line number Diff line number Diff line
@@ -338,8 +338,8 @@ 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 MediaPlayer}) will refuse app's requests to use cleartext traffic.

     * Third-party libraries are encouraged to honor this flag as well.

     * {@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.

     */

    public static final int FLAG_USES_CLEARTEXT_TRAFFIC = 1<<27;

core/java/android/security/NetworkSecurityPolicy.java

+3 −3
Original line number Diff line number Diff line
@@ -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.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.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.

     *

     * <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

docs/html/guide/topics/manifest/application-element.jd

+27 −0
Original line number Diff line number Diff line
@@ -32,6 +32,7 @@ page.title=&lt;application&gt; 
             android:<a href="#testOnly">testOnly</a>=["true" | "false"]

             android:<a href="#theme">theme</a>="<i>resource or theme</i>"

             android:<a href="#uioptions">uiOptions</a>=["none" | "splitActionBarWhenNarrow"]

             android:<a href="#usesCleartextTraffic">usesCleartextTraffic</a>=["true" | "false"]

             android:<a href="#vmSafeMode">vmSafeMode</a>=["true" | "false"] &gt;

    . . .

&lt;/application&gt;</pre></dd>
@@ -446,6 +447,32 @@ href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guide.< 
  <p>This attribute was added in API level 14.</p>

</dd>



<dt><a name="usesCleartextTraffic"></a>{@code android:usesCleartextTraffic}</dt>

<dd>Indicates whether the app intends to use cleartext network traffic, such as cleartext HTTP.

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.



<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

no expectation that the {@link java.net.Socket} API will honor this flag 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 flag by either reading it

from {@link android.content.pm.ApplicationInfo#flags ApplicationInfo.flags} or

{@link android.security.NetworkSecurityPolicy#isCleartextTrafficPermitted() NetworkSecurityPolicy.isCleartextTrafficPermitted()}.



<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()}.



<p>This attribute was added in API level 23.</p>

</dd>



<dt><a name="vmSafeMode"></a>{@code android:vmSafeMode}</dt>

<dd>Indicates whether the app would like the virtual machine (VM) to operate

in safe mode. The default value is {@code "false"}.