{
	"id": "a2dcd0a8-bb54-4c7f-88f4-2032713f4f52",
	"created_at": "2026-04-06T00:16:42.146667Z",
	"updated_at": "2026-04-10T13:12:27.723899Z",
	"deleted_at": null,
	"sha1_hash": "8f94b41fe5b11c24b470eeb9a543644d665778de",
	"title": "Network security configuration",
	"llm_title": "",
	"authors": "",
	"file_creation_date": "0001-01-01T00:00:00Z",
	"file_modification_date": "0001-01-01T00:00:00Z",
	"file_size": 144796,
	"plain_text": "Network security configuration\r\nArchived: 2026-04-05 20:44:52 UTC\r\nThe Network Security Configuration feature lets you customize your app's network security settings in a safe,\r\ndeclarative configuration file without modifying app code. These settings can be configured for specific domains\r\nand for a specific app. The key capabilities of this feature are:\r\nCustom trust anchors: Customize which Certificate Authorities (CA) are trusted for an app's secure\r\nconnections. For example, trusting particular self-signed certificates or restricting the set of public CAs that\r\nthe app trusts.\r\nDebug-only overrides: Safely debug secure connections in an app without added risk to the installed base.\r\nCleartext traffic opt-out: Protect apps from accidental usage of cleartext (unencrypted) traffic.\r\nCertificate transparency: Restrict an app's secure connections to use provably logged certificates.\r\nCertificate pinning: Restrict an app's secure connection to particular certificates.\r\nThe Network Security Configuration feature uses an XML file where you specify the settings for your app. You\r\nmust include an entry in your app's manifest to point to this file. The following code excerpt from a manifest\r\ndemonstrates how to create this entry:\r\n\u003c?xml version=\"1.0\" encoding=\"utf-8\"?\u003e\r\n\u003cmanifest ... \u003e\r\n \u003capplication android:networkSecurityConfig=\"@xml/network_security_config\"\r\n ... \u003e\r\n ...\r\n \u003c/application\u003e\r\n\u003c/manifest\u003e\r\nCustomize trusted CAs\r\nYou might want your app to trust a custom set of CAs instead of the platform default. The most common reasons\r\nfor this are:\r\nConnecting to a host with a custom CA, such as a CA that is self-signed or is issued internally within a\r\ncompany.\r\nLimiting the set of CAs to only the CAs you trust instead of every pre-installed CA.\r\nTrusting additional CAs not included in the system.\r\nBy default, secure connections (using protocols like TLS and HTTPS) from all apps trust the pre-installed system\r\nCAs, and apps targeting Android 6.0 (API level 23) and lower also trust the user-added CA store by default. You\r\ncan customize your app's connections using base-config (for app-wide customization) or domain-config (for\r\nper-domain customization).\r\nhttps://developer.android.com/training/articles/security-config.html\r\nPage 1 of 14\n\nConfigure a custom CA\nYou might want to connect to a host that uses a self-signed SSL certificate or to a host whose SSL certificate is\nissued by a non-public CA that you trust, such as your company's internal CA. The following code excerpt\ndemonstrates how to configure your app for a custom CA in res/xml/network_security_config.xml :\nexample.com Add the self-signed or non-public CA certificate, in PEM or DER format, to res/raw/my_ca .\nLimit the set of trusted CAs\nIf you don't want your app to trust all CAs trusted by the system, you can instead specify a reduced set of CAs to\ntrust. This protects the app from fraudulent certificates issued by any of the other CAs.\nThe configuration to limit the set of trusted CAs is similar to trusting a custom CA for a specific domain except\nthat multiple CAs are provided in the resource. The following code excerpt demonstrates how to limit your app's\nset of trusted CAs in res/xml/network_security_config.xml :\nsecure.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\nfile must contain only PEM data and no extra text. You can also provide multiple elements\ninstead of one.\nTrust additional CAs\nhttps://developer.android.com/training/articles/security-config.html\nPage 2 of 14\n\nYou might want your app to trust additional CAs that aren't trusted by the system, such as if the system doesn't yet\ninclude the CA or the CA doesn't meet the requirements for inclusion in the Android system. You can specify\nmultiple certificate sources for a configuration in res/xml/network_security_config.xml using code like the\nfollowing excerpt.\nConfigure CAs for debugging\nWhen debugging an app that connects over HTTPS, you may want to connect to a local development server that\ndoes not have the SSL certificate for your production server. To support this without any modification to your\napp's code, you can specify debug-only CAs, which are trusted only when android:debuggable is true , by using\ndebug-overrides . Normally, IDEs and build tools set this flag automatically for non-release builds.\nThis is safer than the usual conditional code because, as a security precaution, app stores do not accept apps that\nare marked debuggable.\nThe excerpt below shows how to specify debug-only CAs in res/xml/network_security_config.xml :\nCertificate transparency\nNote: Certificate transparency support is only available from Android 16 (API level 36).\nCertificate Transparency (CT, RFC 6962) is an Internet standard designed to enhance the security of digital\ncertificates. It requires CAs to submit all issued certificates to a public log that records them, increasing\ntransparency and accountability in the certificate issuance process.\nhttps://developer.android.com/training/articles/security-config.html\nPage 3 of 14\n\nBy maintaining a verifiable record of all certificates, CT makes it significantly harder for malicious actors to forge\ncertificates or for CAs to mistakenly issue them. This helps protect users from man-in-the-middle attacks and\nother security threats. For more information, see the explanation on transparency.dev. For more information about\nCT compliance on Android, see Android's CT policy.\nThe default behavior of certificate transparency depends on the API level:\nStarting with Android 17 (API level 37), certificate transparency is enabled by default. Apps can opt out of\nthe feature either globally or on a per-domain basis.\nOn Android 16 (API level 36), certificate transparency is disabled by default. Apps can opt in to the feature\neither globally or on a per-domain basis.\nOn Android 15 (API level 35) and lower, certificate transparency is not available.\nOpt out of certificate transparency\nNote: For Android 16 (API level 36), opt in to certificate transparency by setting (it is disabled by default).\nIf you intend for your app to connect to destinations without requiring their certificates to be logged into\ncertificate transparency logs, you can opt out of certificate transparency.\nFor example, you might want to allow your app to make connections to secure.example.com without requiring\ncertificate transparency.\nsecure.example.com Encrypted Client Hello\nNote: Encrypted Client Hello support is only available from Android 17 (API level 37) and requires the app's\nnetworking library to support ECH. The configuration specified here will only take effect if the networking library\nhas adopted ECH.\nEncrypted Client Hello (ECH, RFC 9849) is a TLS protocol extension designed to enhance the privacy of secure\nconnections. It works by encrypting the sensitive parts of the initial TLS handshake, most notably the Server\nName Indication (SNI) field.\nBy encrypting the SNI, ECH prevents network intermediaries from observing the specific domain name the client\nis attempting to connect to. This helps prevent users from being fingerprinted or monitored based on the domains\nthey visit, mitigating a significant privacy leak present in standard TLS handshakes.\nhttps://developer.android.com/training/articles/security-config.html\nPage 4 of 14\n\nThe default behavior of Encrypted Client Hello depends on the API level:\nStarting with Android 17 (API level 37), ECH is used in \"opportunistic\" mode by default. Apps can opt out\nof the feature or modify its behavior either globally or on a per-domain basis.\nOn Android 16 (API level 36) and lower, ECH is not available.\nOpt out of Encrypted Client Hello\nYou can opt out of the feature by disabling it. For example, if you wanted to disable ECH when making\nconnections to disable-ech.example.com only, but keep ECH enabled for all other domains, you can use the\nfollowing configuration:\ndisable-ech.example.com Cleartext traffic\nDevelopers can opt in or out of cleartext traffic (using the unencrypted HTTP protocol instead of HTTPS) for their\napplications. See NetworkSecurityPolicy.isCleartextTrafficPermitted() for more details.\nThe default behavior of cleartext traffic depends on the API level:\nUp to Android 8.1 (API level 27), cleartext support is enabled by default. Applications can opt out of\ncleartext traffic for additional security.\nStarting with Android 9 (API level 28), cleartext support is disabled by default. Applications that require\ncleartext traffic can opt in to cleartext traffic.\nOpt out of cleartext traffic\nNote: The guidance in this section applies only to apps that target Android 8.1 (API level 27) or lower.\nIf you intend for your app to connect to destinations using only secure connections, you can opt out of supporting\ncleartext traffic to those destinations. This option helps prevent accidental regressions in apps due to changes in\nURLs provided by external sources such as backend servers.\nFor example, you might want your app to ensure that connections to secure.example.com are always done over\nHTTPS to protect sensitive traffic from hostile networks.\nhttps://developer.android.com/training/articles/security-config.html\nPage 5 of 14\n\n\u003c?xml version=\"1.0\" encoding=\"utf-8\"?\u003e\r\n\u003cnetwork-security-config\u003e\r\n \u003cdomain-config cleartextTrafficPermitted=\"false\"\u003e\r\n \u003cdomain includeSubdomains=\"true\"\u003esecure.example.com\u003c/domain\u003e\r\n \u003c/domain-config\u003e\r\n\u003c/network-security-config\u003e\r\nOpt in to cleartext traffic\r\nNote: The guidance in this section applies only to apps that target Android 9 (API level 28) or higher.\r\nIf your app needs to connect to destinations using cleartext traffic (HTTP), you can opt in to supporting cleartext\r\nto those destinations.\r\nFor example, you might want to allow your app to make insecure connections to insecure.example.com .\r\n\u003c?xml version=\"1.0\" encoding=\"utf-8\"?\u003e\r\n\u003cnetwork-security-config\u003e\r\n \u003cdomain-config cleartextTrafficPermitted=\"true\"\u003e\r\n \u003cdomain includeSubdomains=\"true\"\u003einsecure.example.com\u003c/domain\u003e\r\n \u003c/domain-config\u003e\r\n\u003c/network-security-config\u003e\r\nIf your app needs to opt in to cleartext traffic to any domain, set cleartextTrafficPermitted=\"true\" in the\r\nbase-config . Note that this insecure configuration should be avoided whenever possible.\r\n\u003c?xml version=\"1.0\" encoding=\"utf-8\"?\u003e\r\n\u003cnetwork-security-config\u003e\r\n \u003cbase-config cleartextTrafficPermitted=\"true\"\u003e\r\n \u003c/base-config\u003e\r\n\u003c/network-security-config\u003e\r\nPin certificates\r\nNormally, an app trusts all pre-installed CAs. If any of these CAs were to issue a fraudulent certificate, the app\r\nwould be at risk from an on-path attacker. Some apps choose to limit the set of certificates they accept by either\r\nlimiting the set of CAs they trust or by certificate pinning.\r\nCertificate pinning is done by providing a set of certificates by hash of the public key ( SubjectPublicKeyInfo of\r\nthe X.509 certificate). A certificate chain is then valid only if the certificate chain contains at least one of the\r\npinned public keys.\r\nNote that, when using certificate pinning, you should always include a backup key so that if you are forced to\r\nswitch to new keys or change CAs (when pinning to a CA certificate or an intermediate of that CA), your app's\r\nhttps://developer.android.com/training/articles/security-config.html\r\nPage 6 of 14\n\nconnectivity is unaffected. Otherwise, you must push out an update to the app to restore connectivity.\nAdditionally, it is possible to set an expiration time for pins after which pinning is not performed. This helps\nprevent connectivity issues in apps which have not been updated. However, setting an expiration time on pins may\nenable attackers to bypass your pinned certificates.\nThe excerpt below shows how to pin certificates in res/xml/network_security_config.xml :\nexample.com7HIpactkIAq2Y49orFOOQKurWxmmSFZhBCoQYcRhJ3Y=fwza0LRMXouZHRC8Ei+4PyuldPDcf3UKgO/04cDM1oE= Configuration inheritance behavior\nValues not set in a specific configuration are inherited. This behavior allows more complex configurations while\nkeeping the configuration file readable.\nFor example, values not set in a domain-config are taken from the parent domain-config , if nested, or from the\nbase-config , if not. Values not set in the base-config use the platform default values.\nFor example, consider a case where all connections to subdomains of example.com must use a custom set of\nCAs. Additionally, cleartext traffic to these domains is permitted except when connecting to\nsecure.example.com . By nesting the configuration for secure.example.com inside the configuration for\nexample.com , the trust-anchors does not need to be duplicated.\nThe excerpt below shows how this nesting would look in res/xml/network_security_config.xml :\nexample.comsecure.example.com https://developer.android.com/training/articles/security-config.html\nPage 7 of 14\n\nLocalhost configuration\nEnforcing the network security features for localhost connections is generally unnecessary. For example,\ncertificate transparency is rarely needed for localhost connections.\nFrom Android 17 (API level 37) and higher, if no configuration has been defined for localhost, an implicit\nconfiguration is included. By default, this configuration does the following:\nAllows cleartext traffic.\nDoesn't enforce certificate transparency (CT).\nDoesn't enforce certificate pinning.\nDelegates to for trust anchors.\nA configuration is considered to be targeting localhost if the domain is:\nlocalhost\nip6-localhost or\na numerical IP address and InetAddress.isLoopback() is true (for example, 127.0.0.1 or [::1] )\nConfiguration file format\nThe Network Security Configuration feature uses an XML file format. The overall structure of the file is shown in\nthe following code sample:\n... android.com ... ... ... ...\nhttps://developer.android.com/training/articles/security-config.html\nPage 8 of 14\n\n... ... The following sections describe the syntax and other details of the file format.\ncan contain:\n0 or 1 of Any number of 0 or 1 of syntax:\n...\ncan contain:\n  description:\nThe default configuration used by all connections whose destination is not covered by a domain-config .\nAny values that are not set use the platform default values.\nThe default configuration for apps targeting Android 9 (API level 28) and higher is as follows:\nThe default configuration for apps targeting Android 7.0 (API level 24) to Android 8.1 (API level 27) is as\nfollows:\nhttps://developer.android.com/training/articles/security-config.html\nPage 9 of 14\n\nThe default configuration for apps targeting Android 6.0 (API level 23) and lower is as follows:\nsyntax:\n...\ncan contain:\n1 or more 0 or 1 0 or 1 0 or 1 0 or 1 Any number of nested description:\nConfiguration used for connections to specific destinations, as defined by the domain elements.\nNote that if multiple domain-config elements cover a destination, the configuration with the most\nspecific (longest) matching domain rule is used.\nsyntax:\nexample.com attributes:\nhttps://developer.android.com/training/articles/security-config.html\nPage 10 of 14\n\nincludeSubdomains\nIf \"true\" , then this domain rule matches the domain and all subdomains, including subdomains of\nsubdomains. Otherwise, the rule only applies to exact matches.\nsyntax:\ndescription:\nIf true , then the app will use the Certificate Transparency logs to validate certificates. When an app uses\nits own certificate (or the user store), it is likely that the certificate is not public and therefore not verifiable\nusing certificate transparency. By default, the verification is disabled for these cases. It is still possible to\nforce the verification using in the domain configuration.\nFor each , the evaluation follows this order:\n1. If certificateTransparency is enabled, enable the verification.\n2. If any is \"user\" or inline (i.e., \"@raw/cert.pem\" ), disable the verification.\n3. Otherwise, rely on the inherited configuration.\nsyntax:\ndescription:\nControls Encrypted Client Hello (ECH) behavior for connections to the specified domains.\nNote: The domainEncryption element depends on the app's networking library supporting ECH. The\nspecified behavior only takes effect if the networking library has adopted ECH. Apps are not expected to\nhandle ECH configurations themselves and should instead rely on their networking libraries to do so when\nestablishing the TLS handshake.\nThe mode attribute can be one of the following:\nenabled : Enforce ECH on a connection when the ECH configuration is provided when\nestablishing the TLS handshake, and enable ECH GREASE otherwise.\nopportunistic : Use ECH on a connection when the ECH configuration is provided when\nestablishing the TLS handshake. If the connection fails or the configuration was not provided, fall\nback to a standard non-encrypted TLS ClientHello. This mode does not enable ECH GREASE.\ndisabled : Don't attempt to use ECH or ECH GREASE on any connections.\nIf not specified, the default mode is \"opportunistic\" .\nhttps://developer.android.com/training/articles/security-config.html\nPage 11 of 14\n\nsyntax:\n...\ncan contain:\n0 or 1 description:\nOverrides to be applied when android:debuggable is \"true\" , which is normally the case for non-release\nbuilds generated by IDEs and build tools. Trust anchors specified in debug-overrides are added to all\nother configurations, and certificate pinning is not performed when the server's certificate chain uses one of\nthese debug-only trust anchors. If android:debuggable is \"false\" , then this section is completely ignored.\nsyntax:\n...\ncan contain:\nAny number of description:\nSet of trust anchors for secure connections.\nsyntax:\ndescription:\nSet of X.509 certificates for trust-anchors elements.\nattributes:\nsrc\nThe source of CA certificates. Each certificate can be one of the following:\na raw resource ID pointing to a file containing X.509 certificates. Certificates must be\nencoded in DER or PEM format. In the case of PEM certificates, the file must not contain\nextra non-PEM data such as comments.\nhttps://developer.android.com/training/articles/security-config.html\nPage 12 of 14\n\n\"system\" for the pre-installed system CA certificates\r\n\"user\" for user-added CA certificates\r\noverridePins\r\nSpecifies if the CAs from this source bypass certificate pinning. If \"true\" , then pinning is not\r\nperformed on certificate chains which are signed by one of the CAs from this source. This can be\r\nuseful for debugging CAs or for testing man-in-the-middle attacks on your app's secure traffic.\r\nDefault is \"false\" unless specified in a debug-overrides element, in which case the default is\r\n\"true\" .\r\n\u003cpin-set\u003e\r\nsyntax:\r\n\u003cpin-set expiration=\"date\"\u003e\r\n...\r\n\u003c/pin-set\u003e\r\ncan contain:\r\nAny number of \u003cpin\u003e\r\ndescription:\r\nA set of public key pins. For a secure connection to be trusted, one of the public keys in the chain of trust\r\nmust be in the set of pins. See \u003cpin\u003e for the format of pins.\r\nattributes:\r\nexpiration\r\nThe date, in yyyy-MM-dd format, on which the pins expire, thus disabling pinning. If the attribute is\r\nnot set, then the pins do not expire.\r\nExpiration helps prevent connectivity issues in apps which do not get updates to their pin set, such\r\nas when the user disables app updates.\r\n\u003cpin\u003e\r\nsyntax:\r\n\u003cpin digest=[\"SHA-256\"]\u003ebase64 encoded digest of X.509\r\n SubjectPublicKeyInfo (SPKI)\u003c/pin\u003e\r\nattributes:\r\ndigest\r\nThe digest algorithm used to generate the pin. Currently, only \"SHA-256\" is supported.\r\nhttps://developer.android.com/training/articles/security-config.html\r\nPage 13 of 14\n\nSource: https://developer.android.com/training/articles/security-config.html\r\nhttps://developer.android.com/training/articles/security-config.html\r\nPage 14 of 14",
	"extraction_quality": 1,
	"language": "EN",
	"sources": [
		"MITRE"
	],
	"origins": [
		"web"
	],
	"references": [
		"https://developer.android.com/training/articles/security-config.html"
	],
	"report_names": [
		"security-config.html"
	],
	"threat_actors": [
		{
			"id": "aa73cd6a-868c-4ae4-a5b2-7cb2c5ad1e9d",
			"created_at": "2022-10-25T16:07:24.139848Z",
			"updated_at": "2026-04-10T02:00:04.878798Z",
			"deleted_at": null,
			"main_name": "Safe",
			"aliases": [],
			"source_name": "ETDA:Safe",
			"tools": [
				"DebugView",
				"LZ77",
				"OpenDoc",
				"SafeDisk",
				"TypeConfig",
				"UPXShell",
				"UsbDoc",
				"UsbExe"
			],
			"source_id": "ETDA",
			"reports": null
		}
	],
	"ts_created_at": 1775434602,
	"ts_updated_at": 1775826747,
	"ts_creation_date": 0,
	"ts_modification_date": 0,
	"files": {
		"pdf": "https://archive.orkl.eu/8f94b41fe5b11c24b470eeb9a543644d665778de.pdf",
		"text": "https://archive.orkl.eu/8f94b41fe5b11c24b470eeb9a543644d665778de.txt",
		"img": "https://archive.orkl.eu/8f94b41fe5b11c24b470eeb9a543644d665778de.jpg"
	}
}