Securely Manage iOS Keychain Data

This skill covers iOS Keychain Services and building secure, efficient Keychain wrapper libraries - the Security framework, keychain item classes, access controls, and best practices for storing sensitive data on iOS. Keychain item classes: kSecClassGenericPassword (generic passwords and sensitive strings), kSecClassInternetPassword (internet passwords with server/protocol info), kSecClassKey (cryptographic keys), and kSecClassCertificate (X.509 certificates). Access-control fundamentals: kSecAttrAccessible controls when items are accessible, kSecAttrAccessGroup enables keychain sharing between apps, and SecAccessControlCreateWithFlags applies biometric protection.

Wrapper implementation best practices are demonstrated via a thread-safe wrapper class (a dedicated serial DispatchQueue wrapping storage calls, generic Codable item encoding) and an error type providing localized descriptions for each failure mode:

enum KeychainError: Error, LocalizedError {
    case itemNotFound
    case duplicateItem
    case invalidData
    case unexpectedStatus(OSStatus)
    case biometricAuthRequired
    
    var errorDescription: String? {
        switch self {
        case .itemNotFound: return "Keychain item not found"
        case .duplicateItem: return "Item already exists"
        case .invalidData: return "Invalid data format"
        case .unexpectedStatus(let status): return "Keychain error: \(status)"
        case .biometricAuthRequired: return "Biometric authentication required"
        }
    }
}

Advanced implementation patterns cover generic data storage with an accessibility enum (whenUnlocked, whenUnlockedThisDeviceOnly, afterFirstUnlock, whenPasscodeSetThisDeviceOnly, each mapped to its kSecAttrAccessible* constant) used in a store function that calls SecItemAdd and falls back to an update on errSecDuplicateItem. Biometric-authentication integration is shown via SecAccessControlCreateWithFlags with .biometryCurrentSet combined with kSecAttrAccessibleWhenUnlockedThisDeviceOnly, attached as kSecAttrAccessControl on the SecItemAdd query. Keychain sharing between apps is demonstrated by adding kSecAttrAccessGroup to the query so multiple apps under the same group can read the same item.

Security recommendations cover data validation and sanitization (always validate before storage, proper encode/decode for complex types, data-integrity checks for critical items, additional encryption for highly sensitive data) and access-pattern security, shown via a retrieval function that accepts an optional LAContext for biometric-gated retrieval via kSecUseAuthenticationContext, calling SecItemCopyMatching and decoding the result, distinguishing errSecItemNotFound from other unexpected statuses. Migration and cleanup strategies cover version-aware storage for app updates, secure deletion methods handling all item attributes, keychain-item lifecycle management, and planning for iOS version compatibility and deprecations. Testing considerations cover using keychain groups for test isolation, mock wrappers for unit testing, testing accessibility scenarios and device-lock states, and validating biometric-auth flows across devices.

Use it when building or hardening an iOS Keychain wrapper - choosing item classes and accessibility levels, adding biometric protection, sharing items between apps in the same group, or handling keychain errors robustly. It is not a general iOS-security or encryption-at-rest guide beyond the Keychain APIs themselves - it is scoped to Security.framework's keychain item storage and retrieval.

Given a Codable item and a key, it produces store, retrieve, and update code against the appropriate keychain item class, with the requested accessibility level, biometric protection, or access-group sharing configured on the query.

Built on iOS's Security framework (SecItemAdd, SecItemCopyMatching, SecAccessControlCreateWithFlags), Swift's Codable/JSONEncoder/JSONDecoder, and LocalAuthentication's LAContext for biometric-gated access.

iOS developers building or hardening a Keychain wrapper for storing sensitive data securely.