Network security configuration
Archived: 2026-04-05 20:44:52 UTC
The Network Security Configuration feature lets you customize your app's network security settings in a safe,
declarative configuration file without modifying app code. These settings can be configured for specific domains
and for a specific app. The key capabilities of this feature are:
Custom trust anchors: Customize which Certificate Authorities (CA) 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.
Debug-only overrides: Safely debug secure connections in an app without added risk to the installed base.
Cleartext traffic opt-out: Protect apps from accidental usage of cleartext (unencrypted) traffic.
Certificate transparency: Restrict an app's secure connections to use provably logged certificates.
Certificate pinning: Restrict an app's secure connection to particular certificates.
The Network Security Configuration feature uses an XML file where you specify the settings for your app. You
must include an entry in your app's manifest to point to this file. The following code excerpt from a manifest
demonstrates how to create this entry:
...
Customize trusted CAs
You might want your app to trust a custom set of CAs instead of the platform default. The most common reasons
for this are:
Connecting to a host with a custom CA, such as a CA that is self-signed or is issued internally within a
company.
Limiting the set of CAs to only the CAs you trust instead of every pre-installed CA.
Trusting additional CAs not included in the system.
By default, secure connections (using protocols like TLS and HTTPS) from all apps trust the pre-installed system
CAs, and apps targeting Android 6.0 (API level 23) and lower also trust the user-added CA store by default. You
can customize your app's connections using base-config (for app-wide customization) or domain-config (for
per-domain customization).
https://developer.android.com/training/articles/security-config.html
Page 1 of 14
Configure a custom CA
You might want to connect to a host that uses a self-signed SSL certificate or to a host whose SSL certificate is
issued by a non-public CA that you trust, such as your company's internal CA. The following code excerpt
demonstrates how to configure your app for a custom CA in res/xml/network_security_config.xml :
example.com Add the self-signed or non-public CA certificate, in PEM or DER format, to res/raw/my_ca .
Limit the set of trusted CAs
If you don't want your app to trust all CAs trusted by the system, you can instead specify a reduced set of CAs to
trust. This protects the app from fraudulent certificates issued by any of the other CAs.
The configuration to limit the set of trusted CAs is similar to trusting a custom CA for a specific domain except
that multiple CAs are provided in the resource. The following code excerpt demonstrates how to limit your app's
set of trusted CAs in res/xml/network_security_config.xml :
secure.example.comcdn.example.com Add the trusted CAs, in PEM or DER format, to res/raw/trusted_roots . Note that if you use PEM format, the
file must contain only PEM data and no extra text. You can also provide multiple elements
instead of one.
Trust additional CAs
https://developer.android.com/training/articles/security-config.html
Page 2 of 14
You might want your app to trust additional CAs that aren't trusted by the system, such as if the system doesn't yet
include the CA or the CA doesn't meet the requirements for inclusion in the Android system. You can specify
multiple certificate sources for a configuration in res/xml/network_security_config.xml using code like the
following excerpt.
Configure CAs for debugging
When debugging an app that connects over HTTPS, you may want to connect to a local development server that
does not have the SSL certificate for your production server. To support this without any modification to your
app's code, you can specify debug-only CAs, which are trusted only when android:debuggable is true , by using
debug-overrides . Normally, IDEs and build tools set this flag automatically for non-release builds.
This is safer than the usual conditional code because, as a security precaution, app stores do not accept apps that
are marked debuggable.
The excerpt below shows how to specify debug-only CAs in res/xml/network_security_config.xml :
Certificate transparency
Note: Certificate transparency support is only available from Android 16 (API level 36).
Certificate Transparency (CT, RFC 6962) is an Internet standard designed to enhance the security of digital
certificates. It requires CAs to submit all issued certificates to a public log that records them, increasing
transparency and accountability in the certificate issuance process.
https://developer.android.com/training/articles/security-config.html
Page 3 of 14
By maintaining a verifiable record of all certificates, CT makes it significantly harder for malicious actors to forge
certificates or for CAs to mistakenly issue them. This helps protect users from man-in-the-middle attacks and
other security threats. For more information, see the explanation on transparency.dev. For more information about
CT compliance on Android, see Android's CT policy.
The default behavior of certificate transparency depends on the API level:
Starting with Android 17 (API level 37), certificate transparency is enabled by default. Apps can opt out of
the feature either globally or on a per-domain basis.
On Android 16 (API level 36), certificate transparency is disabled by default. Apps can opt in to the feature
either globally or on a per-domain basis.
On Android 15 (API level 35) and lower, certificate transparency is not available.
Opt out of certificate transparency
Note: For Android 16 (API level 36), opt in to certificate transparency by setting (it is disabled by default).
If you intend for your app to connect to destinations without requiring their certificates to be logged into
certificate transparency logs, you can opt out of certificate transparency.
For example, you might want to allow your app to make connections to secure.example.com without requiring
certificate transparency.
secure.example.com Encrypted Client Hello
Note: Encrypted Client Hello support is only available from Android 17 (API level 37) and requires the app's
networking library to support ECH. The configuration specified here will only take effect if the networking library
has adopted ECH.
Encrypted Client Hello (ECH, RFC 9849) is a TLS protocol extension designed to enhance the privacy of secure
connections. It works by encrypting the sensitive parts of the initial TLS handshake, most notably the Server
Name Indication (SNI) field.
By encrypting the SNI, ECH prevents network intermediaries from observing the specific domain name the client
is attempting to connect to. This helps prevent users from being fingerprinted or monitored based on the domains
they visit, mitigating a significant privacy leak present in standard TLS handshakes.
https://developer.android.com/training/articles/security-config.html
Page 4 of 14
The default behavior of Encrypted Client Hello depends on the API level:
Starting with Android 17 (API level 37), ECH is used in "opportunistic" mode by default. Apps can opt out
of the feature or modify its behavior either globally or on a per-domain basis.
On Android 16 (API level 36) and lower, ECH is not available.
Opt out of Encrypted Client Hello
You can opt out of the feature by disabling it. For example, if you wanted to disable ECH when making
connections to disable-ech.example.com only, but keep ECH enabled for all other domains, you can use the
following configuration:
disable-ech.example.com Cleartext traffic
Developers can opt in or out of cleartext traffic (using the unencrypted HTTP protocol instead of HTTPS) for their
applications. See NetworkSecurityPolicy.isCleartextTrafficPermitted() for more details.
The default behavior of cleartext traffic depends on the API level:
Up to Android 8.1 (API level 27), cleartext support is enabled by default. Applications can opt out of
cleartext traffic for additional security.
Starting with Android 9 (API level 28), cleartext support is disabled by default. Applications that require
cleartext traffic can opt in to cleartext traffic.
Opt out of cleartext traffic
Note: The guidance in this section applies only to apps that target Android 8.1 (API level 27) or lower.
If you intend for your app to connect to destinations using only secure connections, you can opt out of supporting
cleartext traffic to those destinations. This option helps prevent accidental regressions in apps due to changes in
URLs provided by external sources such as backend servers.
For example, you might want your app to ensure that connections to secure.example.com are always done over
HTTPS to protect sensitive traffic from hostile networks.
https://developer.android.com/training/articles/security-config.html
Page 5 of 14
secure.example.com
Opt in to cleartext traffic
Note: The guidance in this section applies only to apps that target Android 9 (API level 28) or higher.
If your app needs to connect to destinations using cleartext traffic (HTTP), you can opt in to supporting cleartext
to those destinations.
For example, you might want to allow your app to make insecure connections to insecure.example.com .
insecure.example.com
If your app needs to opt in to cleartext traffic to any domain, set cleartextTrafficPermitted="true" in the
base-config . Note that this insecure configuration should be avoided whenever possible.
Pin certificates
Normally, an app trusts all pre-installed CAs. If any of these CAs were to issue a fraudulent certificate, the app
would be at risk from an on-path attacker. Some apps choose to limit the set of certificates they accept by either
limiting the set of CAs they trust or by certificate pinning.
Certificate pinning is done by providing a set of certificates by hash of the public key ( SubjectPublicKeyInfo of
the X.509 certificate). A certificate chain is then valid only if the certificate chain contains at least one of the
pinned public keys.
Note that, when using certificate pinning, you should always include a backup key so that if you are forced to
switch to new keys or change CAs (when pinning to a CA certificate or an intermediate of that CA), your app's
https://developer.android.com/training/articles/security-config.html
Page 6 of 14
connectivity is unaffected. Otherwise, you must push out an update to the app to restore connectivity.
Additionally, it is possible to set an expiration time for pins after which pinning is not performed. This helps
prevent connectivity issues in apps which have not been updated. However, setting an expiration time on pins may
enable attackers to bypass your pinned certificates.
The excerpt below shows how to pin certificates in res/xml/network_security_config.xml :
example.com7HIpactkIAq2Y49orFOOQKurWxmmSFZhBCoQYcRhJ3Y=fwza0LRMXouZHRC8Ei+4PyuldPDcf3UKgO/04cDM1oE= Configuration inheritance behavior
Values not set in a specific configuration are inherited. This behavior allows more complex configurations while
keeping the configuration file readable.
For example, values not set in a domain-config are taken from the parent domain-config , if nested, or from the
base-config , if not. Values not set in the base-config use the platform default values.
For example, consider a case where all connections to subdomains of example.com must use a custom set of
CAs. Additionally, cleartext traffic to these domains is permitted except when connecting to
secure.example.com . By nesting the configuration for secure.example.com inside the configuration for
example.com , the trust-anchors does not need to be duplicated.
The excerpt below shows how this nesting would look in res/xml/network_security_config.xml :
example.comsecure.example.com https://developer.android.com/training/articles/security-config.html
Page 7 of 14
Localhost configuration
Enforcing the network security features for localhost connections is generally unnecessary. For example,
certificate transparency is rarely needed for localhost connections.
From Android 17 (API level 37) and higher, if no configuration has been defined for localhost, an implicit
configuration is included. By default, this configuration does the following:
Allows cleartext traffic.
Doesn't enforce certificate transparency (CT).
Doesn't enforce certificate pinning.
Delegates to for trust anchors.
A configuration is considered to be targeting localhost if the domain is:
localhost
ip6-localhost or
a numerical IP address and InetAddress.isLoopback() is true (for example, 127.0.0.1 or [::1] )
Configuration file format
The Network Security Configuration feature uses an XML file format. The overall structure of the file is shown in
the following code sample:
... android.com ... ... ... ...
https://developer.android.com/training/articles/security-config.html
Page 8 of 14
... ... The following sections describe the syntax and other details of the file format.
can contain:
0 or 1 of Any number of 0 or 1 of syntax:
...
can contain:
description:
The default configuration used by all connections whose destination is not covered by a domain-config .
Any values that are not set use the platform default values.
The default configuration for apps targeting Android 9 (API level 28) and higher is as follows:
The default configuration for apps targeting Android 7.0 (API level 24) to Android 8.1 (API level 27) is as
follows:
https://developer.android.com/training/articles/security-config.html
Page 9 of 14
The default configuration for apps targeting Android 6.0 (API level 23) and lower is as follows:
syntax:
...
can contain:
1 or more 0 or 1 0 or 1 0 or 1 0 or 1 Any number of nested description:
Configuration used for connections to specific destinations, as defined by the domain elements.
Note that if multiple domain-config elements cover a destination, the configuration with the most
specific (longest) matching domain rule is used.
syntax:
example.com attributes:
https://developer.android.com/training/articles/security-config.html
Page 10 of 14
includeSubdomains
If "true" , then this domain rule matches the domain and all subdomains, including subdomains of
subdomains. Otherwise, the rule only applies to exact matches.
syntax:
description:
If true , then the app will use the Certificate Transparency logs to validate certificates. When an app uses
its own certificate (or the user store), it is likely that the certificate is not public and therefore not verifiable
using certificate transparency. By default, the verification is disabled for these cases. It is still possible to
force the verification using in the domain configuration.
For each , the evaluation follows this order:
1. If certificateTransparency is enabled, enable the verification.
2. If any is "user" or inline (i.e., "@raw/cert.pem" ), disable the verification.
3. Otherwise, rely on the inherited configuration.
syntax:
description:
Controls Encrypted Client Hello (ECH) behavior for connections to the specified domains.
Note: The domainEncryption element depends on the app's networking library supporting ECH. The
specified behavior only takes effect if the networking library has adopted ECH. Apps are not expected to
handle ECH configurations themselves and should instead rely on their networking libraries to do so when
establishing the TLS handshake.
The mode attribute can be one of the following:
enabled : Enforce ECH on a connection when the ECH configuration is provided when
establishing the TLS handshake, and enable ECH GREASE otherwise.
opportunistic : Use ECH on a connection when the ECH configuration is provided when
establishing the TLS handshake. If the connection fails or the configuration was not provided, fall
back to a standard non-encrypted TLS ClientHello. This mode does not enable ECH GREASE.
disabled : Don't attempt to use ECH or ECH GREASE on any connections.
If not specified, the default mode is "opportunistic" .
https://developer.android.com/training/articles/security-config.html
Page 11 of 14
syntax:
...
can contain:
0 or 1 description:
Overrides to be applied when android:debuggable is "true" , which is normally the case for non-release
builds generated by IDEs and build tools. Trust anchors specified in debug-overrides are added to all
other configurations, and certificate pinning is not performed when the server's certificate chain uses one of
these debug-only trust anchors. If android:debuggable is "false" , then this section is completely ignored.
syntax:
...
can contain:
Any number of description:
Set of trust anchors for secure connections.
syntax:
description:
Set of X.509 certificates for trust-anchors elements.
attributes:
src
The source of CA certificates. Each certificate can be one of the following:
a raw resource ID pointing to a file containing X.509 certificates. Certificates must be
encoded in DER or PEM format. In the case of PEM certificates, the file must not contain
extra non-PEM data such as comments.
https://developer.android.com/training/articles/security-config.html
Page 12 of 14
"system" for the pre-installed system CA certificates
"user" for user-added CA certificates
overridePins
Specifies if the CAs from this source bypass certificate pinning. If "true" , then pinning is not
performed on certificate chains which are signed by one of the CAs from this source. This can be
useful for debugging CAs or for testing man-in-the-middle attacks on your app's secure traffic.
Default is "false" unless specified in a debug-overrides element, in which case the default is
"true" .
syntax:
...
can contain:
Any number of
description:
A set of public key pins. For a secure connection to be trusted, one of the public keys in the chain of trust
must be in the set of pins. See for the format of pins.
attributes:
expiration
The date, in yyyy-MM-dd format, on which the pins expire, thus disabling pinning. If the attribute is
not set, then the pins do not expire.
Expiration helps prevent connectivity issues in apps which do not get updates to their pin set, such
as when the user disables app updates.
syntax:
base64 encoded digest of X.509
SubjectPublicKeyInfo (SPKI)
attributes:
digest
The digest algorithm used to generate the pin. Currently, only "SHA-256" is supported.
https://developer.android.com/training/articles/security-config.html
Page 13 of 14
Source: https://developer.android.com/training/articles/security-config.html
https://developer.android.com/training/articles/security-config.html
Page 14 of 14