dpearson2699/swift-ios-skills / skills/swift-security
swift-security
UnverifiedUse when working with iOS/macOS Keychain Services (SecItem queries, kSecClass, OSStatus errors), biometric authentication (LAContext, Face ID, Touch ID), CryptoKit (AES-GCM, ChaChaPoly, ECDSA, ECDH, HPKE, ML-KEM), Secure Enclave, secure credential storage (OAuth tokens, API keys), certificate pinning (SecTrust, SPKI), keychain sharing across apps/extensions, migrating secrets from UserDefaults or plists, or OWASP MASVS/MASTG mobile compliance on Apple platforms.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.7 KB |
| evals/evals.json | config | 4.6 KB |
| references/biometric-authentication.md | markdown | 28.7 KB |
| references/certificate-trust.md | markdown | 31.3 KB |
| references/common-anti-patterns.md | markdown | 31.0 KB |
| references/compliance-owasp-mapping.md | markdown | 38.5 KB |
| references/credential-storage-patterns.md | markdown | 43.1 KB |
| references/cryptokit-public-key.md | markdown | 34.5 KB |
| references/cryptokit-symmetric.md | markdown | 28.9 KB |
| references/keychain-access-control.md | markdown | 32.9 KB |
| references/keychain-fundamentals.md | markdown | 30.1 KB |
| references/keychain-item-classes.md | markdown | 32.9 KB |
| references/keychain-sharing.md | markdown | 32.1 KB |
| references/migration-legacy-stores.md | markdown | 37.0 KB |
| references/secure-enclave.md | markdown | 32.1 KB |
| references/testing-security-code.md | markdown | 35.2 KB |
references/keychain-access-control.md
View on GitHub# Keychain Access Control
> Scope: Selecting `kSecAttrAccessible` classes and `SecAccessControl` flags to enforce the correct lock-state and user-presence guarantees for keychain items.
Data protection classes (`kSecAttrAccessible`) and runtime authentication gates (`SecAccessControl`) form the two-layer security model protecting every keychain item. The first controls **when** an item's class key is available in memory based on device state; the second controls **how** the user must authenticate at access time. Both must be satisfied for a read to succeed. Getting this wrong is the single most common cause of production keychain failures — background operations that silently return `nil`, items that vanish after device migration, or credentials left decryptable at rest.
Sources: Apple Platform Security Guide (2024–2026 editions), Apple Keychain Services documentation, TN3137, WWDC 2014 Session 711 ("Keychain and Authentication with Touch ID"), WWDC 2015 Session 706, SecAccessControl documentation, OWASP MASTG.
---
## Contents
- [The "When" Layer: Seven Accessibility Constants](#the-when-layer-seven-accessibility-constants)
- [The Protection Spectrum](#the-protection-spectrum)
- [Quick Reference Table](#quick-reference-table)
- [Lock-State Spectrum Explained](#lock-state-spectrum-explained)
- [The "How" Layer: SecAccessControl Flags](#the-how-layer-secaccesscontrol-flags)
- [Available Flags](#available-flags)
- [Flag Compatibility Matrix](#flag-compatibility-matrix)
- [Composing Constraints](#composing-constraints)
- [The Cardinal Rule: Never Set Both Attributes](#the-cardinal-rule-never-set-both-attributes)
- [Decision Matrix: Choosing the Right Accessibility Level](#decision-matrix-choosing-the-right-accessibility-level)
- [`WhenPasscodeSetThisDeviceOnly` — Data that should self-destruct](#whenpasscodesetthisdeviceonly-data-that-should-self-destruct)
- [`WhenUnlockedThisDeviceOnly` — Standard device-bound credentials](#whenunlockedthisdeviceonly-standard-device-bound-credentials)
- [`AfterFirstUnlockThisDeviceOnly` — Background operations (most common for services)](#afterfirstunlockthisdeviceonly-background-operations-most-common-for-services)
- [`AfterFirstUnlock` — Background + backup migration](#afterfirstunlock-background-backup-migration)
- [Dual-Item Strategy for Mixed Contexts](#dual-item-strategy-for-mixed-contexts)
- [Common AI-Generated Mistakes](#common-ai-generated-mistakes)
- [Mistake 1: Omitting `kSecAttrAccessible` (inheriting the wrong default)](#mistake-1-omitting-ksecattraccessible-inheriting-the-wrong-default)
- [Mistake 2: Using deprecated `kSecAttrAccessibleAlways`](#mistake-2-using-deprecated-ksecattraccessiblealways)
- [Mistake 3: Not handling `ThisDeviceOnly` item loss after device migration](#mistake-3-not-handling-thisdeviceonly-item-loss-after-device-migration)
- [Mistake 4: Biometric flags on background-accessible protection levels](#mistake-4-biometric-flags-on-background-accessible-protection-levels)
- [Mistake 5: Conflicting flags without logical operator](#mistake-5-conflicting-flags-without-logical-operator)
- [Code Patterns](#code-patterns)
- [Biometric protection with highest security](#biometric-protection-with-highest-security)
- [Background-accessible token (push notifications, VPN, widgets)](#background-accessible-token-push-notifications-vpn-widgets)
- [Accessing a `WhenUnlocked` item from a background extension](#accessing-a-whenunlocked-item-from-a-background-extension)
- [macOS: `kSecUseDataProtectionKeychain`](#macos-ksecusedataprotectionkeychain)
- [NSFileProtection Sidebar](#nsfileprotection-sidebar)
- [Error Codes Reference](#error-codes-reference)
- [iOS Version Timeline](#ios-version-timeline)
- [Testing Requirements](#testing-requirements)
- [Cross-References](#cross-references)
- [Summary Checklist](#summary-checklist)
## The "When" Layer: Seven Accessibility Constants
Every keychain item is encrypted with a class key derived from the device's hardware UID and (for most classes) the user's passcode. The `kSecAttrAccessible` attribute selects which class key protects the item, determining when the system can decrypt it. **If you omit `kSecAttrAccessible`, the default is `kSecAttrAccessibleWhenUnlocked`** — confirmed by Apple documentation. This default breaks all background operations.
### The Protection Spectrum
Listed from most restrictive to least:
**`kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly`** (iOS 8+) — the highest-security class. Items are accessible only while unlocked, and only if a device passcode is currently set. Two unique behaviors: (1) `SecItemAdd` fails on devices without a passcode, (2) **removing the passcode permanently deletes all items in this class** — class keys are discarded, data is unrecoverable. No non-`ThisDeviceOnly` variant exists. Items don't sync to iCloud Keychain, aren't backed up, and aren't in escrow keybags.
**`kSecAttrAccessibleWhenUnlockedThisDeviceOnly`** — Items decryptable only while unlocked. Device-bound: excluded from backups and device migration.
**`kSecAttrAccessibleWhenUnlocked`** ⭐ (system default) — Same lock-state behavior as above, but items migrate with encrypted backups. Maps to `NSFileProtectionComplete`. Class key is discarded from memory shortly after the device locks (~10 seconds with Require Password set to Immediately).
**`kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`** — **The correct choice for background operations.** After the user unlocks the device once following a restart, the class key remains in memory until the next restart — even while locked. Device-bound.
**`kSecAttrAccessibleAfterFirstUnlock`** — Same background accessibility, but items migrate with encrypted backups. Apple uses this for system Wi-Fi passwords, mail accounts, and iCloud tokens. Maps to `NSFileProtectionCompleteUntilFirstUserAuthentication`.
**`kSecAttrAccessibleAlwaysThisDeviceOnly`** ⚠️ DEPRECATED — Deprecated in iOS 12 / macOS 10.14. Apple announced intent at WWDC 2015 Session 706.
**`kSecAttrAccessibleAlways`** ⚠️ DEPRECATED — Same deprecation. Items encrypted with only the device UID (no passcode involvement), equivalent to `NSFileProtectionNone`.
Deprecated "Always" constants have OS-version-specific behavior and should not be used for new or migrated code. **Migrate to `kSecAttrAccessibleAfterFirstUnlock` or a stricter class**, and block these constants in CI linting rather than relying on runtime behavior across OS versions.
### Quick Reference Table
| Constant | Accessible When | Survives Lock | Migrates in Backup | Special |
| -------------------------------- | ----------------------- | ------------- | ------------------ | ------------------------------- |
| `WhenPasscodeSetThisDeviceOnly` | Unlocked + passcode set | No | No | **Deleted on passcode removal** |
| `WhenUnlockedThisDeviceOnly` | Unlocked | No | No | — |
| `WhenUnlocked` ⭐ default | Unlocked | No | Yes | — |
| `AfterFirstUnlockThisDeviceOnly` | After first unlock | Yes | No | Background-safe |
| `AfterFirstUnlock` | After first unlock | Yes | Yes | Background-safe + migratable |
| `AlwaysThisDeviceOnly` ⚠️ | Always¹ | Yes | No | Deprecated iOS 12 |
| `Always` ⚠️ | Always¹ | Yes | Yes | Deprecated iOS 12 |
¹ Behavior may be remapped to `AfterFirstUnlock` on modern iOS versions.
### Lock-State Spectrum Explained
After a device restart, the system is in **Before First Unlock (BFU)** state. Only items with the deprecated `Always` class are supposed to be accessible. Even `AfterFirstUnlock` items are locked.
Once the user enters their passcode, the device enters **After First Unlock (AFU)** state. `AfterFirstUnlock` class keys load into memory and remain there through subsequent lock/unlock cycles until the next restart. `WhenUnlocked` class keys are available only during active unlocked periods and discarded each time the device locks.
> **iOS 15+ caveat — app pre-warming:** iOS can launch your process before first unlock for faster app startup. This means even `AfterFirstUnlock` items may be temporarily unavailable during pre-warm. Check `UIApplication.shared.isProtectedDataAvailable` before accessing keychain items, and defer if it returns `false`.
---
## The "How" Layer: SecAccessControl Flags
`SecAccessControl` adds runtime authentication requirements on top of data-at-rest protection. It is created via `SecAccessControlCreateWithFlags`, which embeds the accessibility level inside the control object:
```swift
func SecAccessControlCreateWithFlags(
_ allocator: CFAllocator?, // Pass nil
_ protection: CFTypeRef, // A kSecAttrAccessible constant
_ flags: SecAccessControlCreateFlags,
_ error: UnsafeMutablePointer<Unmanaged<CFError>?>?
) -> SecAccessControl?
```
### Available Flags
**Authentication constraints:**
- **`.userPresence`** (iOS 8+) — Biometry OR passcode. Does not require biometry enrollment; auto-falls back to passcode. Equivalent to `[.biometryAny, .or, .devicePasscode]` but handles no-biometry gracefully.
- **`.biometryAny`** (iOS 11.3+, was `.touchIDAny`) — Requires biometric authentication. Item **survives** enrollment changes (new fingerprints, Face ID re-enrollment).
- **`.biometryCurrentSet`** (iOS 11.3+, was `.touchIDCurrentSet`) — Requires biometric authentication. Item **invalidated** on enrollment changes. Most secure biometric option — blocks an attacker who enrolls their own biometrics.
- **`.devicePasscode`** (iOS 9+) — Requires device passcode entry only.
**Logical combinators:**
- **`.or`** — At least one constraint must be satisfied.
- **`.and`** — All constraints must be satisfied.
**Additional:**
- **`.privateKeyUsage`** (iOS 9+) — Required for Secure Enclave private key operations (signing, key agreement).
- **`.applicationPassword`** (iOS 9+) — Adds an app-provided password to key derivation. Not a constraint — an additional encryption layer.
### Flag Compatibility Matrix
| Flag | Works in Background? | Typical Pairing | Failure if Misused |
| ---------------------- | ------------------------ | ----------------------------------------- | -------------------------------------------- |
| `.userPresence` | No | Foreground + `WhenUnlocked` | `-25308` in background |
| `.biometryAny` | No | Foreground secrets | `errSecAuthFailed` if no biometrics enrolled |
| `.biometryCurrentSet` | No | `WhenPasscodeSetTDO` for highest security | Auth fails on enrollment change |
| `.devicePasscode` | No | Compliance flows | `-25308` without UI |
| `.privateKeyUsage` | Yes (for key ops) | Secure Enclave keys | — |
| `.applicationPassword` | Yes (if password cached) | Niche models | Password lifecycle management |
### Composing Constraints
Since `SecAccessControlCreateFlags` is an `OptionSet`, compose with array literal syntax:
```swift
// Biometry OR passcode — most common pattern
let flags: SecAccessControlCreateFlags = [.biometryCurrentSet, .or, .devicePasscode]
// Biometry AND passcode — both required (rare, high security)
let flags: SecAccessControlCreateFlags = [.biometryAny, .and, .devicePasscode]
// Biometry OR passcode, plus application password encryption
let flags: SecAccessControlCreateFlags = [.biometryAny, .or, .devicePasscode, .applicationPassword]
```
> **Critical rule: `.or` / `.and` is required between authentication flags.** Combining `.biometryCurrentSet` and `.devicePasscode` without a logical operator causes `SecAccessControlCreateWithFlags` to return `nil` with `errSecParam` (-50). Both sources confirm this behavior.
---
## The Cardinal Rule: Never Set Both Attributes
`kSecAttrAccessible` and `kSecAttrAccessControl` are **mutually exclusive** in the query dictionary. When you use `SecAccessControlCreateWithFlags`, the accessibility level is embedded inside the `SecAccessControl` object via the `protection` parameter. Setting both in the same `SecItemAdd` query causes **`errSecParam` (-50)**.
```swift
// ❌ WRONG — sets accessibility twice, causes errSecParam (-50)
var error: Unmanaged<CFError>?
let access = SecAccessControlCreateWithFlags(
nil,
kSecAttrAccessibleWhenUnlockedThisDeviceOnly, // ← accessibility set HERE
[.biometryCurrentSet, .or, .devicePasscode],
&error
)!
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrAccount as String: "credential",
kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly, // ❌ CONFLICT
kSecAttrAccessControl as String: access, // ← already contains accessibility
kSecValueData as String: secretData
]
// SecItemAdd returns errSecParam (-50)
```
```swift
// ✅ CORRECT — accessibility set only inside SecAccessControl
var error: Unmanaged<CFError>?
guard let access = SecAccessControlCreateWithFlags(
nil,
kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
[.biometryCurrentSet, .or, .devicePasscode],
&error
) else { throw KeychainError.accessControlCreationFailed(error?.takeRetainedValue()) }
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrAccount as String: "credential",
kSecAttrAccessControl as String: access, // Contains accessibility + auth flags
kSecValueData as String: secretData
]
```
---
## Decision Matrix: Choosing the Right Accessibility Level
### `WhenPasscodeSetThisDeviceOnly` — Data that should self-destruct
Use for your most sensitive credentials. Pair with `.biometryCurrentSet` via `SecAccessControl`. Accept the tradeoff: items are permanently destroyed on passcode removal and never survive device migration. Your app **must** handle item absence gracefully and guide users through re-authentication.
**Use cases:** Banking session tokens, password manager vault keys, healthcare credentials, E2E encryption private keys.
### `WhenUnlockedThisDeviceOnly` — Standard device-bound credentials
Credentials that should be device-bound but don't need passcode-deletion behavior. Re-authenticate after device migration.
**Use cases:** OAuth access tokens (refreshable), app-specific API keys, cached credentials, device registration tokens.
### `AfterFirstUnlockThisDeviceOnly` — Background operations (most common for services)
The correct choice for **any keychain item accessed by background code** — push notification handlers, WidgetKit timeline providers, background fetch, VPN extensions, notification service extensions. Device-bound.
**Use cases:** Push notification decryption keys, VPN credentials, background sync tokens, watch connectivity tokens.
### `AfterFirstUnlock` — Background + backup migration
Same background accessibility, plus items migrate with encrypted backups. Use when background access and device-transfer continuity are both needed.
**Use cases:** Enterprise VPN credentials, email account credentials, Wi-Fi configuration passwords.
### Dual-Item Strategy for Mixed Contexts
If a credential needs both background access (no UI) and foreground biometric protection (with UI), **store two separate items**: a background-capable token with `AfterFirstUnlockThisDeviceOnly` (no `SecAccessControl` user-presence flags) and a stronger foreground-only item with `WhenUnlockedThisDeviceOnly` + biometric `SecAccessControl`. This avoids the logical contradiction of biometric flags on background-accessible items.
---
## Common AI-Generated Mistakes
### Mistake 1: Omitting `kSecAttrAccessible` (inheriting the wrong default)
The most pervasive error. AI code generators produce keychain wrappers that never set `kSecAttrAccessible`, inheriting `WhenUnlocked`. Works during development (device unlocked while testing), fails in production when background extensions execute while locked — `errSecInteractionNotAllowed` (-25308), often silently swallowed.
```swift
// ❌ WRONG — omits kSecAttrAccessible, defaults to WhenUnlocked
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrAccount as String: "authToken",
kSecAttrService as String: "com.example.app",
kSecValueData as String: tokenData
// Missing: kSecAttrAccessible — background extensions WILL fail with -25308
]
```
```swift
// ✅ CORRECT — explicit accessibility for background use
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrAccount as String: "authToken",
kSecAttrService as String: "com.example.app",
kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly,
kSecValueData as String: tokenData
]
```
### Mistake 2: Using deprecated `kSecAttrAccessibleAlways`
Compiles with a warning on iOS 12+, runs at runtime — arguably worse than a hard failure. No meaningful lock-state protection.
```swift
// ❌ WRONG — deprecated since iOS 12
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrAccessible as String: kSecAttrAccessibleAlways, // ⚠️ Deprecated
kSecValueData as String: tokenData
]
// Replacement: kSecAttrAccessibleAfterFirstUnlock
```
### Mistake 3: Not handling `ThisDeviceOnly` item loss after device migration
Items with `ThisDeviceOnly` are cryptographically bound to the hardware UID. They are excluded from all backups, iCloud sync, and Quick Start device-to-device migration. After restoring to a new device, these items silently disappear — `errSecItemNotFound` (-25300). AI-generated code rarely implements re-authentication flows for this scenario.
### Mistake 4: Biometric flags on background-accessible protection levels
Setting `.biometryCurrentSet` with `kSecAttrAccessibleAfterFirstUnlock` is technically valid at the API level but creates a **logical contradiction**: `AfterFirstUnlock` implies background access while locked, but biometric auth requires an interactive prompt. Result: `errSecInteractionNotAllowed` in background contexts, defeating the purpose.
### Mistake 5: Conflicting flags without logical operator
Combining `.biometryCurrentSet` and `.devicePasscode` without `.or` or `.and` causes `SecAccessControlCreateWithFlags` to return `nil` / `errSecParam` (-50).
```swift
// ❌ WRONG — missing logical operator
let access = SecAccessControlCreateWithFlags(
nil,
kSecAttrAccessibleWhenUnlocked,
[.biometryCurrentSet, .devicePasscode], // Missing .or or .and
&error
)
// Returns nil, error contains errSecParam
```
```swift
// ✅ CORRECT — explicit .or between constraints
let access = SecAccessControlCreateWithFlags(
nil,
kSecAttrAccessibleWhenUnlocked,
[.biometryCurrentSet, .or, .devicePasscode],
&error
)
```
---
## Code Patterns
✅ The first two examples are correct patterns for foreground and background access. The third example is intentionally incorrect.
### Biometric protection with highest security
```swift
func saveBiometricProtectedItem(data: Data, account: String, service: String) throws {
var error: Unmanaged<CFError>?
guard let accessControl = SecAccessControlCreateWithFlags(
nil,
kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
[.biometryCurrentSet, .or, .devicePasscode],
&error
) else {
throw KeychainError.accessControlCreationFailed(error?.takeRetainedValue())
}
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrAccount as String: account,
kSecAttrService as String: service,
kSecAttrAccessControl as String: accessControl,
kSecValueData as String: data
]
let status = SecItemAdd(query as CFDictionary, nil)
switch status {
case errSecSuccess: return
case errSecDuplicateItem:
// Must delete + re-add: SecItemUpdate cannot change SecAccessControl
let searchQuery: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrAccount as String: account,
kSecAttrService as String: service
]
let deleteStatus = SecItemDelete(searchQuery as CFDictionary)
guard deleteStatus == errSecSuccess else {
throw KeychainError.fromStatus(deleteStatus)
}
let readdStatus = SecItemAdd(query as CFDictionary, nil)
guard readdStatus == errSecSuccess else {
throw KeychainError.fromStatus(readdStatus)
}
default:
throw KeychainError.fromStatus(status)
}
}
```
> **Important:** `SecItemUpdate` **cannot** change a `SecAccessControl` attribute on an existing item. To change access control, you must delete and re-add. Both sources confirm this.
### Background-accessible token (push notifications, VPN, widgets)
```swift
func saveBackgroundToken(_ token: Data, account: String, service: String) throws {
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrAccount as String: account,
kSecAttrService as String: service,
kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly,
kSecValueData as String: token
]
let status = SecItemAdd(query as CFDictionary, nil)
switch status {
case errSecSuccess: return
case errSecDuplicateItem:
let updateAttrs: [String: Any] = [kSecValueData as String: token]
let searchQuery: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrAccount as String: account,
kSecAttrService as String: service
]
let updateStatus = SecItemUpdate(searchQuery as CFDictionary, updateAttrs as CFDictionary)
guard updateStatus == errSecSuccess else {
throw KeychainError.fromStatus(updateStatus)
}
default:
throw KeychainError.fromStatus(status)
}
}
```
### Accessing a `WhenUnlocked` item from a background extension
```swift
// Runs in WidgetKit TimelineProvider or NotificationServiceExtension while locked — WILL fail
func fetchTokenInBackground() -> String? {
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrAccount as String: "authToken",
kSecAttrService as String: "com.example.app",
kSecReturnData as String: true,
kSecMatchLimit as String: kSecMatchLimitOne
// Item stored with default WhenUnlocked — inaccessible while locked
]
var result: AnyObject?
let status = SecItemCopyMatching(query as CFDictionary, &result)
// status == errSecInteractionNotAllowed (-25308) when device is locked
guard status == errSecSuccess, let data = result as? Data else {
return nil // ❌ Silent failure — no logging, no error propagation
}
return String(data: data, encoding: .utf8)
}
```
---
## macOS: `kSecUseDataProtectionKeychain`
macOS has **two keychain implementations** (per TN3137): the legacy file-based keychain (`~/Library/Keychains/login.keychain-db`) and the modern Data Protection keychain. The `SecItem` API defaults to the **legacy** keychain on macOS.
Set `kSecUseDataProtectionKeychain: true` in every macOS keychain query to target the modern keychain. Without it:
- `SecAccessControl` flags fail with `errSecParam` (-50)
- iCloud Keychain sync doesn't work
- Secure Enclave integration is unavailable
- Biometric protection (Touch ID) won't function
```swift
// ✅ macOS: always include kSecUseDataProtectionKeychain
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrAccount as String: account,
kSecAttrService as String: service,
kSecUseDataProtectionKeychain as String: true, // ← Critical on macOS
kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly,
kSecValueData as String: data
]
```
On iOS, tvOS, and watchOS, this flag is ignored (those platforms always use Data Protection). The Data Protection keychain requires a user login context — `launchd` daemons running outside a user session must use the legacy keychain. Mac Catalyst and iOS-on-Mac apps automatically use Data Protection.
---
## NSFileProtection Sidebar
The keychain and file system share the same Data Protection architecture but expose it through different APIs. Use the keychain for small discrete secrets (passwords, tokens, keys). Use `NSFileProtection` for larger data (documents, databases, images).
**`NSFileProtectionComplete`** (Class A) = `kSecAttrAccessibleWhenUnlocked`. File inaccessible while locked. Class key discarded ~10 seconds after lock.
**`NSFileProtectionCompleteUnlessOpen`** (Class B) = **No keychain equivalent.** Uses asymmetric ECDH (Curve25519) to allow already-opened files to continue being written while locked. Designed for background downloads (e.g., mail attachment download continues writing to an already-open file).
**`NSFileProtectionCompleteUntilFirstUserAuthentication`** (Class C) = `kSecAttrAccessibleAfterFirstUnlock`. The default for third-party app files when no explicit protection is set. Available after first unlock.
**`NSFileProtectionNone`** (Class D) = deprecated `kSecAttrAccessibleAlways`. Protected only by device UID.
**Recommended layered approach:** Store encryption keys in the keychain with `WhenUnlockedThisDeviceOnly`, then use those keys to encrypt larger files on disk with `NSFileProtectionComplete` as an additional layer.
---
## Error Codes Reference
| Code | Constant | Meaning | Common Root Cause |
| ---------- | ----------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **-25308** | `errSecInteractionNotAllowed` | Item not accessible in current state | Device locked + `WhenUnlocked` item; BFU state + `AfterFirstUnlock` item; biometric flag in background |
| **-50** | `errSecParam` | Invalid parameters | Both `kSecAttrAccessible` and `kSecAttrAccessControl` set; conflicting flags without `.or`/`.and`; missing `kSecUseDataProtectionKeychain` on macOS |
| **-25293** | `errSecAuthFailed` | Authentication failed | Biometric auth failed; enrollment changed with `.biometryCurrentSet`; no biometrics enrolled |
| **-25300** | `errSecItemNotFound` | Item not in keychain | Item never stored; `ThisDeviceOnly` lost after migration; `WhenPasscodeSet` deleted on passcode removal |
| **-25299** | `errSecDuplicateItem` | Item already exists | `SecItemAdd` when matching primary keys exist — use add-or-update pattern |
| **-128** | `errSecUserCanceled` | User canceled prompt | User tapped Cancel on biometric/passcode dialog |
| **-34018** | `errSecMissingEntitlement` | Missing entitlement | Keychain access group not in entitlements; common on iOS Simulator |
The most insidious is `-25308` — it surfaces in production but rarely during development because developers test with unlocked devices. Always handle it by deferring the operation and retrying when `UIApplication.shared.isProtectedDataAvailable` is `true`.
---
## iOS Version Timeline
**iOS 8 (2014):** `WhenPasscodeSetThisDeviceOnly` introduced. `SecAccessControlCreateWithFlags` added. `.userPresence` flag.
**iOS 9 (2015):** `.devicePasscode`, `.applicationPassword`, `.privateKeyUsage` flags added. Apple announced intent to deprecate `Always` at WWDC 2015 Session 706.
**iOS 11.3 (2018):** `.touchIDAny` → `.biometryAny`; `.touchIDCurrentSet` → `.biometryCurrentSet` (unified naming for Face ID).
**iOS 12 (2018):** `kSecAttrAccessibleAlways` and `AlwaysThisDeviceOnly` formally deprecated. Both still compile and run for backward compatibility.
**iOS 15 (2021):** MDM-installed keychain items changed default from "always" to "after first unlock, nonmigratory." App pre-warming can launch processes before first unlock, making `AfterFirstUnlock` items temporarily unavailable.
**iOS 16 (2022):** Passkeys launched (FIDO2/WebAuthn key pairs synced via E2E encrypted iCloud Keychain). No changes to access control APIs.
**iOS 17 (2023):** Enterprise passkey support. No `kSecAttrAccessible` or `SecAccessControl` changes.
**iOS 18 (2024):** Standalone Passwords app. No keychain data protection API changes.
**iOS 26 (2025):** Stolen Device Protection enabled by default — requires biometric auth (no passcode fallback) for stored passwords when away from familiar locations. Secure passkey import/export via FIDO Alliance standard. No changes to `kSecAttrAccessible` constants.
---
## Testing Requirements
All data protection testing **must** use physical devices with passcodes enabled. The iOS Simulator does not enforce `kSecAttrAccessible` or `NSFileProtection`, creating a false sense of security.
**Critical test scenarios:**
1. **Reboot / BFU state:** Reboot device, attempt keychain access before unlocking. `AfterFirstUnlock` items should return `-25308` or `-25300`. Unlock once, lock again, test background access — should succeed.
2. **Lock timing:** Store a `WhenUnlocked` item. Lock the device. Attempt read immediately — expect `-25308`.
3. **Passcode removal:** Store a `WhenPasscodeSetThisDeviceOnly` item. Remove passcode in Settings. Verify item is deleted (`-25300`).
4. **Biometric enrollment change:** Store an item with `.biometryCurrentSet`. Add a new fingerprint or Face ID appearance. Verify authentication fails (`-25293`).
5. **Backup/restore migration:** Back up device, restore to a different physical device. Verify all `ThisDeviceOnly` items are absent (`-25300`).
6. **Background extension access:** Trigger a notification service extension or widget timeline update while the device is locked. Verify `AfterFirstUnlock` items are readable and `WhenUnlocked` items are not.
---
## Cross-References
- `keychain-fundamentals.md` — SecItem CRUD patterns, add-or-update, OSStatus handling
- `biometric-authentication.md` — Biometric flag selection (`.biometryCurrentSet`, `.biometryAny`, `.userPresence`) and keychain-bound patterns
- `secure-enclave.md` — Hardware-backed keys with `SecAccessControl` and `.privateKeyUsage`
- `keychain-item-classes.md` — Class-specific accessibility considerations and primary key composition
- `common-anti-patterns.md` — Anti-pattern #5 (missing `kSecAttrAccessible`), #3 (LAContext-only gate)
- `compliance-owasp-mapping.md` — M9 (Insecure Data Storage) accessibility requirements
---
## Summary Checklist
1. **Always set `kSecAttrAccessible` explicitly** — never rely on the `WhenUnlocked` default; choose the level matching your access context (foreground vs background)
2. **Never set both `kSecAttrAccessible` and `kSecAttrAccessControl`** in the same query dictionary — accessibility belongs inside `SecAccessControlCreateWithFlags`
3. **Use `AfterFirstUnlockThisDeviceOnly`** for any item accessed by background extensions, widgets, VPN, or push notification handlers
4. **Pair `WhenPasscodeSetThisDeviceOnly` with `.biometryCurrentSet`** for highest-security items, and handle item deletion on passcode removal gracefully
5. **Include `.or` or `.and`** when combining multiple authentication flags — omitting the operator causes `errSecParam` (-50)
6. **Set `kSecUseDataProtectionKeychain: true`** on all macOS keychain queries to target the modern Data Protection keychain
7. **Implement re-authentication flows** for `ThisDeviceOnly` items that will be absent after device migration or backup restore
8. **Check `isProtectedDataAvailable`** before keychain access in app launch paths — iOS 15+ pre-warming can start your process before first unlock
9. **Delete and re-add** (not update) when changing `SecAccessControl` on an existing item — `SecItemUpdate` cannot modify access control attributes
10. **Test on physical devices** across lock/unlock, reboot, passcode removal, and biometric enrollment change scenarios — the Simulator does not enforce data protection
11. **Block deprecated `kSecAttrAccessibleAlways` constants** in CI/CD linting and migrate existing items to `AfterFirstUnlock` on next foreground authentication
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |