swift-security

Swift 安全

将此技能用于 Apple 平台客户端安全工作：Keychain Services、访问控制、生物识别保护的机密、CryptoKit、Secure Enclave 密钥、凭据存储、证书信任、钥匙串共享、旧版机密数据迁移、安全测试，以及 OWASP 移动端合规映射。

部署目标未知时，默认使用 iOS 17+ 和 Swift 并发示例。用户要求支持较旧的目标时，保留 iOS 13+ 兼容性说明。将 iOS 26 CryptoKit 后量子 API 视为受可用性限制的 API。

目录

• 工作流
• 参考资料加载
• 安全不变量
• 相关技能的边界
• 审查清单
• 常见错误
• 输出规则
• 参考资料

工作流

加载参考资料前，先对请求进行分类。

1. 审查现有代码：运行审查清单，然后加载 common-anti-patterns.md 以及每个未通过领域对应的参考资料。报告严重性、证据和修正后的模式。
2. 改进或迁移代码：确定迁移类型，加载迁移和目标领域的参考资料，保留现有数据，验证新条目，然后仅在成功后移除旧版存储。
3. 实现新的安全代码：加载最少量的领域参考资料，使用提供的正确模式，包含 OSStatus 处理和测试，然后运行相关清单。

默认情况下，不要加载所有参考文件。此技能有意拆分以便渐进式披露；仅加载完成用户任务所需的文件。

最低安全级别的钥匙串写入

使用相互独立的添加、标识和更新字典；处理每一种 OSStatus：

func saveSecret(_ data: Data, account: String) throws {
    let identity: [CFString: Any] = [
        kSecClass: kSecClassGenericPassword,
        kSecAttrService: "com.example.app",
        kSecAttrAccount: account,
    ]
    var add = identity
    add[kSecValueData] = data
    add[kSecAttrAccessible] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly

    switch SecItemAdd(add as CFDictionary, nil) {
    case errSecSuccess:
        return
    case errSecDuplicateItem:
        let status = SecItemUpdate(
            identity as CFDictionary,
            [kSecValueData: data] as CFDictionary
        )
        guard status == errSecSuccess else { throw KeychainError(status: status) }
    case let status:
        throw KeychainError(status: status)
    }
}

读取、删除、访问控制、设备锁定和测试模式请加载 keychain-fundamentals.md。

参考资料加载

如果任务涉及	加载
通用钥匙串 CRUD 或 OSStatus 处理	keychain-fundamentals.md
选择 kSecClass 或条目标识	keychain-item-classes.md
可访问性类别或 SecAccessControl	keychain-access-control.md
Face ID、Touch ID 或生物识别保护的机密	biometric-authentication.md
Secure Enclave 密钥	secure-enclave.md
哈希、HMAC、AES-GCM、ChaChaPoly、HKDF、PBKDF2	cryptokit-symmetric.md
签名、ECDH、HPKE、ML-KEM、ML-DSA	cryptokit-public-key.md
OAuth 令牌、API 密钥、注销、刷新轮换	credential-storage-patterns.md
应用/扩展钥匙串共享	keychain-sharing.md
证书信任、SPKI 固定、mTLS	certificate-trust.md
UserDefaults/plist/NSCoding 迁移	migration-legacy-stores.md
单元、集成、模拟器、设备或 CI 测试	testing-security-code.md
OWASP MASVS/MASTG 或企业审计映射	compliance-owasp-mapping.md
完整安全审查	common-anti-patterns.md，然后加载每个涉及领域的参考资料

安全不变量

仅对这些安全不变量以及常见反模式中对应的反模式使用指令式措辞。 对于此列表之外的架构选择，请使用建议性措辞。

• 绝不要将令牌、密码、API 密钥、签名密钥或刷新令牌存储在 UserDefaults、Info.plist、.xcconfig、源代码、日志、文件或 NSCoding 归档中。请使用 Keychain 或在运行时获取机密信息。
• 绝不要忽略 OSStatus。每条 SecItemAdd、SecItemCopyMatching、 SecItemUpdate 和 SecItemDelete 路径都必须处理成功情况和预期的失败情况，例如 errSecDuplicateItem、errSecItemNotFound 和 errSecInteractionNotAllowed。
• 绝不要将 LAContext.evaluatePolicy() 作为保护机密的唯一关卡。请使用 SecAccessControl 将受保护的机密绑定到 Keychain 项目，然后让 Keychain 访问触发 LocalAuthentication。
• 添加 Keychain 项目时，始终显式设置 kSecAttrAccessible 或 kSecAttrAccessControl。
• 对持久化的 Keychain 写入，始终使用添加或更新操作。不要将先删除再添加作为常规更新路径。
• 将 SecItem* 操作放在主 Actor 之外。请使用 Actor 或串行队列访问 Keychain。
• 对于 macOS AppKit 目标，除非有意使用基于旧式文件的 Keychain 项目，否则请通过 kSecUseDataProtectionKeychain: true 指定数据保护 Keychain。
• 绝不要在同一密钥下重复使用 AES-GCM nonce。
• 绝不要将原始 ECDH SharedSecret 字节用作对称密钥。请使用 HKDF 或 X9.63 派生算法进行派生。
• 绝不要将 Insecure.MD5 或 Insecure.SHA1 用于安全目的。

相邻技能边界

此技能负责客户端存储、密码学原语、硬件支持的密钥和信任评估。请有意识地将相邻工作转交给对应技能：

• Sign in with Apple、通行密钥、OAuth UI 流程、 ASAuthorizationController、凭据状态和账户登录 UX，请使用 authentication。
• 如果任务不涉及存储、密钥生命周期、协议／信任设计、安全隔区策略、证书信任、误用审查或合规性，则在需要 CryptoKit 原语 API 语法和示例时使用 cryptokit。
• 如果工作涉及密钥归属、派生、存储、轮换／恢复、安全隔区、 HPKE/PQC 迁移、协议信任边界或误用分析，请在此处开展应用级端到端加密安全审查。
• DeviceCheck 和 App Attest 证明／断言流程，请使用 device-integrity。
• URLSession、请求管道、ATS 配置、重试、缓存、网络可达性和传输架构，请使用 ios-networking。
• 隐私清单、ATT、App Review 指南合规性和提交准备情况，请使用 app-store-review。

此技能仅可提及这些领域，以指出安全工作交接。

审查清单

在代码审查和迁移计划中使用此清单。将每项标记为通过、失败或不适用；对于每项失败，请注明参考文件和严重性。

• 不在 UserDefaults、属性列表、源代码、日志、文件或归档中存储机密信息。
• 每次 SecItem* 调用都会检查 OSStatus，并处理常见的可恢复错误。
• 使用生物识别访问机密信息时，必须通过 SecAccessControl 绑定到钥匙串，而不是仅依赖 LAContext.evaluatePolicy() 返回的独立 Bool。
• 钥匙串添加字典会设置明确的可访问性策略。
• 钥匙串写入使用添加或更新，而不是先删除再添加。
• 钥匙串操作与 UI／主线程执行器代码隔离。
• 所选的 kSecClass 与项目类型和主键属性匹配。
• CryptoKit 代码避免重用 nonce、直接使用原始共享密钥、使用弱哈希和硬编码密钥。
• 自定义加密设计会明确说明密钥归属、派生、存储、轮换／恢复、可用性门槛以及协议／信任边界。
• Secure Enclave 代码会检查可用性，处理模拟器与设备之间的差异，仅持久化 dataRepresentation，并针对设备绑定密钥进行设计。
• App／扩展共享会使用完整的 Team ID 访问组，并确保每个目标都有匹配的授权配置。
• 证书信任使用最新的 SecTrust API，验证主机名和策略；需要证书固定时，使用 SPKI 或 CA 固定。
• macOS 钥匙串代码会明确选择数据保护或基于文件的钥匙串行为。
• 在适用情况下，测试涵盖成功、重复、项目缺失、设备锁定、模拟器／设备以及迁移路径。
• 用户要求合规时，包含 OWASP MASVS／MASTG 映射。

常见错误

• 生成的钥匙串示例不处理重复项或 errSecItemNotFound。
• 添加了生物识别 UI，却没有使用钥匙串访问控制，因此机密信息仍可读取。
• 省略属性时，默认选择 kSecAttrAccessibleWhenUnlocked。
• 使用已弃用的 kSecAttrAccessibleAlways 或 kSecAttrAccessibleAlwaysThisDeviceOnly。
• 在同一个添加查询中混用 kSecAttrAccessible 和 kSecAttrAccessControl。
• 认为 Secure Enclave 密钥可以导入、导出、同步或用于对称加密。
• 声称 iOS 26 之前即可使用 SHA-3、ML-KEM、ML-DSA 或 X-Wing CryptoKit API。
• 认为 iOS 17 之前即可使用 HPKE。
• 实现证书固定时，只对原始密钥字节进行哈希，而没有使用正确的 SPKI 表示形式。
• 将此技能扩展到账号登录、网络、App Attest 或 App Store 审核指导，而不是转交给相关的其他技能。

输出规则

• 对于安全问题，注明严重性：可利用的机密信息或加密问题标记为 CRITICAL，隐蔽的安全边界／数据丢失问题标记为 HIGH，脆弱或不完整的加固措施标记为 MEDIUM。
• 代码实现审查中存在具体反模式时，提供错误和修正后的代码示例。
• 推荐有版本要求的 API 时，注明最低 iOS／macOS 版本。
• 为每项实质性的安全模式注明支持该模式的参考文件。
• 对于钥匙串代码，在示例中包含 OSStatus 处理和明确的可访问性设置。
• 对于实现或迁移相关答复，以 ## Reference Files 结尾，并列出已加载的参考文件及其一句话用途。
• 不要编造 WWDC 会议编号或来源引用。如果某项说法未出现在已加载的参考资料或 Apple 官方文档中，请说明需要核实。

参考资料

• keychain-fundamentals.md - SecItem CRUD、OSStatus 处理、添加或更新、macOS 数据保护钥匙串。
• keychain-item-classes.md - kSecClass 选择、主键、证书、身份。
• keychain-access-control.md - 可访问性常量、SecAccessControl、后台访问、数据保护。
• biometric-authentication.md - 与钥匙串绑定的生物识别、LAContext、注册信息变更处理。
• secure-enclave.md - Secure Enclave 限制、持久化、生物识别密钥、iOS 26 PQ API。
• cryptokit-symmetric.md - SHA、HMAC、AES-GCM、ChaChaPoly、HKDF、PBKDF2。
• cryptokit-public-key.md - 签名、密钥协商、HPKE、ML-KEM、ML-DSA、密钥格式。
• credential-storage-patterns.md - OAuth 令牌、API 密钥、轮换、注销清理。
• keychain-sharing.md - 访问组、扩展、iCloud 同步、macOS 访问组。
• certificate-trust.md - SecTrust、SPKI/CA 固定、NSPinnedDomains、客户端证书。
• migration-legacy-stores.md - UserDefaults/plist/NSCoding 迁移与清理。
• common-anti-patterns.md - 审查不安全生成代码的核心参考。
• testing-security-code.md - 协议模拟、真实钥匙串测试、CI/设备划分。
• compliance-owasp-mapping.md - OWASP Mobile Top 10、MASVS、MASTG 证据映射。