Managing App Transport Security — iOS & macOS

Overview

With each major upgrade of its operating systems, Apple introduces new features which all iOS and macOS developers must be aware of. In iOS 9 and macOS 10.11, a particularly important feature known as App Transport Security was introduced, hereafter referred to as ATS.

Essentially, ATS is Apple’s new guard against insecure HTTP and weaker/older HTTPS connections. Apple suggests that you adopt ATS as soon as possible, regardless of whether you’re creating a new app or updating an existing one. The intent is to protect your app’s users from exploits inherent in older Internet protocols, so the best approach is always to work with it rather than just turn it off (an option that Apple will remove in the near future anyway).

For comprehensive details and usage specifications for ATS, please see Apple’s documentation.

Prerequisites

ATS applies to both iOS and macOS apps which meet these criteria:

• All apps which use high-level network-related APIs (socket level APIs are not affected).
• iOS apps built to target the iOS 9 SDK or higher.
• macOS apps built to target macOS 10.11 or higher.

Valid Connections

The following conditions must be met for a connection to be allowed through ATS:

• HTTPS must be used to connect to the server.
• The server must support TLS v1.2 or higher.
• Certificates must be valid and signed using SHA256 or better. They must also use a 2048-bit or greater RSA key or a 256-bit or greater Elliptic Curve key. Any up-to-date certificate should meet these criteria.

Configuring Connections

ATS can be configured to manage certain specific endpoints that do not meet the valid connections requirements outlined above. The following steps outline this process:

1. Configuring ATS begins with the addition of the NSAppTransportSecurity key-value pair within the iphone → plist table of your app’s build.settings file (guide):

settings =
{
    iphone =
    {
        plist =
        {
            NSAppTransportSecurity =
            {

            },
        },
    },
}

2. Inside the NSAppTransportSecurity table, add a NSExceptionDomains key-value pair. This allows you to specify ATS exceptions for specific domains.

NSAppTransportSecurity =
{
    NSExceptionDomains =
    {

    },
},

3. Inside the NSExceptionDomains table, include distinct key-value pairs to describe domain-specific network connection configuration exceptions. An exception domain’s top-level key is the domain name string for which you want to specify a connection configuration. Because of Lua naming convention rules, you will typically need to specify these names within brackets/quotes, for instance ["example.com"].

NSAppTransportSecurity =
{
    NSExceptionDomains =
    {
        ["example.com"] =
        {

        },
    },
},

4. Finally, to configure the exception domain, include key-value pairs which describe server-specific exceptions to your app’s overall intended network behavior. For instance:

NSAppTransportSecurity =
{
    NSExceptionDomains =
    {
        ["example.com"] =
        {
            NSIncludesSubdomains = true,
            NSThirdPartyExceptionAllowsInsecureHTTPLoads = true,
        },
    },
},

5. Putting it together, an example ATS configuration block within build.settings may be structured like this:

settings =
{
    iphone =
    {
        plist =
        {
            NSAppTransportSecurity =
            {
                NSExceptionDomains =
                {
                    ["example.com"] =
                    {
                        NSIncludesSubdomains = true,
                        NSThirdPartyExceptionAllowsInsecureHTTPLoads = true,
                    },
                },
            },
        },
    },
}

NSAppTransportSecurity =
{
    NSAllowsArbitraryLoads = true,
},

Corona Simulator

Since the Corona Simulator on macOS must simulate all types of devices, including those that do not implement ATS, it turns it off for all connections.