Introduction

The cleartextTrafficPermitted flag is one of the options in Android’s Network Security Configuration file. The online documentation (https://developer.android.com/training/articles/security-config) explains that from Android 9 (API level 28) and higher, it will be set by default to false and it is intended to prevent insecure communication attempts using clear-text HTTP originating from Android applications.

OK, so what does this actually mean? Will all apps that run on the Android 9 platform with a default configuration be protected? Do these flags instruct the system to prohibit any kind of non-secure TCP communications or does it only apply to HTTP? What about 3^rd party libraries such as OkHttp, async-http-client, dubbo? What about WebView controllers? What about native libraries issuing network requests? To answer all these questions, we need to understand at which level this configuration is being enforced. Otherwise, we may fall into a false sense of security.

But how does it actually work? What component and at which level enforces these restrictions? Is it a kernel module such as SELinux or AppArmor? It is Linux containers? Is it the Android Runtime environment? Is it a compiler flag that acts at the time of Ahead-Of-Time or Just-in-time compilation to strip the insecure code parts?

In this article, we will try to understand how this flag works by example and how it can help us to make a more secure application. We will also learn by example which use-cases aren’t being protected by the flag.

The importance of TLS

Just before we begin, a short recap on why we need to protect all application communication with TLS.

Potential threat agents include:

• Wi-fi layer attackers – Numerous router level vulnerabilities, wi-fi hacking, and results of our private research show that tens of millions of routers could be compromised. As such, even home wi-fi cannot be considered as a secure by default. The app must maintain security at the network layer to provide secure transport for app-server communications.
• WAN layer attackers – ISPs logging network traffic or APT and Government level actors monitoring communications at central network hops.

Compromised communications can lead to a number of possible risks including:

• Hijacking secrets from client-side libraries via server-initiated redirects (We will talk about this more in the next blog post)
• HTTPS connections can be downgraded to HTTP even if a server does not support HTTP
• Open redirects to HTTP, both client-side initiated and server-side triggered (for example, the HTTP Desync Attack)
• HTML injected resources (img) with http:// link that trigger HTTP communication
• In-app user-provided clear-text HTTP link to app’s domain
• Cache poisoning resulting in clear-text HTTP redirects

Creating a test-bed

To check how applications actually behave, we created an Android testing application and a python server for the application to communicate with. The test included trying different target APIs for the application and checking for each target API if the app could issue non-secure outgoing HTTP requests using different libraries as well as the default Android WebView controller.

For each library, three requests were sent: standard HTTPS, standard HTTP, and an HTTPS request to a URL which redirects the user agent to HTTP to simulate server-side-issued redirect attacks.

Testing notes

1. Test results for HTTPS to HTTP redirects were the same as for HTTP. If in normal conditions the library prohibits HTTP connections it will also prohibit redirects to HTTP.
2. Differences between minimal, target, and compile SDK versions from the manifest file:
   1. Minimal API – minimal API support required for the app to work;
   2. Compile API – IDE compiler used to compile the app
   3. Target API – the API level on which the application should run correctly as it was fully tested by the developers.
3. Minimum SDK has no impact on how the cleartextTrafficPermitted flag is being enforced; only the API target level affects it.
4. Most of the security issues arise on outdated Android OS versions. However, these versions are running on a large number of devices according to Google:

The results

This section will go through the results for the different libraries tested.

OkHttp

OkHttp is the most popular Android HTTP library and is maintained by Square: https://square.github.io/okhttp/. For the test the latest 3.* and 4.* versions were used. The results for both versions were the same.

The following table shows the results of using our testing app with different target SDK configurations and without the clearTextTrafficPermited flag set (i.e. the default configuration) on multiple Android devices of different OS versions.

	Android 5 API 21	Android 6 API 23	Android 7.1 API 25	Android 8 API 26	Android 9 API 28	Android 10 API 29
target API 21-27	HTTP works	HTTP works	HTTP works	HTTP works	HTTP works	HTTP works
target API 28+	HTTP works	HTTP works	HTTP works	HTTP works	HTTP doesn’t work	HTTP doesn’t work

The following table shows the results of using our testing app with different target SDK configurations and with the clearTextTrafficPermited flag set to “false” on multiple Android devices of different OS versions.

<base-config cleartextTrafficPermitted=“false”>

	Android 5 API 21	Android 6 API 23	Android 7.1 API 25	Android 8 API 26	Android 9 API 28	Android 10 API 29
target API 21-27	HTTP works	HTTP works	HTTP doesn’t work	HTTP doesn’t work	HTTP doesn’t work	HTTP doesn’t work
target API 28+	HTTP works	HTTP works	HTTP doesn’t work	HTTP doesn’t work	HTTP doesn’t work	HTTP doesn’t work

The following table shows the results of using our testing app with different target SDK configurations and with the clearTextTrafficPermited flag set to “true” on multiple Android devices of different OS versions.

<base-config cleartextTrafficPermitted=“true”>

	Android 5 API 21	Android 6 API 23	Android 7.1 API 25	Android 8 API 26	Android 9 API 28	Android 10 API 29
target API 21-27	HTTP works	HTTP works	HTTP works	HTTP works	HTTP works	HTTP works
target API 28+	HTTP works	HTTP works	HTTP works	HTTP works	HTTP works	HTTP works

When the network security policy is being correctly enforced, the OkHttp library won’t issue the request and will throw the following exception:

We can find multiple instances of checking the flag in OkHttp’s source code (https://github.com/square/okhttp) and can manually verify at which cases the check is being done. However, understanding the libraries internal logic may be required to identify the edge cases in which the flag could be ignored. The screenshot shows the source code for the relevant part of the connection chain:

Other Popular Network Libraries for Android

This section shows results for async-http-client library but the results were the same for multiple other libraries that were tested. For the most part, libraries which use okhttp “behind the scenes” support the flag but other popular Android libraries which don’t use okhttp (like async-http-client and many others) don’t support the flag at all.

The following table shows the results of using our testing app with different target SDK configurations with the clearTextTrafficPermited flag set to “false” on multiple Android devices of different OS versions. Since the flag is unsupported, the behavior is in fact the same as if the flag wasn’t set or if the flag was set to “true”.

<base-config cleartextTrafficPermitted=“false”>

	Android 5 API 21	Android 6 API 23	Android 7.1 API 25	Android 8 API 26	Android 9 API 28	Android 10 API 29
target API 21-27	HTTP works	HTTP works	HTTP works	HTTP works	HTTP works	HTTP works
target API 28+	HTTP works	HTTP works	HTTP works	HTTP works	HTTP works	HTTP works

Android WebView

In this section we tested the default Android WebView . This test showed that in fact the WebView controller behaves differently to the OkHttp library in the context of enforcing the configuration flag. In particular:

1. When the application’s target API is 25 or less, the “cleartextTrafficPermitted=”false”” is being ignored across all tested Android OS versions.
2. When HTTP redirect occurs, the WebView behaves differently – it forwards the request to the device’s default browser (external) instead of rendering it on its own. This is secure behavior since the browser doesn’t send any sensitive cookies because it runs in a different context to the application’s WebView.

The following table shows the results of using WebView in our testing app with different target SDK configurations and without a value for the clearTextTrafficPermited flag set (default configuration) on multiple Android devices of different OS versions.

	Android 5 API 21	Android 6 API 23	Android 7.1 API 25	8 API 26	9 API 28	10 API 29
target API 23-27	HTTP works	HTTP works	HTTP works	HTTP works	HTTP works	HTTP works
target API 28+	HTTP works	HTTP works	HTTP works	HTTP works	HTTP doesn’t work	HTTP doesn’t work

The following table shows the results of using WebView in our testing app with different target SDK configurations and with the clearTextTrafficPermited flag set to “false” on multiple Android devices of different OS versions.

	Android 5 API 21	Android 6 API 23	Android 7.1 API 25	8 API 26	9 API 28	10 API 29
target API 23-25	HTTP works	HTTP works	HTTP works	HTTP works	HTTP works	HTTP works
target API 26-27	HTTP works	HTTP works	HTTP doesn’t work	HTTP doesn’t work	HTTP doesn’t work	HTTP doesn’t work
target API 28+	HTTP works	HTTP works	HTTP doesn’t work	HTTP doesn’t work	HTTP doesn’t work	HTTP doesn’t work

When the network policy is being correctly enforced, the WebView will show the following image

Configuration recipes

In this post, we won’t cover all configuration options, but only the main configuration options that should be understood. Full information can be found at https://developer.android.com/training/articles/security-config

To configure the clearTextTrafficPermited flag, we need to set the network security config at the manifest file level:

<application

    android:networkSecurityConfig=“@xml/network_security_config”>

We then need to populate the network_security_config.xml file with the relevant settings.

We have included below some examples of the network config file (network_security_config.xml) and the actual meaning of the settings:

1. Disables all insecure outgoing connections – should be a default choice

<?xml version=“1.0” encoding=“utf-8”?>

<network-security-config>

    <base-config cleartextTrafficPermitted=“true”>

    </base-config>

</network-security-config>

2. Allows HTTP traffic only to appdomain.com domain. All other domains will only be allowed via HTTPS.

<?xml version=“1.0” encoding=“utf-8”?>

<network-security-config>

    <base-config cleartextTrafficPermitted=“false”>

    </base-config>

    <domain-config cleartextTrafficPermitted=“true”>

            <domain includeSubdomains=“true”>appdomain.com</domain>

    </domain-config>

</network-security-config>

3. Forbids any insecure traffic to appdomain.com but allows insecure connection for all other domains (base-config will be default):

<?xml version=“1.0” encoding=“utf-8” ?>

<network-security-config>

        <domain-config cleartextTrafficPermitted=“false”>

               <domain includeSubdomains=“true”>appdomain.com</domain>

        </domain-config>

</network-security-config>

4. Forbids any insecure traffic to appdomain.com; allow explicitly all insecure connection for all other domains:

<?xml version=“1.0” encoding=“utf-8”?>

<network-security-config>

    <base-config cleartextTrafficPermitted=“true”>

    </base-config>

    <domain-config cleartextTrafficPermitted=“false”>

            <domain includeSubdomains=“true”>appdomain.com</domain>

    </domain-config>

</network-security-config>

Results Quick Q&A

In this section we will summarize some of the key questions which we have answered so far in our research:

• What happens when the app communicates using HTTP and makes use of a framework/library which does not support this manifest flag
  • No restrictions will be in place
• At which level does the manifest restrict clear-text communications?
  • Each library reads the flag from configuration flags and enforces the restrictions but only if it supports the flag.
• What happens when native code issues a clear-text network request? For example, it sends an HTTP request or sends binary data (such as protobuf)? Will it be protected by this manifest configuration?
  • Only if the library supports the flag. In most cases these libraries won’t support the flag. The native code libraries and non-HTML libraries mostly have no flag awareness and support. You should rely only on how you configured the library. These configs either can be done in a “config” file or at the actual network request object properties and methods.
• What happens when these libraries issue requests using HTTP and nonstandard port?
  • Generally, if the library supports the flag it will block all outgoing cleartext HTTP communication regardless of the port.

Result analysis and wrap-up

Multiple tests show that manifest flag clearTextTrafficPermited is not being universally enforced by either the Android OS or at the SDK level. IN practice, each client-side library must implement support for the flag on its own and the actual implementation may heavily differ from one library to another.

Certain libraries such as OkHttp (or Volley which uses OkHttp behind the scenes) have full support for this flag according to their documentation. However, many other HTTP libraries which do not use OkHttp do not support it at all and the presence of the flag has no impact on the app’s behavior.

The Android WebView component has support for the flag but actual results show inconsistencies between the WebView and OkHttp implementations. In fact, Android WebView puts more clients at risk compared to OkHttp (refer to the WebView result table) as it does not enforce the flag unless target API is 26+.

Regarding other clients, such as binary communication libraries, etc, do not assume that these libraries will respect the flag. Instead, the source code of each such library should be checked for the code part that enforces the restrictions on outgoing insecure communications. The default assumption for all client-side network libraries should be that they don’t support the flag unless the library explicitly states that it does.

Despite the lack of actual system-wide level protection, the flag still offers a greater level of security in situations where it is supported by the client library and either the application’s target SDK is set to 28+ or the application is running on Android 7.1 or higher.

Recommendations:

1. Activate the clearTextTrafficPermited protection by setting it to “false” for all outgoing connections.
2. Set the target API level to 28+.
3. Check actual support for the flag across different libraries in use in your application.
4. Be aware that the flag enforcement has its restrictions.
5. Enforce other supplementary transport security measures, such as:
   • Using secure response headers such as HSTS.
   • Using explicit request object configurations to prohibit HTTP.
   • Implementing custom interception layers for libraries being used which will block clear-text URI schemes.
   • Removing any HTTP:// links from the code and server’s configuration.