Determining if an entitlement is real

This issue keeps cropping up on the forums and so I decided to write up a single post with all the details. If you have questions or comments:

• If you were referred here from an existing thread, reply on that thread.
• If not, feel free to start a new thread. Use whatever topic and subtopic is appropriate for your question, but also add the Entitlements tag so that I see it.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

Determining if an entitlement is real

In recent months there’s been a spate of forums threads involving ‘hallucinated’ entitlements. This typically pans out as follows:

1. The developer, or an agent working on behalf of the developer, changes their .entitlements file to claim an entitlement that’s not real. That is, the entitlement key is a value that is not, and never has been, supported in any way.
2. Xcode’s code signing machinery tries to find or create a provisioning profile to authorise this claim.
3. That’s impossible, because the entitlement isn’t a real entitlement. Xcode reports this as a code signing error.
4. The developer misinterprets that error [1] in one of two ways:
   • As a generic Xcode code signing failure, and so they start a forums thread asking about how to fix that problem.
   • As an indication that the entitlement is managed — that is, requires authorisation from Apple to use — and so they start a forums thread asking how to request such authorisation.

The fundamental problem is step 1. Once you start claiming entitlements that aren’t real, you’re on a path to confusion.

Note If you’re curious about how provisioning profiles authorise entitlement claims, read TN3125 Inside Code Signing: Provisioning Profiles.

There are a couple of ways to check whether an entitlement is real. My preferred option is to create a new test project and use Xcode’s Signing & Capabilities editor to add the corresponding capability to it. Then look at what Xcode did. You might find that Xcode claimed a different entitlement, or added an Info.plist key, or did nothing at all.

IMPORTANT If you can’t find the correct capability in the Signing & Capabilities editor, it’s likely that this feature is available to all apps, that is, it’s not gated by an entitlement or anything else.

Another thing you can do is search the documentation. The vast majority of real entitlements are documented in Bundle Resources > Entitlements.

IMPORTANT When you search for documentation, focus on the Apple documentation. If, for example, you search the Apple Developer Forums, you might be mislead by other folks who are similarly confused.

If you find that you’re mistakenly trying to claim a hallucinated entitlement, the fix is trivial:

1. Remove it from your .entitlements file so that your app starts to build again.
2. Then add the capability using Xcode’s Signing & Capabilities editor. This will do the right thing.

If you continue to have problems, feel free to ask for help here on the forums. See the top of this post for advice on how to do that.

[1] It’d be nice if the Xcode errors were more clear in this case (r. 155327166).

Commonly Hallucinated Entitlements

This section lists some of the more commonly hallucinated entitlements:

• com.apple.developer.push-notifications — The correct entitlement is aps-environment (com.apple.developer.aps-environment on macOS), documented here. There’s also the remote-notification value in the UIBackgroundModes property.

• com.apple.developer.in-app-purchase — There’s no entitlement for in-app purchase. Rather, in-app purchase is available to all apps with an explicit App ID (as opposed to a wildcard App ID).

• com.apple.InAppPurchase — Likewise.

• com.apple.developer.app-groups — The correct entitlement is com.apple.security.application-groups, documented here. And if you’re working on the Mac, see App Groups: macOS vs iOS: Working Towards Harmony.

• com.apple.developer.background-modes — Background modes are controlled by the UIBackgroundModes key in your Info.plist, documented here.

• UIBackgroundModes — See the previous point.

• com.apple.developer.voip-push-notification — There’s no entitlement for this. VoIP is gated by the voip value in the UIBackgroundModes property.

• com.apple.developer.family-controls.user-authorization — The correct entitlement is com.apple.developer.family-controls, documented here.

  IMPORTANT As explained in the docs, this entitlement is available to all developers during development but you must request authorisation for distribution.

• com.apple.developer.managed-settings — If you’re trying to use the ManagedSettings framework, that has the same restrictions as Family Controls. If you’re trying to use the ManagedApp framework, that’s not gated by an entitlement.

• com.apple.developer.callkit.call-directory — There’s no entitlement for the Call Directory app extension feature.

• com.apple.developer.nearby-interaction — There’s no entitlement for the Nearby interaction framework.

• com.apple.developer.secure-enclave — On iOS and its child platforms, there’s no entitlement required to use the Secure Enclave. For macOS specifically, any program that has access to the data protection keychain also has access to the Secure Enclave [1]. See TN3137 On Mac keychain APIs and implementations for more about the data protection keychain.

• com.apple.developer.networking.configuration — If you’re trying to configure the Wi-Fi network on iOS, the correct entitlement is com.apple.developer.networking.HotspotConfiguration, documented here.

[1] While technically these are different features, they are closely associated and it turns out that, if you have access to the data protection keychain, you also have access to the SE.