Property List Key

NSExceptionDomains

Custom configurations for App Transport Security named domains.

Details

Name
Exception Domains
Type
dictionary

Discussion

The value for this key is a dictionary with keys that name specific domains for which you want to set exceptions. The value for each domain key is another dictionary that indicates the exceptions for that domain.

NSExceptionDomains : Dictionary {
    <domain-name-string> : Dictionary {
        NSIncludesSubdomains : Boolean
        NSExceptionAllowsInsecureHTTPLoads : Boolean
        NSExceptionMinimumTLSVersion : String
        NSExceptionRequiresForwardSecrecy : Boolean
        NSRequiresCertificateTransparency : Boolean
    }
}

Follow these rules when setting a domain name string:

  • Use lowercase. Use example.com, not EXAMPLE.COM.

  • Don’t include a port number. Use example.com, not example.com:443.

  • Don’t use numerical IP addresses. Don’t use 1.2.3.4. For information about how ATS handles IP addresses, see NSAllowsLocalNetworking.

  • Don’t include a trailing dot, unless you only want to match a domain string with a trailing dot. For example, example.com. (with a trailing dot) matches “example.com.” but not “example.com”. Similarly, example.com matches “example.com” but not “example.com.”.

The values for the keys in each individual domain’s dictionary control how ATS treats connections made to that domain.

NSIncludesSubdomains

Set the value for this key to YES to apply the ATS exceptions for the given domain to all subdomains of the domain.

For example, if you set this value to YES and the domain name string is example.com, then the ATS exceptions in the domain exception dictionary apply to example.com, as well as math.example.com, history.example.com, and so on. Otherwise, if the value is NO, the exceptions apply only to example.com.

This key is optional. The default value is NO.

NSExceptionAllowsInsecureHTTPLoads

Set the value for this key to YES to allow insecure HTTP loads for the given domain, or to be able to loosen the server trust evaluation requirements for HTTPS connections to the domain, as described in Performing Manual Server Trust Authentication.

Using this key doesn’t by itself change default server trust evaluation requirements for HTTPS connections, described in Ensure the Network Server Meets Minimum Requirements. Using only this key also doesn’t change the TLS or forward secrecy requirements imposed by ATS. As a result, you might need to combine this key with the NSExceptionMinimumTLSVersion or NSExceptionRequiresForwardSecrecy key in certain cases.

This key is optional. The default value is NO.

NSExceptionMinimumTLSVersion

Set the value of this key to specify the minimum Transport Layer Security (TLS) version for network connections.

This key is optional. The value is a string, with a default value of TLSv1.2. Possible values are:

  • TLSv1.0

  • TLSv1.1

  • TLSv1.2

  • TLSv1.3

NSExceptionRequiresForwardSecrecy

Set the value for this key to NO to override the requirement that a server support perfect forward secrecy (PFS) for the given domain. Disabling this requirement also removes the key length check described in Ensure the Network Server Meets Minimum Requirements. However, it doesn’t impact the TLS version requirement. To control that, use NSExceptionMinimumTLSVersion.

This key is optional. The default value is YES, which limits the accepted ciphers to those that support PFS through Elliptic Curve Diffie-Hellman Ephemeral (ECDHE) key exchange.

NSRequiresCertificateTransparency

Certificate Transparency (CT) is a protocol that ATS can use to identify mistakenly or maliciously issued X.509 certificates. Set the value for the NSRequiresCertificateTransparency key to YES to require that for a given domain, server certificates are supported by valid, signed CT timestamps from at least two CT logs trusted by Apple. For more information about Certificate Transparency, see RFC6962.

Unlike most other ATS exceptions, using a non-default value in this case tightens security requirements.

This key is optional. The default value is NO.