What is the difference between a capability, an entitlement and an Info.plist key, and what breaks when they disagree?

25.1.2 · L3 · Interview

Predict first

A binary is signed with an entitlements file containing two sandbox keys. Can the entitlements be read back from the signature?

// === main.swift ===
print("hello")
// === ent.plist ===
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
<key>com.apple.security.app-sandbox</key><true/>
<key>com.apple.security.network.client</key><true/>
</dict></plist>

Yes: both keys are listed
No: entitlements are only stored in the profile
Only Info.plist keys can be read back

Mental model. Info.plist is the sign on the shop door saying what you sell. An entitlement is the licence from the authority that lets you sell it. Having the sign without the licence, or the licence without telling customers, both cause trouble.

They look similar and are easy to confuse, but they are different layers. A capability is something you switch on for the app: in Xcode’s Signing & Capabilities tab (which also updates the App ID on Apple’s servers) for push notifications, App Groups, iCloud, Sign in with Apple, associated domains, HealthKit and so on. Turning one on usually does three things: it enables the service for the App ID, adds an entitlement to the app’s .entitlements file, and may add keys to Info.plist. An entitlement is a signed claim (a key and value) embedded in the code signature that says “this app may use this protected service”; it is checked against the provisioning profile, which must grant at least the same entitlements, and the check below reads the entitlements back out of a signed binary. Info.plist is configuration and declarations read before your code runs: the bundle identifier and version, supported orientations, URL schemes, background modes, the scene manifest, required device capabilities and the usage description strings that explain why you want access to the camera, location or contacts. It is not signed as a claim of rights, and it does not grant access.

The failure modes differ, which helps you diagnose them. An entitlement that the profile does not include means the app will not install or launch, with a message naming the entitlement (fix: enable the capability so the App ID and profile are regenerated, and re-sign). A missing usage description means the app is terminated the moment it touches the protected API (and App Store submission can be rejected), while the system still asks the user for consent at run time; the string explains, the user decides, and neither the string nor the entitlement can bypass that. A capability enabled but not configured (a push entitlement with no server key) installs fine and fails later. UIBackgroundModes in Info.plist declares which background execution you may use, and misuse is a review issue. Keep a list per target (the app, each extension, the watch app) because each has its own entitlements and plist, and app extensions need the same App Group in the extension’s profile as in the app’s.

Entitlements are embedded in the code signature, which is what the system verifies against the profile.

Common traps

Hand-editing the entitlements file without enabling the capability. The profile does not match and the app will not install.
Forgetting a usage description string. The app is terminated on first use of the protected API.

They might follow up with

Where do entitlements live at run time? In the code signature, verified against the provisioning profile.
Does a usage description grant permission? No: it explains the request; the user still has to allow it.

What is the difference between a capability, an entitlement and an Info.plist key, and what breaks when they disagree?

Predict first

Common traps

They might follow up with

Related questions