/swift-security

name: swift-security
description: Use 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.
license: MIT

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](#workflow)
• [Reference Loading](#reference-loading)
• [Security Invariants](#security-invariants)
• [Sibling Boundaries](#sibling-boundaries)
• [Review Checklist](#review-checklist)
• [Common Mistakes](#common-mistakes)
• [Output Rules](#output-rules)
• [References](#references)

Workflow

Classify the request before loading references.

1. Review existing code: run the [Review Checklist](#review-checklist), then load [common-anti-patterns.md](references/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](references/keychain-fundamentals.md) for read, delete, access-control, locked-device, and test patterns.

Reference Loading

| If the task involves | Load | | --- | --- | | General keychain CRUD or OSStatus handling | [keychain-fundamentals.md](references/keychain-fundamentals.md) | | Choosing `kSecClass` or item identity | [keychain-item-classes.md](references/keychain-item-classes.md) | | Accessibility classes or `SecAccessControl` | [keychain-access-control.md](references/keychain-access-control.md) | | Face ID, Touch ID, or biometric-gated secrets | [biometric-authentication.md](references/biometric-authentication.md) | | Secure Enclave keys | [secure-enclave.md](references/secure-enclave.md) | | Hashing, HMAC, AES-GCM, ChaChaPoly, HKDF, PBKDF2 | [cryptokit-symmetric.md](references/cryptokit-symmetric.md) | | Signing, ECDH, HPKE, ML-KEM, ML-DSA | [cryptokit-public-key.md](references/cryptokit-public-key.md) | | OAuth tokens, API keys, logout, refresh rotation | [credential-storage-patterns.md](references/credential-storage-patterns.md) | | App/extension keychain sharing | [keychain-sharing.md](references/keychain-sharing.md) | | Certificate trust, SPKI pinning, mTLS | [certificate-trust.md](references/certificate-trust.md) | | UserDefaults/plist/NSCoding migration | [migration-legacy-stores.md](references/migration-legacy-stores.md) | | Unit, integration, simulator, device, or CI tests | [testing-security-code.md](references/testing-security-code.md) | | OWASP MASVS/MASTG or enterprise audit mapping | [compliance-owasp-mapping.md](references/compliance-owasp-mapping.md) | | Full security review | [common-anti-patterns.md](references/common-anti-patterns.md), then each touched domain reference |

Security Invariants

Use directive language only for these security invariants and the matching anti-patterns in [common-anti-patterns.md](references/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.

• Ke