axiom-keychain-ref（Axiom 钥匙扣参考）

Keychain Services API Reference

Comprehensive API reference for iOS/macOS Keychain Services: SecItem CRUD functions, item class attributes, uniqueness constraints, accessibility levels, access control flags, biometric integration, and error codes.

Quick Reference

// Add a generic password
let addQuery: [String: Any] = [
    kSecClass as String: kSecClassGenericPassword,
    kSecAttrService as String: "com.example.app",
    kSecAttrAccount as String: "user@example.com",
    kSecValueData as String: "secret".data(using: .utf8)!
]
let addStatus = SecItemAdd(addQuery as CFDictionary, nil)

// Read a generic password
let readQuery: [String: Any] = [
    kSecClass as String: kSecClassGenericPassword,
    kSecAttrService as String: "com.example.app",
    kSecAttrAccount as String: "user@example.com",
    kSecReturnData as String: true,
    kSecMatchLimit as String: kSecMatchLimitOne
]
var result: AnyObject?
let readStatus = SecItemCopyMatching(readQuery as CFDictionary, &result)
let data = result as? Data

// Update a generic password
let updateQuery: [String: Any] = [
    kSecClass as String: kSecClassGenericPassword,
    kSecAttrService as String: "com.example.app",
    kSecAttrAccount as String: "user@example.com"
]
let updateAttributes: [String: Any] = [
    kSecValueData as String: "newSecret".data(using: .utf8)!
]
let updateStatus = SecItemUpdate(updateQuery as CFDictionary, updateAttributes as CFDictionary)

// Delete a generic password
let deleteQuery: [String: Any] = [
    kSecClass as String: kSecClassGenericPassword,
    kSecAttrService as String: "com.example.app",
    kSecAttrAccount as String: "user@example.com"
]
let deleteStatus = SecItemDelete(deleteQuery as CFDictionary)

SecItem Functions

SecItemAdd

func SecItemAdd(_ attributes: CFDictionary, _ result: UnsafeMutablePointer<CFTypeRef?>?) -> OSStatus

attributes dictionary accepts: Item class + item attributes + value properties + return type properties.

Does NOT accept search properties (kSecMatch*). Providing kSecMatchLimit in an add query is an error.

result: Pass nil if you don't need the added item back. Pass a pointer to receive the item in the format specified by kSecReturn* keys. Pass nil in most cases — requesting the result back forces an extra read.

SecItemCopyMatching

func SecItemCopyMatching(_ query: CFDictionary, _ result: UnsafeMutablePointer<CFTypeRef?>?) -> OSStatus

query dictionary accepts: Item class + item attributes + search properties + return type properties.

Does NOT accept value properties (kSecValueData) as search criteria.

result: The type depends on which kSecReturn* keys are set:

• kSecReturnData alone → CFData
• kSecReturnAttributes alone → CFDictionary
• kSecReturnRef alone → SecKey / SecCertificate / SecIdentity
• kSecReturnPersistentRef alone → CFData (persistent reference)
• Multiple kSecReturn* keys → CFDictionary containing requested types
• kSecMatchLimit = kSecMatchLimitAll → CFArray of the above

SecItemUpdate

func SecItemUpdate(_ query: CFDictionary, _ attributesToUpdate: CFDictionary) -> OSStatus

query dictionary accepts: Item class + item attributes + search properties. Used to find items to update.

attributesToUpdate dictionary accepts: Item attributes + value properties. These are applied to matched items. Does NOT accept item class or search properties.

Updating kSecValueData replaces the stored secret. Updating attributes (e.g., kSecAttrLabel) changes metadata without touching the secret.

SecItemDelete

func SecItemDelete(_ query: CFDictionary) -> OSStatus

query dictionary accepts: Item class + item attributes + search properties.

On macOS, deletes ALL matching items by default (implicit kSecMatchLimitAll). On iOS, also deletes all matches. There is no confirmation — deletion is immediate.

Item Classes

kSecClassGenericPassword

General-purpose secret storage. The most commonly used class.

kSecClassInternetPassword

URL-associated credentials. Rarely needed — most apps use generic passwords.

kSecClassCertificate

X.509 certificates. Typically managed by the system, not app code.

kSecClassKey

Cryptographic keys (RSA, EC, AES). Used for encryption, signing, key agreement.

kSecClassIdentity

A digital identity is a certificate paired with its private key. Not a distinct storage class — the system synthesizes it from a matching certificate and key. You cannot add a kSecClassIdentity item directly; add the certificate and key separately. Queries return an identity when both halves share the same kSecAttrPublicKeyHash.

See Quinn "The Eskimo!"'s technote: "SecItem: Pitfalls and Best Practices" (forums/thread/724013) — digital identities are a virtual join, not a stored item.

Uniqueness Constraints Per Class

Each keychain item is uniquely identified by a subset of its attributes. Adding a second item with the same primary key returns errSecDuplicateItem (-25299). Use SecItemUpdate to modify existing items.

Consequence: If you store tokens for multiple users under the same kSecAttrService without unique kSecAttrAccount values, SecItemAdd returns errSecDuplicateItem for the second user.

Attribute Constants Reference

Identity Attributes

Security Attributes

kSecAttrAccessible and kSecAttrAccessControl are mutually exclusive. Setting both is an error — kSecAttrAccessControl includes an accessibility level in its creation.

Token Attributes

Key Metadata Attributes

Search Properties

Used in SecItemCopyMatching, SecItemUpdate (query parameter), and SecItemDelete queries.

kSecMatchLimit Defaults

The default depends on context and is a common source of bugs:

Always set kSecMatchLimit explicitly in SecItemCopyMatching to make intent clear. For SecItemDelete, omitting kSecMatchLimit deletes all matches — this is by design, not a bug.

Return Type Properties

Control what SecItemCopyMatching and SecItemAdd return. Set in the query dictionary.

Return Type Behavior Per Class

Multiple Return Types

When multiple kSecReturn* keys are true, the result is a CFDictionary with keys:

• kSecValueData → the data
• kSecValueRef → the ref
• kSecValuePersistentRef → the persistent ref
• Plus all attribute keys if kSecReturnAttributes is true

When kSecMatchLimitAll is set, the result is a CFArray of the above.

Value Type Properties

Used to provide or extract values in add, query, and update dictionaries.

Behavior Per Operation

Accessibility Constants

Controls when keychain items are readable. Set via kSecAttrAccessible.

Default: kSecAttrAccessibleWhenUnlocked for new items.

ThisDeviceOnly variants: Item is not included in encrypted backups and does not sync via iCloud Keychain. Use for device-bound secrets (biometric-gated tokens, Secure Enclave keys).

WhenPasscodeSetThisDeviceOnly: Item is deleted if the user removes their passcode. Use for secrets that must not survive passcode removal.

AfterFirstUnlock: Available in the background after the user unlocks once post-reboot. Required for background fetch, push notification handlers, and background URLSession completions.

Deprecated (do not use): kSecAttrAccessibleAlways, kSecAttrAccessibleAlwaysThisDeviceOnly.

SecAccessControlCreateFlags

Fine-grained access control for keychain items. Created with SecAccessControlCreateWithFlags and set via kSecAttrAccessControl.

All Flags

Creating Access Control

var error: Unmanaged<CFError>?
guard let accessControl = SecAccessControlCreateWithFlags(
    kCFAllocatorDefault,
    kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
    [.biometryCurrentSet, .or, .devicePasscode],
    &error
) else {
    let nsError = error!.takeRetainedValue() as Error
    fatalError("Failed to create access control: \(nsError)")
}

let query: [String: Any] = [
    kSecClass as String: kSecClassGenericPassword,
    kSecAttrService as String: "com.example.app",
    kSecAttrAccount as String: "auth-token",
    kSecAttrAccessControl as String: accessControl,
    kSecValueData as String: tokenData
]
let status = SecItemAdd(query as CFDictionary, nil)

Flag Combinations

.biometryAny vs .biometryCurrentSet: Use .biometryCurrentSet for high-security items (banking tokens). If the user enrolls a new fingerprint, the item becomes inaccessible — your app must re-authenticate and re-store. Use .biometryAny for convenience items where new enrollment should not invalidate access.

LocalAuthentication Integration

LAContext with Keychain

Pre-evaluate biometrics with LAContext, then pass the context to the keychain query to avoid a second biometric prompt.

import LocalAuthentication

let context = LAContext()
context.localizedReason = "Access your credentials"

var authError: NSError?
guard context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &authError) else {
    // Biometrics unavailable — handle error or fall back to passcode
    return
}

context.evaluatePolicy(
    .deviceOwnerAuthenticationWithBiometrics,
    localizedReason: "Authenticate to access credentials"
) { success, error in
    guard success else { return }

    let query: [String: Any] = [
        kSecClass as String: kSecClassGenericPassword,
        kSecAttrService as String: "com.example.app",
        kSecAttrAccount as String: "auth-token",
        kSecReturnData as String: true,
        kSecMatchLimit as String: kSecMatchLimitOne,
        kSecUseAuthenticationContext as String: context
    ]
    var result: AnyObject?
    let status = SecItemCopyMatching(query as CFDictionary, &result)
}

LAContext Keychain Keys

kSecUseAuthenticationUIFail: Returns errSecInteractionNotAllowed instead of showing the biometric prompt. Use to check if an item exists without triggering UI.

LAPolicy Types

BiometryType Detection

let context = LAContext()
var error: NSError?
context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &error)

switch context.biometryType {
case .faceID:    // Face ID available
case .touchID:   // Touch ID available
case .opticID:   // Optic ID available (visionOS)
case .none:      // No biometric hardware
@unknown default: break
}

LAError Codes

OSStatus Error Codes

Common keychain OSStatus values and their root causes.

Interpreting OSStatus in Swift

let status = SecItemAdd(query as CFDictionary, nil)
if status != errSecSuccess {
    let message = SecCopyErrorMessageString(status, nil) as? String ?? "Unknown error"
    print("Keychain error \(status): \(message)")
}

-34018 on Test Targets

Unit test runners (XCTest) often lack the keychain-access-groups entitlement. Workarounds:

1. Add a Host Application to the test target (Xcode → Test Target → General → Host Application)
2. Use an in-memory mock for unit tests, real keychain for integration tests only

Keychain Sharing

Access Groups

Items are isolated per app by default. To share between apps or extensions:

1. Enable "Keychain Sharing" capability in Xcode
2. Add shared access group identifiers
3. Set kSecAttrAccessGroup when adding items

let query: [String: Any] = [
    kSecClass as String: kSecClassGenericPassword,
    kSecAttrService as String: "com.example.shared",
    kSecAttrAccount as String: "shared-token",
    kSecAttrAccessGroup as String: "TEAMID.com.example.shared",
    kSecValueData as String: tokenData
]

The access group format is $(TeamIdentifierPrefix)$(GroupIdentifier). Items without an explicit access group default to the app's first access group in its entitlements.

iCloud Keychain Sync

Set kSecAttrSynchronizable to true to sync via iCloud Keychain:

let query: [String: Any] = [
    kSecClass as String: kSecClassGenericPassword,
    kSecAttrService as String: "com.example.app",
    kSecAttrAccount as String: "sync-token",
    kSecAttrSynchronizable as String: true,
    kSecValueData as String: tokenData
]

Synchronizable items cannot use ThisDeviceOnly accessibility levels or SecAccessControl. They must use kSecAttrAccessibleWhenUnlocked or kSecAttrAccessibleAfterFirstUnlock.

When querying, kSecAttrSynchronizable defaults to kSecAttrSynchronizableAny (returns both local and synced items). Set explicitly to true or false to filter.

Resources

WWDC: 2013-709, 2014-711, 2020-10147

Docs: /security/keychain_services, /localauthentication, /security/secaccesscontrolcreateflags, /security/secitemadd(*:*:)

Skills: axiom-code-signing-ref, axiom-app-attest