Cocoa Keys

Cocoa and Cocoa Touch are the environments used to define Objective-C based apps that run in OS X and iOS respectively. The keys associated with the Cocoa environments provide support for Interface Builder nib files and provide support for other user-facing features vended by your bundle.

Cocoa keys use the prefix NS to distinguish them from other keys. For information about developing Cocoa Touch apps for iOS, see iOS App Programming Guide. For information about developing Cocoa apps for OS X, see Cocoa Fundamentals Guide.

Key Summary

Table 1 contains an alphabetical listing of Cocoa keys, the corresponding name for that key in the Xcode property list editor, a high-level description of each key, and the platforms on which you use it. Detailed information about each key is available in later sections.

Table 1  Summary of Cocoa keys

Key

Xcode name

Summary

Platforms

GKGameCenterBadgingDisabled

(none)

Specifies whether your app is badged. See GKGameCenterBadgingDisabled for details.

iOS 7.0 and later

GKShowChallengeBanners

(none)

Specifies whether banners are shown within an app. See GKShowChallengeBannersfor details.

iOS 7.0 and later

NETestAppMapping

(none)

Enables testing of per-app VPN app extensions without using an MDM server. See NETestAppMapping for details.

iOS 9.0 and later, OS X v10.11 and later

NSAppleScriptEnabled

“Scriptable”

Specifies whether AppleScript is enabled. See NSAppleScriptEnabled for details.

OS X

NSAppTransportSecurity

(none)

Specifies exceptions to the default strong Internet security in iOS and OS X apps and in app extensions. See NSAppTransportSecurity for details.

iOS 9.0 and later, OS X v10.11 and later

NSBluetoothPeripheralUsageDescription

“Privacy - Bluetooth Peripheral Usage Description”

Specifies the reason for using Bluetooth. See NSBluetoothPeripheralUsageDescription for details.

iOS 6.0 and later

NSCalendarsUsageDescription

“Privacy - Calendars Usage Description”

Specifies the reason for accessing the user’s calendars. See NSCalendarsUsageDescription for details.

iOS 6.0 and later

NSCameraUsageDescription

“Privacy - Camera Usage Description”

Specifies the reason for accessing the device’s camera. See NSLocationAlwaysUsageDescription for details.

iOS 7.0 and later

NSContactsUsageDescription

“Privacy - Contacts Usage Description”

Specifies the reason for accessing the user’s contacts. See NSContactsUsageDescription for details.

iOS 6.0 and later, OS X v10.8 and later

NSDockTilePlugIn

”Dock Tile Plugin path”

Specifies the name of app’s Dock tile plug-in, if present. See NSDockTilePlugIn for details.

OS X

NSHumanReadableCopyright

“Copyright (human-readable)”

(Localizable) Specifies the copyright notice for the bundle. See NSHumanReadableCopyright for details.

OS X

NSJavaNeeded

“Cocoa Java application”

Specifies whether the program requires a running Java VM. See NSJavaNeeded for details.

OS X

NSJavaPath

“Java classpaths”

An array of paths to classes whose components are preceded by NSJavaRoot. See NSJavaPath for details.

OS X

NSJavaRoot

“Java root directory”

The root directory containing the java classes. See NSJavaRoot for details.

OS X

NSLocationAlwaysUsageDescription

(none)

Specifies the reason for accessing the user’s location information. See NSLocationAlwaysUsageDescription for details.

iOS 8.0 and later, OS X v10.10 and later

NSLocationUsageDescription

“Privacy - Location Usage Description”

Specifies the reason for accessing the user’s location information. See NSLocationUsageDescription for details.

iOS 6.0 and later, OS X v10.9 and later

NSLocationWhenInUseUsageDescription

(none)

Specifies the reason for accessing the user’s location information. See NSLocationWhenInUseUsageDescription for details.

iOS 8.0 and later, OS X v10.10 and later

NSMainNibFile

“Main nib file base name”

The name of an app’s main nib file. See NSMainNibFile for details.

iOS, OS X

NSMicrophoneUsageDescription

“Privacy - Microphone Usage Description”

Specifies the reason for accessing the device’s microphone. See NSCalendarsUsageDescription for details.

iOS 7.0 and later

NSMotionUsageDescription

“Privacy - Motion Usage Description”

Specifies the reason for accessing the device’s accelerometer. See NSMotionUsageDescription for details.

iOS 7.0 and later

NSPersistentStoreTypeKey

“Core Data persistent store type”

The type of Core Data persistent store associated with a persistent document type. See NSPersistentStoreTypeKey for details.

OS X

NSPhotoLibraryUsageDescription

“Privacy - Photo Library Usage Description”

Specifies the reason for accessing the user’s photo library. See NSPhotoLibraryUsageDescription for details.

iOS 6.0 and later

NSPrefPaneIconFile

“Preference Pane icon file”

The name of an image file resource used to represent a preference pane in the System Preferences app. See NSPrefPaneIconFile for details.

OS X

NSPrefPaneIconLabel

“Preference Pane icon label”

The name of a preference pane displayed beneath the preference pane icon in the System Preferences app. See NSPrefPaneIconLabel for details.

OS X

NSPrincipalClass

“Principal class”

The name of the bundle’s main class. See NSPrincipalClass for details.

OS X

NSRemindersUsageDescription

“Privacy - Reminders Usage Description”

Specifies the reason for accessing the user’s reminders. See NSRemindersUsageDescription for details.

iOS 6.0 and later

NSServices

“Services”

An array of dictionaries specifying the services provided by an app. See NSServices for details.

OS X

NSSupportsAutomaticTermination

(none)

Specifies whether the app may be killed to reclaim memory. See NSSupportsAutomaticTermination for details.

OS X v10.7 and later

NSSupportsPurgeableLocalStorage

(none)

Declares that the app can depend on nonlocal storage for user data. See NSSupportsPurgeableLocalStorage for details.

iOS 9.3 and later

NSSupportsSuddenTermination

(none)

Specifies whether the app may be killed to allow for faster shut down or log out operations. See NSSupportsSuddenTermination for details.

OS X

NSUbiquitousContainer

(none)

Specifies the iCloud Drive settings for each container. See NSUbiquitousContainers for details.

iOS, OS X

NSUbiquitousContainerIsDocumentScopePublic

(none)

Specifies whether the iCloud Drive should share the contents of this container. See NSUbiquitousContainerIsDocumentScopePublic for details.

iOS, OS X

NSUbiquitousContainerName

(none)

Specifies the name that the iCloud Drive displays for your container. See NSUbiquitousContainerName for details.

iOS, OS X

NSUbiquitousContainerSupportedFolderLevels

(none)

Specifies the maximum number of folder levels inside your container’s Documents directory. See NSUbiquitousContainerSupportedFolderLevels for details.

iOS, OS X

NSUbiquitousDisplaySet

(none)

Specifies the mobile document data that the app can view. See NSUbiquitousDisplaySet for details.

iOS, OS X

NSUserActivityTypes

(none)

Specifies the user activity types that the app supports. See NSUserActivityTypes for details.

iOS, OS X

NSUserNotificationAlertStyle

(none)

Specifies whether the notification style should be banner, alert, or none. The default value is banner, which is the recommended style. See NSUserNotificationAlertStyle for details.

OS X

UTExportedTypeDeclarations

“Exported Type UTIs”

An array of dictionaries specifying the UTI-based types supported (and owned) by the app. See UTExportedTypeDeclarations for details.

iOS 5.0 and later, OS X v10.7 and later

UTImportedTypeDeclarations

“Imported Type UTIs”

An array of dictionaries specifying the UTI-based types supported (but not owned) by the app. See UTImportedTypeDeclarations for details.

iOS, OS X

GKGameCenterBadgingDisabled

GKGameCenterBadgingDisabled (Boolean - iOS). This key determines if badges are added to your turn based app icon. Set the value of this key to YES to opt out of badging. Defaults to NO.

GKShowChallengeBanners

GKShowChallengeBanners (Boolean - iOS). This key determines if challenge banners are displayed within an app. Set the value of this key to YES to show challenge banners in the app. Set the value to NO to suppress challenge-related banners.

NETestAppMapping

NETestAppMapping (Dictionary - iOS, OS X) Use this key only during development and testing to help you create a per-app VPN app extension. By using this key, you can test per-app VPN communication without the use of a mobile device management (MDM) server. For more information, refer to NETunnelProviderManager Class Reference.

NSAppleScriptEnabled

NSAppleScriptEnabled (Boolean or String - OS X). This key identifies whether the app is scriptable. Set the value of this key to true (when typed as Boolean) or “YES” (when typed as String) if your app supports AppleScript.

NSAppTransportSecurity

NSAppTransportSecurity (Dictionary - iOS, OS X) Use this key to describe your app’s intended HTTP connection behavior if you require exceptions from best security practices.

Starting in iOS 9.0 and OS X v10.11, a new security feature called App Transport Security (ATS) is available to apps and is enabled by default. It improves the privacy and data integrity of connections between an app and web services by enforcing additional security requirements for HTTP-based networking requests. Specifically, with ATS enabled, HTTP connections must use HTTPS (RFC 2818). Attempts to connect using insecure HTTP fail. Furthermore, HTTPS requests must use best practices for secure communications.

The NSAppTransportSecurity key is supported in iOS 9.0 and later and in OS X v10.11 and later, and is available in app extensions.

ATS employs the Transport Layer Security (TLS) protocol version 1.2 (RFC 5246).

For background on secure Internet connections, read HTTPS Server Trust Evaluation.

ATS is enforced by the NSURLSession class and all APIs that use it. ATS is automatically enabled when you link your app against the iOS 9.0 SDK or later or against the OS X v10.11 SDK or later. (The older NSURLConnection class also enforces ATS when you link against the iOS 9.0 SDK or later or against the OS X v10.11 SDK or later.)

If you disable ATS, either globally or for a specific domain, the system still provides standard HTTPS security: If your app makes an HTTPS request the system performs server trust evaluation per RFC 2818.

If your app uses secure network connections exclusively and those connections use best-practice networking properties, you do not need to employ the NSAppTransportSecurity key.

If you link your app against an SDK for an operating system older than iOS 9.0 or OS X v10.11, your Internet connections continue to work but ATS is disabled, no matter which version of the operating system your app is running on. ATS is not available on operating systems older than iOS 9.0 or OS X v10.11; those older operating systems ignore the NSAppTransportSecurity key.

The following listing represents the overall structure of the NSAppTransportSecurity dictionary, showing all possible keys (all of which are optional). Keep this structure in mind as you configure each element of the NSAppTransportSecurity dictionary:

NSAppTransportSecurity : Dictionary {
    NSExceptionDomains : Dictionary {
        <domain-name-string> : Dictionary {
            NSIncludesSubdomains : Boolean
            // Keys to describe your app’s intended network behavior for
            //    domains whose security attributes you control
            NSExceptionAllowsInsecureHTTPLoads : Boolean
            NSExceptionRequiresForwardSecrecy : Boolean
            NSExceptionMinimumTLSVersion : String
            // Keys to describe your app’s intended network behavior for
            //    domains whose security attributes you don't control
            NSThirdPartyExceptionAllowsInsecureHTTPLoads : Boolean
            NSThirdPartyExceptionRequiresForwardSecrecy : Boolean
            NSThirdPartyExceptionMinimumTLSVersion : String
        }
    }
    NSAllowsArbitraryLoads : Boolean
}

Table 2 shows the primary keys within the NSAppTransportSecurity dictionary for describing your app’s intended network behavior. For the sub-keys associated with the NSExceptionDomains dictionary, see Table 3.

Table 2  App Transport Security dictionary primary keys

Key

Xcode name

Type

Description

NSExceptionDomains

“Exception Domains”

Dictionary

An optional dictionary of ATS exceptions for specific domains. Each value in the dictionary is itself a dictionary, and describes a domain-specific network connection configuration exception.

An exception domain’s top-level key is the domain name string for which you want to specify a connection configuration; for example, www.apple.com. A domain name key for an exception dictionary:

  • Must be lowercased to work correctly

  • Must not include a port number

  • Must not be a numerical IP address (but rather a string)

  • Must not end with a trailing dot, unless you only want to match a domain string with a trailing dot. For example, https://example.com. (with a trailing dot) matches “example.com.” but not “example.com”. Similarly, https://example.com matches “example.com” but not “example.com.”.

For details on configuring an exception domain dictionary, see Table 3.

NSAllowsArbitraryLoads

“Allow Arbitrary Loads”

Boolean

An optional Boolean value that, when set to YES, disables App Transport Security (ATS) for any domains for which you do not reenable ATS by using an exception domain dictionary.

Enable this key for cases where your app allows the user to specify connection to an arbitrary URL.

Enabling this key can also be useful for debugging and development purposes.

NOTE Disabling ATS allows connection regardless of HTTP or HTTPS configuration, allows connection to servers with lower TLS versions, and allows connection using cipher suites that do not support forward secrecy (FS).

This key’s default value of NO results in default ATS behavior for all connections except those for which you have specified an exception domain dictionary (see Table 3).

Table 3 shows the keys for describing server-specific exceptions to your app’s overall intended network behavior. Use an exception domain dictionary, as needed, to configure the connection behavior for a specific server, in either of the two following ways:

Table 3  Exception domains dictionary keys

Key

Xcode name

Type

Description

NSIncludesSubdomains

(none)

Boolean

An optional Boolean value that, when set to YES, applies the NSExceptionDomains ATS exceptions to all subdomains (of the domain whose name is the top-level key in the NSExceptionDomains dictionary).

Default value is NO.

NSExceptionAllowsInsecureHTTPLoads

(none)

Boolean

An optional Boolean value that, when set to YES, allows insecure HTTP loads. Use this key to describe your app’s intended network behavior for a domain whose security attributes you have control over. See also NSThirdPartyExceptionAllowsInsecureHTTPLoads.

With this key’s value set to YES, your app can make secure connections to a secure server but can also connect insecurely to a server with no certificate, or a self-signed, expired, or hostname-mismatched certificate.

Set this key’s value to YES, if needed, to:

  • Enable connection to an insecure HTTP server

  • Enable connection to an untrusted HTTPS server

  • Enable connection to an HTTPS server for which you want to perform your own server trust evaluation

In some cases you need to use other exception-dictionary keys along with this one to establish connection. For example, to connect to an HTTPS server that uses a self-signed certificate and a TLS version lower than 1.2, set the NSExceptionAllowsInsecureHTTPLoads value to YES and also set an appropriate value for the NSExceptionMinimumTLSVersion key.

Default value is NO.

NSExceptionRequiresForwardSecrecy

(none)

Boolean

An optional Boolean value for overriding the requirement that a server support forward secrecy (FS). Use this key to describe your app’s intended network behavior for a domain whose security attributes you have control over. See also NSThirdPartyExceptionRequiresForwardSecrecy.

Default value is YES, which limits the accepted ciphers to those listed in Requirements for Connecting Using ATS.

Setting the value to NO results in the following ciphers, which do not support FS, also being accepted:

  • TLS_RSA_WITH_AES_256_GCM_SHA384

  • TLS_RSA_WITH_AES_128_GCM_SHA256

  • TLS_RSA_WITH_AES_256_CBC_SHA256

  • TLS_RSA_WITH_AES_256_CBC_SHA

  • TLS_RSA_WITH_AES_128_CBC_SHA256

  • TLS_RSA_WITH_AES_128_CBC_SHA

NSExceptionMinimumTLSVersion

(none)

String

An optional string value that specifies the minimum Transport Layer Security (TLS) version for connections. Use this key to describe your app’s intended network behavior for a domain whose security attributes you have control over. See also NSThirdPartyExceptionMinimumTLSVersion.

Valid values are:

  • TLSv1.0

  • TLSv1.1

  • TLSv1.2

Default value is TLSv1.2.

NSThirdPartyExceptionAllowsInsecureHTTPLoads

(none)

Boolean

A version of the NSExceptionAllowsInsecureHTTPLoads key to be used to configure connections to a domain whose security attributes you don’t control.

NSThirdPartyExceptionRequiresForwardSecrecy

(none)

Boolean

A version of the NSExceptionRequiresForwardSecrecy key to be used to configure connections to a domain whose security attributes you don’t control.

NSThirdPartyExceptionMinimumTLSVersion

(none)

String

A version of the NSExceptionMinimumTLSVersion key to be used to configure connections to a domain whose security attributes you don’t control.

Requirements for Connecting Using ATS

With ATS fully enabled, your app’s HTTP connections must use HTTPS and must satisfy the following security requirements:

  • The server certificate must meet at least one of the following trust requirements:

    • Issued by a certificate authority (CA) whose root certificate is incorporated into the operating system

    • Issued by a trusted root CA and installed by the user or a system administrator

  • The negotiated Transport Layer Security version must be TLS 1.2

  • The negotiated TLS connection cipher suite must support forward secrecy (FS) and be one of the following:

    • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

    • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

    • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384

    • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

    • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256

    • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA

    • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

    • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

    • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

    • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

    • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

  • The leaf server certificate must be signed with one of the following types of keys:

    • Rivest-Shamir-Adleman (RSA) key with a length of at least 2048 bits

    • Elliptic-Curve Cryptography (ECC) key with a size of at least 256 bits

    In addition, the leaf server certificate hashing algorithm must be Secure Hash Algorithm 2 (SHA-2) with a digest length of at least 256 (that is, SHA-256 or greater).

If ATS is not enabled, the system still performs HTTPS server trust evaluation but you can override it on a case-by-case basis, as described in HTTPS Server Trust Evaluation. With ATS fully enabled, you cannot override the default HTTPS server trust evaluation.

The requirements listed in this section are current as of this document’s publication date, with stricter requirements possible in the future. Changes to these requirements will not break app binary compatibility.

Examples of Specifying Intended Network Behavior

This section shows how to specify some common networking behaviors using the NSAppTransportSecurity key.

Allowing Insecure Connection to a Single Server

To use ATS generally but allow connection to a specific server that does not support the HTTPS protocol—for example, a media server that your app uses—employ the following configuration pattern in your Info.plist file:

NSAppTransportSecurity
    NSExceptionDomains
        "media-server.example.com"
            NSExceptionAllowsInsecureHTTPLoads = YES

Allowing Lowered Security to a Single Server

To use a less-secure HTTPS connection to a specified server that uses an older version of TLS and that does not support forward secrecy, while retaining the default, best-practice ATS behavior elsewhere, employ the following configuration pattern in your Info.plist file:

NSAppTransportSecurity
    NSExceptionDomains
        "less-secure.example.com"
            NSExceptionRequiresForwardSecrecy = NO
            NSExceptionMinimumTLSVersion = "TLSv1.0"

Using ATS For Your Servers and Allowing Insecure Connections Elsewhere

If your app is a web browser, or otherwise allows a user to enter an arbitrary URL, your app must be able to load resources from anywhere. In such a scenario, your app should still use ATS when communicating with servers whose security attributes you control, such as your update server.

To require ATS connections to domains that you control, while allowing insecure HTTP access to all other URLs, employ the following configuration pattern in your Info.plist file:

NSAppTransportSecurity
    NSExceptionDomains
        "domain-i-control.example.com"
            NSExceptionAllowsInsecureHTTPLoads = NO
            NSExceptionRequiresForwardSecrecy = YES
            NSExceptionMinimumTLSVersion = "TLSv1.2"
        "other-domain-i-control.example.com"
            NSExceptionAllowsInsecureHTTPLoads = NO
            NSExceptionRequiresForwardSecrecy = YES
            NSExceptionMinimumTLSVersion = "TLSv1.2"
    NSAllowsArbitraryLoads = YES

Debugging ATS Connections

If you are seeing Internet connection problems that you suspect are related to ATS, try the following troubleshooting approach:

  1. Disable ATS entirely to confirm that ATS is involved with the connection problem. Do this by using the following configuration pattern:

    NSAppTransportSecurity
        NSAllowsArbitraryLoads = YES

    If entirely disabling ATS solves your connection problem, proceed with step 2. (If you still cannot connect with ATS disabled, the problem lies somewhere other than with ATS.)

  2. Test whether a specific domain under your control is causing the connection problem. Do this by reenabling ATS except on that specific domain, using the following configuration pattern:

    NSAppTransportSecurity
        NSAllowsArbitraryLoads = NO  // Shown for clarity; this is the default
        NSExceptionDomains
            "secure-server-i-control.example.com"
            NSExceptionAllowsInsecureHTTPLoads = YES
            NSExceptionRequiresForwardSecrecy = NO
            NSExceptionMinimumTLSVersion = "TLSv1.0"

    If connection continues to work with this configuration, it is likely that the problem lies with the specific domain named in your NSExceptionDomains dictionary.

    If connection fails with this configuration, the problem is likely one of two things:

    • An ATS misconfiguration on the server named in the NSExceptionDomains dictionary

    • An ATS misconfiguration on another server that the connection is redirected to

    Once you have pinpointed the server at blame for the connection problem, proceed with step 3.

  3. Use the TLSTool sample code project to investigate the details of the TLS version, server certificate, and cipher suite the problematic server is using.

    If the new information you’ve gathered allows you to reconfigure the server to support ATS, do so.

    If you are unable to reconfigure the server, use the information you’ve gathered using the TLSTool app to define an appropriate NSExceptionDomains dictionary for that server.

In addition, you can enable logging of NSURLSession class errors by employing the following environment variable in your Xcode project:

CFNETWORK_DIAGNOSTICS=1

For more information about using this environment variable, read CFNetwork Diagnostic Logging. For help interpreting error codes, read Security Framework Error Codes.

Using the nscurl tool to diagnose ATS Connection Issues

In OS X v10.11 and later, you can use the /usr/bin/nscurl tool to help diagnose connection issues due to App Transport Security.

The --ats-diagnostics option tries to connect with the specified URL using different combinations of values for the NSAllowsArbitraryLoads, NSExceptionMinimumTLSVersion, NSExceptionRequiresForwardSecrecy, and NSExceptionAllowsInsecureHTTPLoads keys shown in Table 3. A summary of the results is printed to the command line.

The format for the command is:

/usr/bin/nscurl --ats-diagnostics [--verbose] URL

  • URL. The URL for the host. This is required.

  • verbose. Specifying this option includes more information for each connection attempt including the keys and associated values used.

Listing 1 shows partial output of diagnosing a connection to https://apple.com.

Listing 1  Partial output of nscurl

> /usr/bin/nscurl --ats-diagnostics https://apple.com
Starting ATS Diagnostics
 
Configuring ATS Info.plist keys and displaying the result of HTTPS loads to https://apple.com.
A test will "PASS" if URLSession:task:didCompleteWithError: returns a nil error.
Use '--verbose' to view the ATS dictionaries used and to display the error received in URLSession:task:didCompleteWithError:.
================================================================================
 
Default ATS Secure Connection
---
ATS Default Connection
2015-09-09 09:53:01.592 nscurl[9207:5187047] CFNetwork SSLHandshake failed (-9824)
2015-09-09 09:53:01.593 nscurl[9207:5187047] NSURLSession/NSURLConnection HTTP load failed (kCFStreamErrorDomainSSL, -9824)
Result : FAIL
---
 
================================================================================
 
Allowing Arbitrary Loads
 
---
Allow All Loads
Result : PASS
---
 
================================================================================
 
Configuring TLS exceptions for apple.com
 
---
TLSv1.2
2015-09-09 09:53:02.145 nscurl[9207:5187047] CFNetwork SSLHandshake failed (-9824)
2015-09-09 09:53:02.146 nscurl[9207:5187047] NSURLSession/NSURLConnection HTTP load failed (kCFStreamErrorDomainSSL, -9824)
Result : FAIL
---
 
---
TLSv1.1
2015-09-09 09:53:02.270 nscurl[9207:5187047] CFNetwork SSLHandshake failed (-9824)
2015-09-09 09:53:02.271 nscurl[9207:5187047] NSURLSession/NSURLConnection HTTP load failed (kCFStreamErrorDomainSSL, -9824)
Result : FAIL
---
 
---
TLSv1.0
2015-09-09 09:53:02.407 nscurl[9207:5187047] CFNetwork SSLHandshake failed (-9824)
2015-09-09 09:53:02.408 nscurl[9207:5187047] NSURLSession/NSURLConnection HTTP load failed (kCFStreamErrorDomainSSL, -9824)
Result : FAIL
---
 
================================================================================
 
Configuring PFS exceptions for apple.com

Listing 2 shows partial output when using the--verbose option. The two main differences are showing the values of the keys from Info.plist from lines 10 to 17, and a longer error result shown on line 19.

Listing 2  Partial output of nscurl using --verbose

> /usr/bin/nscurl --ats-diagnostics --verbose https://apple.com
Starting ATS Diagnostics
 
Configuring PFS exceptions and allowing insecure HTTP for apple.com
 
---
Disabling Perfect Forward Secrecy and Allowing Insecure HTTP
ATS Dictionary:
{
    NSExceptionDomains =     {
        "apple.com" =         {
            NSExceptionAllowsInsecureHTTPLoads = true;
            NSExceptionRequiresForwardSecrecy = false;
        };
    };
}
Result : FAIL
Error : Error Domain=NSURLErrorDomain Code=-1022 "The resource could not be loaded because the App Transport Security policy requires the use of a secure connection." UserInfo={NSUnderlyingError=0x7fc6a9d11900 {Error Domain=kCFErrorDomainCFNetwork Code=-1022 "(null)"}, NSErrorFailingURLStringKey=http://www.apple.com/apple-events/september-2015/, NSErrorFailingURLKey=http://www.apple.com/apple-events/september-2015/, NSLocalizedDescription=The resource could not be loaded because the App Transport Security policy requires the use of a secure connection.}
---

NSBluetoothPeripheralUsageDescription

NSBluetoothPeripheralUsageDescription (String - iOS) This key describes the reason that the app uses Bluetooth. When the system prompts the user to allow usage, this string is displayed as part of the dialog box.

This key is supported in iOS 6.0 and later.

NSCalendarsUsageDescription

NSCalendarsUsageDescription (String - iOS) describes the reason that the app accesses the user’s calendars. When the system prompts the user to allow access, this string is displayed as part of the dialog box.

This key is supported in iOS 6.0 and later.

NSCameraUsageDescription

NSCameraUsageDescription (String - iOS) describes the reason that the app accesses the device’s camera. When the system prompts the user to allow access, this string is displayed as part of the dialog box.

This key is supported in iOS 7.0 and later.

NSContactsUsageDescription

NSContactsUsageDescription (String - iOS) describes the reason that the app accesses the user’s contacts. When the system prompts the user to allow access, this string is displayed as part of the dialog box.

This key is supported in iOS 6.0 and later.

NSDockTilePlugIn

NSDockTilePlugIn (String - OS X). This key contains the name of a plug-in bundle with the .docktileplugin filename extension and residing in the app’s Contents/PlugIns directory. The bundle must contain the Dock tile plug-in for the app. For information about creating a Dock tile plug-in, see Dock Tile Programming Guide.

NSHumanReadableCopyright

NSHumanReadableCopyright (String - OS X). This key contains a string with the copyright notice for the bundle; for example, © 2008, My Company. You can load this string and display it in an About dialog box. This key can be localized by including it in your InfoPlist.strings files. This key replaces the obsolete CFBundleGetInfoString key.

NSJavaNeeded

NSJavaNeeded (Boolean or String - OS X). This key specifies whether the Java VM must be loaded and started up prior to executing the bundle code. This key is required only for Cocoa Java apps to tell the system to launch the Java environment. If you are writing a pure Java app, do not include this key.

You can also specify a string type with the value “YES” instead of a Boolean value if desired.

Deprecated in OS X v10.5.

NSJavaPath

NSJavaPath (Array - OS X). This key contains an array of paths. Each path points to a Java class. The path can be either an absolute path or a relative path from the location specified by the key NSJavaRoot. The development environment (or, specifically, its jamfiles) automatically maintains the values in the array.

Deprecated in OS X v10.5.

NSJavaRoot

NSJavaRoot (String - OS X). This key contains a string identifying a directory. This directory represents the root directory of the app’s Java class files.

NSLocationAlwaysUsageDescription

NSLocationAlwaysUsageDescription (String - iOS) describes the reason why the app accesses the user’s location information. Include this key when your app uses location services in a potentially nonobvious way while running in the foreground or the background. For example, a social app might include this key when it uses location information to track the user’s location and display other users that are nearby. In this case, the fact that the app is tracking the user’s location might not be readily apparent. The system includes the value of this key in the alert panel displayed to the user when requesting permission to use location services.

This key is required when you use the requestAlwaysAuthorization method of the CLLocationManager class to request authorization for location services. If this key is not present and you call the requestAlwaysAuthorization method, the system ignores your request and prevents your app from using location services.

This key is supported in iOS 8.0 and later. If your Info.plist file includes both this key and the NSLocationUsageDescription key, the system uses this key and ignores the NSLocationUsageDescription key.

NSLocationUsageDescription

NSLocationUsageDescription (String - iOS) describes the reason why the app accesses the user’s location information. When the system prompts the user to allow access, this string is displayed as part of the alert panel.

This key is supported in iOS 6.0 and later and is ignored in iOS 8 and later. In iOS 8, you must use the NSLocationAlwaysUsageDescription or NSLocationWhenInUseUsageDescription key instead.

NSLocationWhenInUseUsageDescription

NSLocationWhenInUseUsageDescription (String - iOS) describes the reason why the app accesses the user’s location normally while running in the foreground. Include this key when your app uses location services to track the user’s current location directly. This key does not support using location services to monitor regions or monitor the user’s location using the significant location change service. The system includes the value of this key in the alert panel displayed to the user when requesting permission to use location services.

This key is required when you use the requestWhenInUseAuthorization method of the CLLocationManager class to request authorization for location services. If the key is not present when you call the requestWhenInUseAuthorization method without including this key, the system ignores your request.

This key is supported in iOS 8.0 and later. If your Info.plist file includes both this key and the NSLocationUsageDescription key, the system uses this key and ignores the NSLocationUsageDescription key.

NSMainNibFile

NSMainNibFile (String - iOS, OS X). This key contains a string with the name of the app’s main nib file (minus the .nib extension). A nib file is an Interface Builder archive containing the description of a user interface along with any connections between the objects of that interface. The main nib file is automatically loaded when an app is launched.

This key is mutually exclusive with the UIMainStoryboardFile key. You should include one of the keys in your Info.plist file but not both.

NSMicrophoneUsageDescription

NSMicrophoneUsageDescription (String - iOS) describes the reason that the app accesses the device’s microphone. When the system prompts the user to allow access, this string is displayed as part of the dialog box.

This key is supported in iOS 7.0 and later.

NSMotionUsageDescription

NSMotionUsageDescription (String - iOS) describes the reason that the app accesses the device’s accelerometer. When the system prompts the user to allow access, this string is displayed as part of the dialog box.

This key is supported in iOS 7.0 and later.

NSPersistentStoreTypeKey

NSPersistentStoreTypeKey (String - OS X). This key contains a string that specifies the type of Core Data persistent store associated with a document type (see CFBundleDocumentTypes).

NSPhotoLibraryUsageDescription

NSPhotoLibraryUsageDescription (String - iOS) describes the reason that the app accesses the user’s photo library. When the system prompts the user to allow access, this string is displayed as part of the dialog box.

This key is supported in iOS 6.0 and later.

NSPrefPaneIconFile

NSPrefPaneIconFile (String - OS X). This key contains a string with the name of an image file (including extension) containing the preference pane’s icon. This key should only be used by preference pane bundles. The image file should contain an icon 32 by 32 pixels in size. If this key is omitted, the System Preferences app looks for the image file using the CFBundleIconFile key instead.

NSPrefPaneIconLabel

NSPrefPaneIconLabel (String - OS X). This key contains a string with the name of a preference pane. This string is displayed below the preference pane’s icon in the System Preferences app. You can split long names onto two lines by including a newline character (‘\n’) in the string. If this key is omitted, the System Preferences app gets the name from the CFBundleName key.

This key can be localized and included in the InfoPlist.strings files of a bundle.

NSPrincipalClass

NSPrincipalClass (String - OS X). This key contains a string with the name of a bundle’s principal class. This key is used to identify the entry point for dynamically loaded code, such as plug-ins and other dynamically-loaded bundles. The principal class of a bundle typically controls all other classes in the bundle and mediates between those classes and any classes outside the bundle. The class identified by this value can be retrieved using the principalClass method of NSBundle. For Cocoa apps, the value for this key is NSApplication by default.

NSRemindersUsageDescription

NSRemindersUsageDescription (String - iOS) describes the reason that the app accesses the user’s reminders. When the system prompts the user to allow access, this string is displayed as part of the dialog box.

This key is supported in iOS 6.0 and later.

NSServices

NSServices (Array - OS X). This key contains an array of dictionaries specifying the services provided by the app. Table 4 lists the keys for specifying a service:

Table 4  Keys for NSServices dictionaries

Key

Xcode name

Type

Description

Platforms

NSPortName

“Incoming service port name”

String

This key specifies the name of the port your app monitors for incoming service requests. Its value depends on how the service provider app is registered. In most cases, this is the app name. For more information, see Services Implementation Guide.

OS X

NSMessage

“Instance method name”

String

This key specifies the name of the instance method to invoke for the service. In Objective-C, the instance method must be of the form messageName:userData:error:. In Java, the instance method must be of the form messageName(NSPasteBoard,String).

OS X

NSSendFileTypes

(none)

Array

This key specifies an array of strings. Each string should contain a UTI defining a supported file type. Only UTI types are allowed; pasteboard types are not permitted. To specify pasteboard types, continue to use the NSSendTypes key.

By assigning a value to this key, your service declares that it can operate on files whose type conforms to one or more of the given file types. Your service will receive a pasteboard from which you can read file URLs.

Available in OS X v10.6 and later. For information on UTIs, see Uniform Type Identifiers Overview.

OS X

NSSendTypes

“Send Types”

Array

This key specifies an optional array of data type names that can be read by the service. The NSPasteboard class description lists several common data types. You must include this key, the NSReturnTypes key, or both.

In OS X v10.5 and earlier, this key is required. In OS X v10.6 and later, you should use the NSSendFileTypes key instead.

OS X

NSServiceDescription

(none)

String

This key specifies a description of your service that is suitable for presentation to users. This description string may be long to give users adequate information about your service.

To localize the menu item text, create a ServicesMenu.strings file for each localization in your bundle. This strings file should contain this key along with the translated description string as its value. For more information about creating strings files, see Resource Programming Guide.

Available in OS X v10.6 and later.

OS X

NSRequiredContext

(none)

Dictionary or Array

This key specifies a dictionary with the conditions under which your service is made available to the user. Alternatively, you can specify an array of dictionaries, each of which contains a set of conditions for enabling your service.

See the discussion after this table for information about specifying the value of this key. Available in OS X v10.6 and later.

OS X

NSRestricted

(none)

Boolean

Specifying a value of true for this key prevents the service from being invoked by a sandboxed app. You should set the value to true if your service performs privileged or potentially dangerous operations that would allow a sandboxed app to escape its containment. For example, you should set it to true if your service executes arbitrary files or text strings as scripts, reads or writes any file specified by a path, or retrieves the contents of an arbitrary URL from the network on behalf of the client of the service.

The default value for this key is false. Available in OS X v10.7 and later.

OS X

NSReturnTypes

“Return Types”

Array

This key specifies an array of data type names that can be returned by the service. The NSPasteboard class description lists several common data types. You must include this key, the NSSendTypes key, or both.

OS X

NSMenuItem

“Menu”

Dictionary

This key contains a dictionary that specifies the text to add to the Services menu. The only key in the dictionary is called default and its value is the menu item text.

In OS X v10.5 and earlier, menu items must be unique. You can ensure a unique name by combining the app name with the command name and separating them with a slash character “/”. This effectively creates a submenu for your services. For example, Mail/Send would appear in the Services menu as a menu named Mail with an item named Send.

Submenus are not supported (or necessary) in OS X v10.6 and later. If you specify a slash character in OS X v10.6 and later, the slash and any text preceding it are discarded. Instead, services with the same name are disambiguated by adding the app name in parenthesis after the menu item text.

To localize the menu item text, create a ServicesMenu.strings file for each localization in your bundle. This strings file should contain the default key along with the translated menu item text as its value. For more information about creating strings files, see Resource Programming Guide.

OS X

NSKeyEquivalent

“Menu key equivalent”

Dictionary

This key is optional and contains a dictionary with the keyboard equivalent used to invoke the service menu command. Similar to NSMenuItem, the only key in the dictionary is called default and its value is a single character. Users invoke this keyboard equivalent by pressing the Command modifier key along with the character. The character is case sensitive, so you can assign different commands to the uppercase and lowercase versions of a character. To specify the uppercase character, the user must press the Shift key in addition to the other keys.

OS X

NSUserData

“User Data”

String

This key is an optional string that contains a value of your choice.

OS X

NSTimeout

“Timeout value (in milliseconds)”

String

This key is an optional numerical string that indicates the number of milliseconds Services should wait for a response from the app providing a service when a response is required.

OS X

In OS X v10.6 and later, the NSRequiredContext key may contain a dictionary or an array of dictionaries describing the conditions under which the service appears in the Services menu. If you specify a single dictionary, all of the conditions in that dictionary must be met for the service to appear. If you specify an array of dictionaries, all of the conditions in only one of those dictionaries must be met for the service to appear. Each dictionary may contain one or more of the keys listed in Table 5. All keys in the dictionary are optional.

Table 5  Contents of the NSRequiredContext dictionary

Key

Xcode name

Type

Description

Platform

NSApplicationIdentifier

(none)

String or Array

The value of this key is a string or an array of strings, each of which contains the bundle ID (CFBundleIdentifier key) of an app. Your service appears only if the bundle ID of the current app matches one of the specified values.

OS X

NSTextScript

(none)

String or Array

The value of this key is a string or an array of strings, each of which contains a standard four-letter script tag, such as Latn or Cyrl. Your service appears only if the dominant script of the selected text matches one of the specified script values.

OS X

NSTextLanguage

(none)

String or Array

The value of this key is a string or an array of strings, each of which contains a BCP-47 tag indicating the language of the desired text. Your service appears if the overall language of the selected text matches one of the specified values.

Matching is performed using a prefix-matching scheme. For example, specifying the value en matches text whose full BCP-47 code is en-US, en-GB, or en-AU.

OS X

NSWordLimit

(none)

Number

The value of this key is an integer indicating the maximum number of selected words on which the service can operate. For example, a service to look up a stock by ticker symbol might have a value of 1 because ticker symbols cannot contain spaces.

OS X

NSTextContext

(none)

String or Array

The value of this key is a string or an array of strings, each of which contains one of the following values: URL, Date, Address, Email, or FilePath. The service is displayed only if the selected text contains data of a corresponding type. For example, if the selected text contained an HTTP-based link, the service would be displayed if the value of this key were set to URL.

Note that all of the selected text is provided to the service-vending app, not just the parts found to contain the given data types.

OS X

For additional information about implementing services in your app, see Services Implementation Guide.

NSSupportsAutomaticTermination

NSSupportsAutomaticTermination (Boolean - OS X). This key contains a Boolean value that indicates whether the app supports automatic termination in OS X v10.7 and later. Automatic termination allows an app that is running to be terminated automatically by the system when certain conditions apply. Primarily, the app can be terminated when it is hidden or does not have any visible windows and is not currently being used. The system may terminate such an app in order to reclaim the memory used by the app.

An app may programmatically disable and reenable automatic termination support using the disableAutomaticTermination and enableAutomaticTermination methods of NSProcessInfo. The app might do this to prevent being terminated during a critical operation.

NSSupportsPurgeableLocalStorage

NSSupportsPurgeableLocalStorage (Boolean - iOS). This key contains a Boolean value that indicates whether the app is designed to work, without disruption to the user, with the local data container treated as a volatile cache by the system. The default value of this key is NO. If your app supports Shared iPad (a feature of iOS device management), set this key’s value to YES.

When set to YES, the system is enabled to purge local storage, at the system’s discretion, when the user is logged out.

Supporting Shared iPad entails different work depending on where your app stores nonlocal user data, as follows:

If your app uses only local storage and does not depend on its persistence (for example, a simple calculator app), you can declare support for Shared iPad by setting this key’s value to YES.

NSSupportsSuddenTermination

NSSupportsSuddenTermination (Boolean - OS X). This key contains a Boolean value that indicates whether the system may kill the app outright in order to log out or shut down more quickly. Use this key to specify whether the app can be killed immediately after launch. The app can still enable or disable sudden termination at runtime using the methods of the NSProcessInfo class. The default value of this key is NO.

NSUbiquitousContainers

NSUbiquitousContainers (Dictionary - iOS and OS X) Specifies the iCloud Drive settings for each container. This dictionary’s keys are the container identifiers for your app’s iCloud containers. The values are dictionaries containing the NSUbiquitousContainerIsDocumentScopePublic, NSUbiquitousContainerName and NSUbiquitousContainerSupportedFolderLevels entries for each container. You must specify the sharing permissions separately for each container.

NSUbiquitousContainerIsDocumentScopePublic

NSUbiquitousContainerIsDocumentScopePublic (Boolean - iOS and OS X) Specifies whether the iCloud drive should share the contents of this container. Defaults to NO.

NSUbiquitousContainerName

NSUbiquitousContainerName (String - iOS and OS X) Specifies the name that the iCloud Drive displays for your container. By default, the iCloud Drive will use the name of the bundle that owns the container.

NSUbiquitousContainerSupportedFolderLevels

NSUbiquitousContainerSupportedFolderLevels (String - iOS and OS X) Specifies the maximum number of folder levels inside your container’s Documents directory. This key can take three different values:

NSUbiquitousDisplaySet

NSUbiquitousDisplaySet (String - iOS, OS X) contains the identifier string that you configured in iTunesConnect for managing your app’s storage. The assigned display set determines from which mobile data folder (in the user’s mobile account) the app retrieves its data files.

If you create multiple apps, you can use the same display set for your apps or assign different display sets to each. For example, if you create a “lite” version of your app, in addition to a full-featured version, you might use the same display set for both versions because they create and use the same basic data files. Each app should recognize the file types stored in its mobile data folder and be able to open them.

NSUserActivityTypes

NSUserActivityTypes (Array of strings - iOS and OS X) Specifies the user activity types that the app supports. This key is valid in iOS 8 and OS X v10.10 and later.

NSUserNotificationAlertStyle

NSUserNotificationAlertStyle (String - OS X) specifies the notification style the app should use. The default value, banner, is recommended; most apps should not need to use the alert style.

UTExportedTypeDeclarations

UTExportedTypeDeclarations (Array - iOS, OS X) declares the uniform type identifiers (UTIs) owned and exported by the app. You use this key to declare your app’s custom data formats and associate them with UTIs. Exporting a list of UTIs is the preferred way to register your custom file types; however, Launch Services recognizes this key and its contents only in OS X v10.5 and later. This key is ignored on versions of OS X prior to version 10.5.

The value for the UTExportedTypeDeclarations key is an array of dictionaries. Each dictionary contains a set of key-value pairs identifying the attributes of the type declaration. Table 6 lists the keys you can include in this dictionary along with the typical values they contain. These keys can also be included in array of dictionaries associated with the UTImportedTypeDeclarations key.

Table 6  UTI property list keys

Key

Xcode name

Type

Description

Platforms

UTTypeConformsTo

“Conforms to UTIs”

Array

(Required) Contains an array of strings. Each string identifies a UTI to which this type conforms. These keys represent the parent categories to which your custom file format belongs. For example, a JPEG file type conforms to the public.image and public.data types. For a list of high-level types, see Uniform Type Identifiers Overview.

iOS, OS X

UTTypeDescription

“Description”

String

A user-readable description of this type. The string associated with this key may be localized in your bundle’s InfoPlist.strings files.

iOS, OS X

UTTypeIconFile

“Icon file name”

String

The name of the bundle icon resource to associate with this UTI. You should include this key only for types that your app exports. This file should have a .icns filename extension. You can create this file using the Icon Composer app that comes with Xcode Tools.

OS X

UTTypeIdentifier

“Identifier”

String

(Required) The UTI you want to assign to the type. This string uses the reverse-DNS format, whereby more generic types come first. For example, a custom format for your company would have the form com.<yourcompany>.<type>.<subtype>.

iOS, OS X

UTTypeReferenceURL

“Reference URL”

String

The URL for a reference document that describes this type.

OS X

UTTypeSize64IconFile

(none)

String

The name of the 64 x 64 pixel icon resource file (located in the app’s bundle) to associate with this UTI. You should include this key only for types that your app exports.

iOS

UTTypeSize320IconFile

(none)

String

The name of the 320 x 320 pixel icon resource file (located in the app’s bundle) to associate with this UTI. You should include this key only for types that your app exports.

iOS

UTTypeTagSpecification

“Equivalent Types”

Dictionary

(Required) A dictionary defining one or more equivalent type identifiers. The key-value pairs listed in this dictionary identify the filename extensions, MIME types, OSType codes, and pasteboard types that correspond to this type. For example, to specify filename extensions, you would use the key public.filename-extension and associate it with an array of strings containing the actual extensions. For more information about the keys for this dictionary, see Uniform Type Identifiers Overview.

iOS, OS X

The way you specify icon files in OS X and iOS is different because of the supported file formats on each platform. In iOS, each icon resource file is typically a PNG file that contains only one image. Therefore, it is necessary to specify different image files for different icon sizes. However, when specifying icons in OS X, you use an icon file (with extension .icns), which is capable of storing the icon at several different resolutions.

This key is supported in iOS 3.2 and later and in OS X v10.5 and later. For more information about UTIs and their use, see Uniform Type Identifiers Overview.

UTImportedTypeDeclarations

UTImportedTypeDeclarations (Array - iOS, OS X) declares the uniform type identifiers (UTIs) inherently supported (but not owned) by the app. You use this key to declare any supported types that your app recognizes and wants to ensure are recognized by Launch Services, regardless of whether the app that owns them is present. For example, you could use this key to specify a file format that is defined by another company but which your program can read and export.

The value for this key is an array of dictionaries and uses the same keys as those for the UTExportedTypeDeclarations key. For a list of these keys, see Table 6.

This key is supported in iOS 3.2 and later and in OS X v10.5 and later. For more information about UTIs and their use, see Uniform Type Identifiers Overview.