iOS 开发中的 Entitlements：它是什么、有哪些类型以及如何配置

什么是 Entitlements？

Entitlements（从英语翻译过来——“权利”）是一个键值对，在构建阶段被包含在应用程序的代码签名中，用于确定应用程序可以访问哪些系统功能和数据。自 iOS SDK 出现以来，Entitlements 就已嵌入 Apple 的安全模型中，并且对于所有通过 App Store 分发的应用程序都是必需的。

Entitlements 的概念不同于 Android 上的传统权限（permissions）。Android 权限在首次使用功能时从用户处请求，而 iOS 中的 Entitlements 在应用程序启动时由系统基于数字签名进行检查。用户无法撤销或更改 entitlement —— 这个权利通过 App Store Connect 授予开发者，并在签名配置文件中固定下来。

每个 entitlement 都有严格定义的用途和格式。例如，com.apple.security.application-groups 允许同一开发者的多个应用访问共享容器，而 aps-environment 启用 Push 通知支持。Apple 在 App Review 过程中手动审查 entitlement 请求，这防止了权利滥用。

iOS 中 Entitlements 的类型

Entitlements 根据功能用途分为多个类别。系统服务 —— iCloud、Push Notifications、Siri。安全与数据 —— Keychain Access Groups、App Groups、Data Protection。网络与通信 —— Multipath TCP、VPN、Hotspot Configuration。硬件功能 —— Camera、Microphone、Bluetooth（通过相关的 capabilities）。

Capabilities 和服务 Entitlements

Xcode 将相关的 entitlements 分组为 Capabilities —— Signing & Capabilities 选项卡上的高级开关。激活 Capability 会自动将所需的 entitlements 添加到 .entitlements 文件中。例如，激活 Push Notifications Capability 会添加值为 development 或 production 的 aps-environment entitlement，而激活 iCloud 会添加用于 CloudKit 和 Key-Value storage 的一组 entitlements。

某些 capabilities 需要在 Apple Developer 门户上进行额外配置。例如，对于 App Groups，需要在门户上注册组标识符，之后它就可以在 Xcode 中选择。对于 Push Notifications，需要生成 APNs 密钥或证书。没有这些准备步骤，即使有正确的 .entitlements 文件，entitlement 也无法工作。

App Groups 和 Keychain Access

com.apple.security.application-groups entitlement 允许同一开发者的多个应用在文件系统中拥有共享容器。这用于在主应用和扩展（Widget、Watch App、Share Extension）之间共享数据。同一组中的所有应用都可以在共享目录 /Library/Group Containers/ 中读写文件。

Keychain Access Groups（键 keychain-access-groups）—— 另一个重要的 entitlement，允许同一组中的应用共享访问 Keychain 元素。这对于实现统一身份验证至关重要：用户在一个应用中登录，并自动获得对另一个应用中同一账户的访问权限，无需重新输入密码。

如何配置 Entitlements

Entitlements 的配置在 Xcode 的 target 设置中的 Signing & Capabilities 选项卡上进行。开发者从列表中选择所需的 Capabilities，Xcode 会自动创建或更新 .entitlements 文件。该文件以 XML 格式存储在项目中，采用 plist 结构，包含此 target 的所有 entitlement 键。

<?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.application-groups</key>
    <array>
        <string>group.com.example.shared</string>
    </array>
    <key>aps-environment</key>
    <string>development</string>
    <key>keychain-access-groups</key>
    <array>
        <string>$(AppIdentifierPrefix)com.example.keychain</string>
    </array>
</dict>
</plist>

在手动创建 entitlement 文件时，遵守键的格式和前缀很重要。Apple 的 Entitlements 使用反向域名风格（com.apple.*）。也可以为自定义目的创建自定义 entitlements，但必须在开发者门户上注册。Xcode 为所有标准 entitlement 键提供自动完成功能。

要调试 Entitlements，请在 macOS 终端中使用 codesign 命令。codesign -d --entitlements :- <应用程序路径> 命令会显示应用程序被签名的所有 entitlements。这对于诊断问题很有用：如果输出中缺少某个 entitlement，则无论 Xcode 中的设置如何，应用程序都无法访问相应功能。

手动创建 entitlement 文件

虽然 Xcode 在激活 Capabilities 时会自动生成 entitlement 文件，但有经验的开发者经常手动创建或编辑它来进行微调。该文件扩展名为 .entitlements，格式为 plist（XML）。可以在其中添加 Xcode 界面中未出现的自定义 entitlement 键，或将不同 capabilities 中的 entitlements 合并到一个文件中。

在手动编辑时，监控 XML 的语法正确性很重要。plist 结构中的错误会导致 entitlements 在签名时无法应用。Xcode 在编译阶段检查 .entitlements 文件，并在格式不正确时显示错误。对于具有多个 target 和扩展的复杂项目，建议将共享的 entitlement 键存储在单独的文件中，并通过 Build Settings 导入它们。

// cli: 检查已安装应用程序的 entitlements
codesign -d --entitlements :- /Applications/Safari.app

// 示例输出包含活动 entitlements 列表
<dict>
    <key>com.apple.security.ts.apple-wifi</key>
    <true/>
    <key>com.apple.security.network.client</key>
    <true/>
</dict>

Entitlements 与应用程序安全

Entitlements 在 Apple 的安全模型中起着关键作用。由于 entitlements 是应用程序数字签名的一部分，不重新签名代码就无法篡改它们。Apple 在多个级别检查 entitlements：在构建时，Xcode 将 entitlements 与可执行文件一起签名；在安装时，系统检查签名的完整性；在启动时，重新验证 entitlements。

重要的安全要求之一是最小 entitlement 原则。开发者应只激活应用程序中实际使用的 entitlements。多余的 entitlements 会增加攻击面，并可能导致应用程序在 App Review 中被拒绝。Apple 明确检查 entitlements 与应用程序功能的一致性。

某些 entitlements 被认为是敏感的（sensitive），需要 Apple 的额外批准。这些包括：com.apple.developer.healthkit（HealthKit）、com.apple.developer.passkit（Wallet）、com.apple.developer.authentication-services.authentication（Sign in with Apple）和 com.apple.developer.nfc.readersession.formats（NFC）。要获取这些 entitlements，需要在 App Review 过程中证明其必要性。

在处理 entitlements 时，重要的是要考虑 iOS 和 macOS 之间的差异。macOS 的桌面应用程序（Sandboxed）相比 iOS 拥有更广泛的 entitlements 集。例如，com.apple.security.temporary-exception.* entitlement 允许某些操作临时绕过沙箱 —— 在 iOS 中，此类 entitlements 完全不存在。

Entitlements 和 Provisioning Profile

Entitlements 与签名配置文件（Provisioning Profiles）密切相关。签名配置文件是将开发者证书、允许的设备列表和特定应用程序的 entitlements 集联系起来的文件。在应用程序安装时，系统将代码中的 entitlements 与签名配置文件中的 entitlements 进行比较。如果 entitlement 存在于代码中但配置文件中没有，应用程序将无法访问相应功能。

要诊断与 entitlements 相关的问题，首先检查签名配置文件。Xcode 根据在 Apple Developer 门户上选择的 capability 自动生成配置文件。如果 capability 已在 Xcode 中添加但在门户上未激活，应用程序在尝试使用受保护功能时会崩溃并显示签名错误。