Protecting against unintentional regressions to cleartext traffic in your Android apps

Posted by Alex Klyubin, Android Security team

When your app communicates with servers using cleartext network traffic, such as HTTP, the traffic risks being eavesdropped upon and tampered with by third parties. This may leak information about your users and open your app up to injection of unauthorized content or exploits. Ideally, your app should use secure traffic only, such as by using HTTPS instead of HTTP. Such traffic is protected against eavesdropping and tampering.

Many Android apps already use secure traffic only. However, some of them occasionally regress to cleartext traffic by accident. For example, an inadvertent change in one of the server components could make the server provide the app with HTTP URLs instead of HTTPS URLs. The app would then proceed to communicate in cleartext, without any user-visible symptoms. This situation may go unnoticed by the app’s developer and users.

Even if you believe your app is only using secure traffic, make sure to use the new mechanisms provided by Android Marshmallow (Android 6.0) to catch and prevent accidental regressions.

New protection mechanisms

For apps which only use secure traffic, Android 6.0 Marshmallow (API Level 23) introduced two mechanisms to address regressions to cleartext traffic: (1) in production / installed base, block cleartext traffic, and (2) during development / QA, log or crash whenever non-TLS/SSL traffic is encountered. The following sections provide more information about these mechanisms.

Block cleartext traffic in production

To protect the installed base of your app against regressions to cleartext traffic, declare android:usesCleartextTraffic=”false” attribute on the application element in your app’s AndroidManifest.xml. This declares that the app is not supposed to use cleartext network traffic and makes the platform network stacks of Android Marshmallow block cleartext traffic in the app. For example, if your app accidentally attempts to sign in the user via a cleartext HTTP request, the request will be blocked and the user’s identity and password will not leak to the network.

You don’t have to set minSdkVersion or targetSdkVersion of your app to 23 (Android Marshmallow) to use android:usesCleartextTraffic. On older platforms, this attribute is simply ignored and thus has no effect.

Please note that WebView does not yet honor this feature.

And under certain circumstances cleartext traffic may still leave or enter the app. For example, Socket API ignores the cleartext policy because it does not know whether the data it transmits or receives can be classified as cleartext. Android platform HTTP stacks, on the other hand, honor the policy because they know whether traffic is cleartext.

Google AdMob is also built to honor this policy. When your app declares that it does not use cleartext traffic, only HTTPS-only ads should be served to the app.

Third-party network, ad, and analytics libraries are encouraged to add support for this policy. They can query the cleartext traffic policy via the NetworkSecurityPolicy class.

Detect cleartext traffic during development

To spot cleartext traffic during development or QA, StrictMode API lets you modify your app to detect non-TLS/SSL traffic and then either log violations to system log or crash the app (see StrictMode.VmPolicy.Builder.detectCleartextNetwork()). This is a useful tool for identifying which bits of the app are using non-TLS/SSL (and DLTS) traffic. Unlike the android:usesCleartextTraffic attribute, this feature is not meant to be enabled in app builds distributed to users.

Firstly, this feature is supposed to flag secure traffic that is not TLS/SSL. More importantly, TLS/SSL traffic via HTTP proxy also may be flagged. This is an issue because as a developer, you have no control over whether a particular user of your app may have configured their Android device to use an HTTP proxy. Finally, the implementation of the feature is not future-proof and thus may reject future TLS/SSL protocol versions. Thus, this feature is intended to be used only during the development and QA phase.

Declare finer-grained cleartext policy in Network Security Config

Android N offers finer-grained control over cleartext traffic policy. As opposed to android:usesCleartextTraffic attribute, which applies to all destinations with which an app communicates, Android N’s Network Security Config lets an app specify cleartext policy for specific destinations. For example, to facilitate a more gradual transition towards a policy that does not allow cleartext traffic, an app can at first block accidental cleartext only for communication with its most important backends and permit cleartext to be used for other destinations.

Next steps

It is a security best practice to only use secure network traffic for communication between your app and its servers. Android Marshmallow enables you to enforce this practice, so give it a try!

As always, we appreciate feedback and welcome suggestions for improving Android. Contact us at security@android.com.