Skip to content

MASTG-KNOW-0014: Android Network Security Configuration

Starting on Android 7.0 (API level 24), Android apps can customize their network security settings using the so-called Network Security Configuration feature which offers the following key capabilities:

  • Cleartext traffic: Protect apps from accidental usage of cleartext traffic (or enables it).
  • Custom trust anchors: Customize which Certificate Authorities (CAs) are trusted for an app's secure connections. For example, trusting particular self-signed certificates or restricting the set of public CAs that the app trusts.
  • Certificate pinning: Restrict an app's secure connection to particular certificates.
  • Debug-only overrides: Safely debug secure connections in an app without added risk to the installed base.

If an app defines a custom Network Security Configuration, you can obtain its location by searching for android:networkSecurityConfig in the AndroidManifest.xml file.

<application android:networkSecurityConfig="@xml/network_security_config"

In this case the file is located at @xml (equivalent to /res/xml) and has the name "network_security_config" (which might vary). You should be able to find it as "res/xml/network_security_config.xml". If a configuration exists, the following event should be visible in the system logs ( Monitoring System Logs):

D/NetworkSecurityConfig: Using Network Security Config from resource network_security_config

The Network Security Configuration is XML-based and can be used to configure app-wide and domain-specific settings:

  • base-config applies to all connections that the app attempts to make.
  • domain-config overrides base-config for specific domains (it can contain multiple domain entries).

For example, the following configuration uses the base-config to prevent cleartext traffic for all domains. But it overrides that rule using a domain-config, explicitly allowing cleartext traffic for localhost.

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="false" />
    <domain-config cleartextTrafficPermitted="true">
        <domain>localhost</domain>
    </domain-config>
</network-security-config>

Learn more:

Default Configurations

The default configuration for apps targeting Android 9 (API level 28) and higher is as follows:

<base-config cleartextTrafficPermitted="false">
    <trust-anchors>
        <certificates src="system" />
    </trust-anchors>
</base-config>

The default configuration for apps targeting Android 7.0 (API level 24) to Android 8.1 (API level 27) is as follows:

<base-config cleartextTrafficPermitted="true">
    <trust-anchors>
        <certificates src="system" />
    </trust-anchors>
</base-config>

The default configuration for apps targeting Android 6.0 (API level 23) and lower is as follows:

<base-config cleartextTrafficPermitted="true">
    <trust-anchors>
        <certificates src="system" />
        <certificates src="user" />
    </trust-anchors>
</base-config>