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-fundamentals.md
View on GitHub# Keychain Fundamentals
> **Scope:** SecItem\* CRUD operations, query dictionary structure, kSecClass types, OSStatus error handling, actor-based wrapper patterns. This is the foundation file — all other reference files assume familiarity with these patterns.
>
> **Key APIs:** `SecItemAdd`, `SecItemCopyMatching`, `SecItemUpdate`, `SecItemDelete`, `kSecClassGenericPassword`, `kSecClassInternetPassword`, `kSecClassKey`, `kSecClassCertificate`, `kSecClassIdentity`
>
> **Apple Documentation:** [Keychain Services](https://sosumi.ai/documentation/security/keychain_services), [TN3137](https://sosumi.ai/documentation/technotes/tn3137-on-mac-keychains), Quinn "The Eskimo!" DTS posts: "SecItem: Fundamentals" and "SecItem: Pitfalls and Best Practices"
---
## Contents
- [Architecture Overview](#architecture-overview)
- [The Four Functions and Their Dictionary Contracts](#the-four-functions-and-their-dictionary-contracts)
- [Uniqueness and Primary Keys](#uniqueness-and-primary-keys)
- [The Add-or-Update Pattern](#the-add-or-update-pattern)
- [Reading from the Keychain: Return Flags and Type Casting](#reading-from-the-keychain-return-flags-and-type-casting)
- [Return Type Cheat Sheet](#return-type-cheat-sheet)
- [String Keys vs. kSec\* Constants](#string-keys-vs-ksec-constants)
- [Centralized Query Builder](#centralized-query-builder)
- [OSStatus Error Handling](#osstatus-error-handling)
- [Actor-Isolated Keychain Manager (iOS 17+ / macOS 14+)](#actor-isolated-keychain-manager-ios-17-macos-14)
- [Why Actors over GCD](#why-actors-over-gcd)
- [Legacy GCD Pattern (iOS 13–16 codebases)](#legacy-gcd-pattern-ios-1316-codebases)
- [Performance Architecture](#performance-architecture)
- [Two-Tier Encryption and Query Cost](#two-tier-encryption-and-query-cost)
- [Query Specificity](#query-specificity)
- [App Launch Performance](#app-launch-performance)
- [Batch Operations](#batch-operations)
- [macOS Keychain Routing (TN3137)](#macos-keychain-routing-tn3137)
- [Accessibility and Data Protection Classes](#accessibility-and-data-protection-classes)
- [Cross-References](#cross-references)
- [Authoritative References](#authoritative-references)
- [Implementation Notes](#implementation-notes)
- [Summary Checklist](#summary-checklist)
## Architecture Overview
The Keychain Services API exposes four C functions that map to database CRUD operations. Every call is an IPC round-trip to the `securityd` daemon, backed by an encrypted SQLite database. This means every call **blocks the calling thread** and must never execute on `@MainActor`.
Internally, keychain items use **two-tier AES-256-GCM encryption** (per the Apple Platform Security Guide): a table-level **metadata key** cached in the Application Processor for fast attribute searches, and a **per-row secret key** requiring a Secure Enclave round-trip for `kSecValueData` decryption. This two-tier design has direct performance implications covered in the Performance section below.
---
## The Four Functions and Their Dictionary Contracts
Each function accepts a specific _type_ of dictionary. Confusing which keys belong in which dictionary is the single most common source of bugs. Quinn (Apple DTS) defines five property groups:
1. **Item class** — `kSecClass`
2. **Item attributes** — `kSecAttrAccount`, `kSecAttrService`, etc.
3. **Search properties** — `kSecMatchLimit`
4. **Return type properties** — `kSecReturnData`, `kSecReturnAttributes`, `kSecReturnRef`, `kSecReturnPersistentRef`
5. **Value type properties** — `kSecValueData`, `kSecValueRef`
| Function | Dictionary Type | Supports Return Keys? | Default `kSecMatchLimit` | Since |
| --------------------------- | -------------------------------------------- | ----------------------- | ------------------------ | ------- |
| `SecItemAdd(_:_:)` | Add dictionary (class + attrs + values) | ✅ Optional | N/A | iOS 2.0 |
| `SecItemCopyMatching(_:_:)` | Query + return (all 5 groups) | ✅ Required for results | `kSecMatchLimitOne` | iOS 2.0 |
| `SecItemUpdate(_:_:)` | Pure query (param 1) + update dict (param 2) | ❌ | **`kSecMatchLimitAll`** | iOS 2.0 |
| `SecItemDelete(_:)` | Pure query | ❌ | **`kSecMatchLimitAll`** | iOS 2.0 |
**Critical detail:** `kSecMatchLimit` defaults to `kSecMatchLimitOne` for `SecItemCopyMatching` but **`kSecMatchLimitAll` for `SecItemUpdate` and `SecItemDelete`**. An under-specified delete query will wipe every matching item in the keychain.
**Dictionary hygiene:** Use a fresh dictionary for each call. Putting `kSecReturnData` in an add dictionary or `kSecClass` in an update dictionary produces `errSecParam` (-50). Quinn's guidance: "Use a new dictionary for each call. That prevents state from one call accidentally leaking into a subsequent call."
---
## Uniqueness and Primary Keys
For `kSecClassGenericPassword`, uniqueness is determined by the combination of:
- `kSecAttrAccount` + `kSecAttrService` + `kSecAttrAccessGroup` + `kSecAttrSynchronizable`
Other attributes like `kSecAttrGeneric`, `kSecAttrLabel`, or `kSecAttrDescription` **do not participate in uniqueness**. This means a query filtering on non-unique attributes can return `errSecItemNotFound` while a subsequent add still hits `errSecDuplicateItem`.
For `kSecClassInternetPassword`, the uniqueness set includes: `kSecAttrAccount` + `kSecAttrServer` + `kSecAttrProtocol` + `kSecAttrAuthenticationType` + `kSecAttrPort` + `kSecAttrPath` + `kSecAttrSecurityDomain` + `kSecAttrAccessGroup` + `kSecAttrSynchronizable`.
**Immutable attributes:** `kSecAttrAccount` and `kSecClass` cannot be changed via `SecItemUpdate`. To change them, delete and re-add the item (see `keychain-item-classes.md`).
---
## The Add-or-Update Pattern
The most common AI-generated keychain bug is calling `SecItemAdd` without handling `errSecDuplicateItem` (-25299).
❌ **Naive add that silently fails on duplicate:**
```swift
// ❌ WRONG — silently fails if item already exists
func savePassword(_ password: String, account: String) {
let query: [CFString: Any] = [
kSecClass: kSecClassGenericPassword,
kSecAttrService: "com.example.app",
kSecAttrAccount: account,
kSecValueData: Data(password.utf8)
]
SecItemAdd(query as CFDictionary, nil) // Return value IGNORED!
// If item exists → errSecDuplicateItem (-25299) — password never saved
}
```
✅ **Correct add-or-update with exhaustive OSStatus handling:**
```swift
// ✅ CORRECT — attempts add, falls back to update on duplicate
func savePassword(_ password: String, account: String) throws {
let baseQuery: [CFString: Any] = [
kSecClass: kSecClassGenericPassword,
kSecAttrService: "com.example.app",
kSecAttrAccount: account
]
var addQuery = baseQuery
addQuery[kSecValueData] = Data(password.utf8)
addQuery[kSecAttrAccessible] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
let addStatus = SecItemAdd(addQuery as CFDictionary, nil)
switch addStatus {
case errSecSuccess:
return
case errSecDuplicateItem:
// Item exists — update it
let updates: [CFString: Any] = [kSecValueData: Data(password.utf8)]
let updateStatus = SecItemUpdate(
baseQuery as CFDictionary,
updates as CFDictionary
)
guard updateStatus == errSecSuccess else {
throw KeychainError(status: updateStatus)
}
case errSecInteractionNotAllowed:
// Device locked — do NOT delete-and-retry!
throw KeychainError(status: addStatus)
default:
throw KeychainError(status: addStatus)
}
}
```
Key points in this pattern:
- **Separate dictionaries** for add vs. update — the update dictionary contains only the attributes to change, never `kSecClass` or search properties.
- **`errSecInteractionNotAllowed`** (-25308) means the device is locked and data protection prevents access. Never delete items in response to this error; the item is valid but temporarily inaccessible.
- **Prefer update over delete-then-add** — update preserves persistent references and avoids the race condition window between delete and add.
---
## Reading from the Keychain: Return Flags and Type Casting
The second most common bug is calling `SecItemCopyMatching` without `kSecReturn*` flags. The function may return `errSecSuccess` with a `nil` result — this is "success but nil," not a real success.
❌ **Query that returns no data because `kSecReturnData` is missing:**
```swift
// ❌ WRONG — no kSecReturn* flags, result is always nil
func loadPassword(account: String) -> Data? {
let query: [CFString: Any] = [
kSecClass: kSecClassGenericPassword,
kSecAttrService: "com.example.app",
kSecAttrAccount: account,
kSecMatchLimit: kSecMatchLimitOne
// BUG: Missing kSecReturnData: true
]
var result: CFTypeRef?
SecItemCopyMatching(query as CFDictionary, &result)
return result as? Data // Always nil — no return type was requested
}
```
✅ **Correct query with proper return flags and exhaustive error handling:**
```swift
// ✅ CORRECT — explicitly requests data, handles all error states
func loadPassword(account: String) throws -> Data? {
let query: [CFString: Any] = [
kSecClass: kSecClassGenericPassword,
kSecAttrService: "com.example.app",
kSecAttrAccount: account,
kSecMatchLimit: kSecMatchLimitOne,
kSecReturnData: true // ← REQUIRED to get the secret
]
var result: CFTypeRef?
let status = SecItemCopyMatching(query as CFDictionary, &result)
switch status {
case errSecSuccess:
guard let data = result as? Data else {
throw KeychainError(status: errSecParam)
}
return data
case errSecItemNotFound:
return nil // Legitimate "not found" — not an error
case errSecInteractionNotAllowed:
throw KeychainError(status: status)
default:
throw KeychainError(status: status)
}
}
```
### Return Type Cheat Sheet
The `CFTypeRef` type depends entirely on which return flags and match limits are set:
```text
kSecReturnData only + kSecMatchLimitOne → Data
kSecReturnAttributes + kSecMatchLimitOne → [String: Any]
kSecReturnData + Attrs + kSecMatchLimitOne → [String: Any] (data under kSecValueData key)
kSecReturnRef + kSecMatchLimitOne → SecKey / SecCertificate / SecIdentity
kSecReturnPersistentRef + kSecMatchLimitOne → Data (opaque handle)
Any combination + kSecMatchLimitAll → Array of the above type
```
**Note:** Combining `kSecReturnData` with `kSecMatchLimitAll` may be restricted for password classes on some OS versions. For listing items, prefer `kSecReturnAttributes` or `kSecReturnRef` with `kSecMatchLimitAll`, then fetch data per-item as needed.
### String Keys vs. kSec\* Constants
Never use raw string literals (`"svce"`, `"class"`) instead of `kSec*` constants. The constants are `CFString` values with specific internal representations. Two equally valid dictionary key styles exist:
```swift
// Style A: CFString keys (fewer casts at definition, cast once at call site)
let query: [CFString: Any] = [kSecClass: kSecClassGenericPassword]
SecItemAdd(query as CFDictionary, nil)
// Style B: String keys (more common in community code)
let query: [String: Any] = [kSecClass as String: kSecClassGenericPassword]
SecItemAdd(query as CFDictionary, nil)
```
Both are correct. Pick one style and use it consistently across your codebase.
---
## Centralized Query Builder
Centralize query construction to prevent flag omissions and key typos:
```swift
enum KeychainQueryBuilder {
static func buildQuery(
forClass secClass: CFString = kSecClassGenericPassword,
account: String? = nil,
service: String? = nil,
accessGroup: String? = nil,
returnData: Bool = false,
returnAttributes: Bool = false,
matchLimit: CFString = kSecMatchLimitOne
) -> [String: Any] {
var query: [String: Any] = [kSecClass as String: secClass]
if let account { query[kSecAttrAccount as String] = account }
if let service { query[kSecAttrService as String] = service }
if let group = accessGroup { query[kSecAttrAccessGroup as String] = group }
if returnData { query[kSecReturnData as String] = kCFBooleanTrue! }
if returnAttributes { query[kSecReturnAttributes as String] = kCFBooleanTrue! }
query[kSecMatchLimit as String] = matchLimit
return query
}
}
```
This pattern ensures return flags are set deliberately and provides a single site to audit query construction.
---
## OSStatus Error Handling
Never treat all non-zero `OSStatus` values as fatal errors. Several codes represent expected operational states:
| OSStatus Code | Constant | Meaning | Correct Response |
| ------------- | ----------------------------- | -------------------------------------------------- | ------------------------------------------ |
| `0` | `errSecSuccess` | Operation succeeded | Proceed normally |
| `-25299` | `errSecDuplicateItem` | Item already exists (on add) | Fall back to `SecItemUpdate` |
| `-25300` | `errSecItemNotFound` | No matching item found | Return `nil` / treat as success for delete |
| `-25308` | `errSecInteractionNotAllowed` | Device locked, data protection active | Retry later — **never delete** |
| `-25293` | `errSecUserCanceled` | User cancelled biometric prompt | Propagate cancellation to UI |
| `-50` | `errSecParam` | Invalid parameter / wrong dictionary keys | Developer error — fix query |
| `-25244` | `errSecNoSuchAttr` | Attribute not supported (data protection keychain) | Check for unsupported attributes |
Map raw codes to a domain-specific Swift error:
```swift
struct KeychainError: Error, CustomStringConvertible {
let status: OSStatus
var description: String {
let msg = SecCopyErrorMessageString(status, nil) as String? ?? "Unknown"
return "KeychainError(\(status)): \(msg)"
}
}
```
**Logging safety:** Log only the query shape and resulting status code. Never log secret data (`kSecValueData`), tokens, or keys.
---
## Actor-Isolated Keychain Manager (iOS 17+ / macOS 14+)
Every `SecItem*` function blocks the calling thread due to IPC to `securityd` and potential Secure Enclave round-trips. For biometry-protected items, the block can last several seconds during user authentication (WWDC 2014 Session 711).
❌ **`@MainActor` keychain access that blocks the UI:**
```swift
// ❌ WRONG — blocks main thread, freezes UI during securityd IPC
@MainActor
class SettingsViewModel: ObservableObject {
@Published var token: String = ""
func loadToken() {
let query: [CFString: Any] = [
kSecClass: kSecClassGenericPassword,
kSecAttrService: "com.example.app",
kSecAttrAccount: "authToken",
kSecReturnData: true,
kSecMatchLimit: kSecMatchLimitOne
]
var result: CFTypeRef?
let status = SecItemCopyMatching(query as CFDictionary, &result)
if status == errSecSuccess, let data = result as? Data {
self.token = String(data: data, encoding: .utf8) ?? ""
}
// UI frozen for entire duration of securityd IPC + potential SE round-trip
}
}
```
✅ **Actor-isolated keychain manager with full CRUD:**
```swift
// ✅ CORRECT — dedicated actor keeps all SecItem calls off @MainActor
actor KeychainManager {
static let shared = KeychainManager()
private let service: String
init(service: String = Bundle.main.bundleIdentifier ?? "default") {
self.service = service
}
// MARK: - Save (add-or-update)
func save(_ data: Data, for key: String,
accessibility: CFTypeRef = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
) throws {
let baseQuery: [CFString: Any] = [
kSecClass: kSecClassGenericPassword,
kSecAttrService: service,
kSecAttrAccount: key
]
var addQuery = baseQuery
addQuery[kSecValueData] = data
addQuery[kSecAttrAccessible] = accessibility
let addStatus = SecItemAdd(addQuery as CFDictionary, nil)
switch addStatus {
case errSecSuccess:
return
case errSecDuplicateItem:
let updates: [CFString: Any] = [kSecValueData: data]
let updateStatus = SecItemUpdate(
baseQuery as CFDictionary,
updates as CFDictionary
)
guard updateStatus == errSecSuccess else {
throw KeychainError(status: updateStatus)
}
case errSecInteractionNotAllowed:
throw KeychainError(status: addStatus)
default:
throw KeychainError(status: addStatus)
}
}
// MARK: - Load
func load(for key: String) throws -> Data? {
let query: [CFString: Any] = [
kSecClass: kSecClassGenericPassword,
kSecAttrService: service,
kSecAttrAccount: key,
kSecReturnData: true,
kSecMatchLimit: kSecMatchLimitOne
]
var result: CFTypeRef?
let status = SecItemCopyMatching(query as CFDictionary, &result)
switch status {
case errSecSuccess:
return result as? Data
case errSecItemNotFound:
return nil
case errSecInteractionNotAllowed:
throw KeychainError(status: status)
default:
throw KeychainError(status: status)
}
}
// MARK: - Delete (idempotent)
func delete(key: String) throws {
let query: [CFString: Any] = [
kSecClass: kSecClassGenericPassword,
kSecAttrService: service,
kSecAttrAccount: key
]
let status = SecItemDelete(query as CFDictionary)
guard status == errSecSuccess || status == errSecItemNotFound else {
throw KeychainError(status: status)
}
}
// MARK: - List all accounts (attributes only — fast)
func allAccounts() throws -> [String] {
let query: [CFString: Any] = [
kSecClass: kSecClassGenericPassword,
kSecAttrService: service,
kSecMatchLimit: kSecMatchLimitAll,
kSecReturnAttributes: true // No kSecReturnData → skips SE round-trip
]
var result: CFTypeRef?
let status = SecItemCopyMatching(query as CFDictionary, &result)
switch status {
case errSecSuccess:
guard let items = result as? [[String: Any]] else { return [] }
return items.compactMap { $0[kSecAttrAccount as String] as? String }
case errSecItemNotFound:
return []
default:
throw KeychainError(status: status)
}
}
}
```
**Calling from SwiftUI:**
```swift
@MainActor
class AuthViewModel: ObservableObject {
@Published var isAuthenticated = false
func loadToken() async {
do {
// Crosses actor boundary — suspends, does NOT block MainActor
let data = try await KeychainManager.shared.load(for: "authToken")
isAuthenticated = data != nil
} catch {
isAuthenticated = false
}
}
}
```
### Why Actors over GCD
| Dimension | Actor (iOS 17+) | GCD Serial Queue |
| --------------------- | --------------------------------- | --------------------------------------- |
| UI blocking | Low — compiler-enforced isolation | Low (if dispatched correctly) |
| Thread safety | Serialized by actor runtime | Manual — developer discipline |
| Readability | Linear async/await | Nested completion handlers |
| Compiler guarantees | Enforced `Sendable` + isolation | None — silent data races possible |
| Swift 6 compatibility | Native — actors are `Sendable` | Requires manual `@Sendable` annotations |
### Legacy GCD Pattern (iOS 13–16 codebases)
```swift
class LegacyKeychainManager {
private let queue = DispatchQueue(label: "com.app.keychain",
qos: .userInitiated)
func load(key: String, completion: @escaping (Result<Data?, Error>) -> Void) {
queue.async {
// ... SecItemCopyMatching on background queue ...
DispatchQueue.main.async { completion(result) }
}
}
}
```
---
## Performance Architecture
### Two-Tier Encryption and Query Cost
Because of the two-tier encryption design:
- **`kSecReturnAttributes` only** → uses cached metadata key → **fast** (no Secure Enclave round-trip)
- **`kSecReturnData`** → requires per-row secret key from Secure Enclave → **slower**
For listing operations, always use `kSecReturnAttributes` or `kSecReturnRef` and fetch secret data only for the specific item the user selects.
### Query Specificity
The underlying SQLite database benefits from narrow constraints. A query specifying only `kSecClass: kSecClassGenericPassword` with `kSecMatchLimitAll` performs a **full table scan**. Adding `kSecAttrService` and `kSecAttrAccount` enables indexed lookup. Always include all relevant uniqueness attributes in production queries.
### App Launch Performance
Keychain access during app launch is a measurable performance risk:
- Each call requires IPC to `securityd` plus potential Secure Enclave latency
- Items with `kSecAttrAccessibleWhenUnlocked` may be unavailable before first unlock (iOS can launch apps before the user unlocks — e.g., background refresh, VoIP pushes)
- **Best practice:** Defer keychain reads until actually needed. Never call SecItem synchronously in `application(_:didFinishLaunchingWithOptions:)`.
- Handle `errSecInteractionNotAllowed` gracefully — never destructively.
### Batch Operations
There is **no batch API** for SecItem. Each function operates individually with one partial exception: `SecItemAdd` supports `kSecUseItemList` to add multiple certificates or keys (not passwords) in a single call. For batch reads, `SecItemCopyMatching` with `kSecMatchLimitAll` retrieves all matching items at once.
---
## macOS Keychain Routing (TN3137)
On macOS, the SecItem API can target two different implementations:
| Implementation | Activated By | Behavior |
| ------------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Legacy file-based keychain** | Default on macOS (without opt-in) | Silently ignores unsupported attributes; inconsistent `kSecMatchLimit` defaults; different `SecItemAdd` return types |
| **Data protection keychain** | `kSecUseDataProtectionKeychain: true` (macOS 10.15+) or `kSecAttrSynchronizable: true` | Parity with iOS; required for iCloud Keychain sync, biometric protection, and Secure Enclave key storage |
**Modern apps must always target the data protection keychain.** Mac Catalyst and iOS Apps on Mac use it automatically.
```swift
// macOS: Always opt into data protection keychain
var query: [CFString: Any] = [
kSecClass: kSecClassGenericPassword,
kSecAttrService: "com.example.app",
kSecAttrAccount: "token"
]
#if os(macOS)
query[kSecUseDataProtectionKeychain] = true
#endif
```
The file-based keychain's shim layer has documented bugs — it silently ignores unsupported attributes where the data protection keychain correctly returns `errSecNoSuchAttr` (-25244). Debugging keychain issues on macOS often starts with confirming which implementation is in use.
---
## Accessibility and Data Protection Classes
The `kSecAttrAccessible` attribute controls when a keychain item's secret data can be decrypted. Brief guidance here; see `keychain-access-control.md` for full coverage.
| Constant | Available When | Survives Backup? | Use Case |
| -------------------------------------------------- | -------------------------------- | ---------------- | -------------------------------------------- |
| `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` | After unlock, until lock | No (device-only) | Default for most secrets |
| `kSecAttrAccessibleAfterFirstUnlock` | After first unlock until restart | Yes | Background processing tokens |
| `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly` | Only if passcode set + unlocked | No | Highest-sensitivity data (OWASP recommended) |
| `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` | After first unlock until restart | No | Background + device-only |
**Deprecated:** `kSecAttrAccessibleAlways` — deprecated in iOS 12, unsupported on Apple Silicon Macs. Never use.
---
## Cross-References
- **Item class deep dive** (required vs optional attributes per kSecClass) → `keychain-item-classes.md`
- **Access control flags and SecAccessControl** → `keychain-access-control.md`
- **Biometric-gated keychain access** (LAContext integration) → `biometric-authentication.md`
- **Secure Enclave key storage** → `secure-enclave.md`
- **Credential lifecycle patterns** (OAuth tokens, API keys) → `credential-storage-patterns.md`
- **Access groups and sharing** → `keychain-sharing.md`
- **Testing keychain code** (mocks, CI/CD) → `testing-security-code.md`
- **Common anti-patterns** (comprehensive catalog) → `common-anti-patterns.md`
---
## Authoritative References
| Source | Relevance |
| ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| [Keychain Services](https://sosumi.ai/documentation/security/keychain_services) | Main API landing page |
| [TN3137: On Mac Keychain APIs and Implementations](https://sosumi.ai/documentation/technotes/tn3137-on-mac-keychains) | macOS data protection vs file-based routing |
| Quinn "The Eskimo!" — "SecItem: Fundamentals" / "SecItem: Pitfalls and Best Practices" | Most practical DTS reference, updated through 2025 |
| [Apple Platform Security Guide](https://support.apple.com/guide/security/welcome/web) — Keychain Data Protection chapter | Two-tier encryption architecture |
| WWDC 2014 Session 711 — "Keychain and Authentication with Touch ID" | Touch ID/keychain integration patterns |
| WWDC 2019 Session 516 — "What's New in Authentication" | Modern credential management |
---
## Implementation Notes
1. **Dictionary key type convention:** Both `[CFString: Any]` and `[String: Any]` with `kSec* as String` casts are valid. This file uses `[CFString: Any]` for concise examples and shows both styles in the String Keys section.
2. **Default accessibility recommendation:** `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly` is strongest for high-security secrets, but items become unavailable if the user removes their passcode. `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` is a safe general foreground-only default. The actor manager example uses `AfterFirstUnlockThisDeviceOnly` for background compatibility while remaining device-bound.
3. **`kSecReturnData` + `kSecMatchLimitAll`:** Some OS versions and keychain implementations have restrictions around returning data for multiple password-class matches. The safer pattern is to use `kSecReturnRef` or `kSecReturnAttributes` with `LimitAll`, then fetch data per item. See the Return Type Cheat Sheet.
---
## Summary Checklist
Before shipping keychain code, verify:
1. **OSStatus checked on every call** — exhaustive `switch` covering at minimum `errSecSuccess`, `errSecDuplicateItem`, `errSecItemNotFound`, `errSecInteractionNotAllowed`; no ignored return values
2. **Add-or-update pattern implemented** — `SecItemAdd` catches `-25299` and falls back to `SecItemUpdate`; duplicate saves never crash or silently fail
3. **Return flags explicitly set** — every `SecItemCopyMatching` call includes at least one `kSecReturn*` flag; no "success but nil" bugs
4. **CFTypeRef cast matches flags** — cast type corresponds to the combination of return flags and match limit (see Return Type Cheat Sheet)
5. **Zero SecItem calls on `@MainActor`** — all keychain access isolated in a dedicated `actor` (iOS 17+) or serial `DispatchQueue` (iOS 13–16)
6. **Fresh dictionaries per call** — no dictionary reuse across SecItem functions; add dict, query dict, and update dict are separate
7. **kSec\* constants used** — no raw string literals for dictionary keys; using either `[CFString: Any]` or `[String: Any]` with `as String` casts
8. **Queries are specific** — `kSecAttrService` + `kSecAttrAccount` included for GenericPassword; `kSecMatchLimitOne` used unless enumeration is needed
9. **Delete treats not-found as success** — `errSecItemNotFound` on delete is a valid postcondition, not an error
10. **macOS targets data protection keychain** — `kSecUseDataProtectionKeychain: true` set for macOS targets (automatic for Catalyst/iOS-on-Mac)
11. **errSecInteractionNotAllowed handled non-destructively** — device-locked state triggers retry-later logic, never delete-and-recreate
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 |