Swift Security

Swift Security

Use this skill for client-side Apple platform security work: Keychain Services, access control, biometric-gated secrets, CryptoKit, Secure Enclave keys, credential storage, certificate trust, keychain sharing, legacy secret migration, security testing, and OWASP mobile compliance mapping.

Default to iOS 17+ and Swift concurrency examples when the deployment target is unknown. Keep iOS 13+ compatibility notes when the user asks for older targets. Treat iOS 26 CryptoKit post-quantum APIs as availability-gated.

Contents

• Workflow
• Reference Loading
• Security Invariants
• Sibling Boundaries
• Review Checklist
• Common Mistakes
• Output Rules
• References

Workflow

Classify the request before loading references.

1. Review existing code: run the Review Checklist, then load common-anti-patterns.md plus the domain reference for each failing area. Report severity, evidence, and the corrected pattern.
2. Improve or migrate code: identify the migration type, load the migration and target-domain references, preserve existing data, verify the new item, then remove legacy storage only after success.
3. Implement new security code: load the minimum domain references, use the provided correct patterns, include OSStatus handling and tests, then run the relevant checklist.

Do not load every reference file by default. This skill is intentionally split for progressive disclosure; load only the files needed by the user's task.

Minimum Safe Keychain Write

Use separate add, identity, and update dictionaries; handle every 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)
    }
}

Load keychain-fundamentals.md for read, delete, access-control, locked-device, and test patterns.

Reference Loading

Security Invariants

Use directive language only for these security invariants and the matching anti-patterns in common-anti-patterns.md. For architecture choices outside this list, use advisory language.

• Never store tokens, passwords, API keys, signing keys, or refresh tokens in UserDefaults, Info.plist, .xcconfig, source code, logs, files, or NSCoding archives. Use Keychain or fetch secrets at runtime.
• Never ignore OSStatus. Every SecItemAdd, SecItemCopyMatching, SecItemUpdate, and SecItemDelete path must handle success and expected failures such as errSecDuplicateItem, errSecItemNotFound, and errSecInteractionNotAllowed.
• Never use LAContext.evaluatePolicy() as the only gate for a secret. Bind protected secrets to keychain items with SecAccessControl, then let keychain access trigger LocalAuthentication.
• Always set kSecAttrAccessible or kSecAttrAccessControl explicitly when adding keychain items.
• Always use add-or-update for persistent keychain writes. Do not delete-then-add as a normal update path.
• Keep SecItem* work off the main actor. Use an actor or serial queue for keychain access.
• On macOS AppKit targets, target the data protection keychain with kSecUseDataProtectionKeychain: true unless deliberately working with legacy file-based keychain items.
• Never reuse an AES-GCM nonce with the same key.
• Never use raw ECDH SharedSecret bytes as a symmetric key. Derive with HKDF or X9.63 derivation.
• Never use Insecure.MD5 or Insecure.SHA1 for security purposes.

Sibling Boundaries

This skill owns client-side storage, cryptographic primitives, hardware-backed keys, and trust evaluation. Route adjacent work deliberately:

• Use authentication for Sign in with Apple, passkeys, OAuth UI flows, ASAuthorizationController, credential state, and account sign-in UX.
• Use cryptokit for primitive CryptoKit API syntax and examples when storage, key lifecycle, protocol/trust design, Secure Enclave policy, certificate trust, misuse review, or compliance is not part of the task.
• Keep application-level E2E encryption security reviews here when the work involves key ownership, derivation, storage, rotation/recovery, Secure Enclave, HPKE/PQC migration, protocol trust boundaries, or misuse analysis.
• Use device-integrity for DeviceCheck and App Attest attestation/assertion flows.
• Use ios-networking for URLSession, request pipelines, ATS configuration, retries, caching, reachability, and transport architecture.
• Use app-store-review for privacy manifests, ATT, App Review guideline compliance, and submission readiness.

This skill may mention those areas only to identify a security handoff.

Review Checklist

Use this checklist for code reviews and migration plans. Mark each item pass, fail, or not applicable; for each failure, cite the reference file and severity.

• Secrets are not stored in UserDefaults, plists, source, logs, files, or archives.
• Every SecItem* call checks OSStatus and handles common recoverable errors.
• Biometric access to secrets is keychain-bound with SecAccessControl, not a standalone Bool from LAContext.evaluatePolicy().
• Keychain add dictionaries set an explicit accessibility policy.
• Keychain writes use add-or-update rather than delete-then-add.
• Keychain work is isolated from UI/main-actor code.
• The selected kSecClass matches the item type and primary-key attributes.
• CryptoKit code avoids nonce reuse, raw shared-secret use, weak hashes, and hardcoded keys.