ios-security

name	ios-security
description	Definitive iOS/Swift security skill for client-side Apple-platform apps (iOS 16–26, Swift 6). Covers Keychain Services (SecItem), biometric auth (LAContext, Face ID, Secure Enclave), CryptoKit (AES-GCM, post-quantum), token storage, Sign in with Apple + passkeys + OAuth, certificate pinning, App Transport Security, privacy manifests + ATT, jailbreak/anti-tamper + App Attest, and OWASP MASVS/MASTG audits with App Store rejection checks. Use whenever the user asks "is this secure?", "audit my app", "how do I store a token/password/key", "add Face ID login", "implement certificate pinning", or writes code touching secrets, keys, biometrics, encryption, Keychain, or ATS.
license	MIT

iOS Security

Philosophy — correctness over opinion. This skill provides Apple-documented, verified patterns, not architecture mandates. Every code pattern is grounded in Apple's Keychain Services / Platform Security Guide, DTS engineer posts (Quinn "The Eskimo!"), WWDC sessions, and OWASP MASVS v2.1.0 / MASTG v2 — never from memory alone. Baseline deployment target iOS 16+; modern recommendations target iOS 17+; forward-looking guidance covers iOS 26 (post-quantum CryptoKit, X25519MLKEM768 TLS).

Scope: client-side Apple-platform security — Keychain, biometrics, CryptoKit, Secure Enclave, credential/token lifecycle, Sign in with Apple / passkeys / OAuth, certificate trust & pinning, App Transport Security, privacy manifests & ATT, app hardening / anti-tamper, and static security auditing (OWASP MASVS, App Store rejection gate).

Out of scope: server-side auth architecture (JWT issuance, OAuth provider config → OWASP ASVS), CloudKit's server-managed key hierarchy, code signing / provisioning (build-time), and cross-platform crypto libraries (OpenSSL, LibSodium). Flag these as out of scope and redirect.

---

What is the task? (route here first)

Identify intent, then jump to the matching mode (table below). If ambiguous, ask one clarifying question. IMPLEMENT = build a feature from scratch (pick the domain, load 1–2 refs, follow ✅ patterns, satisfy the 13 Core Rules). REVIEW = is THIS snippet secure (run the Anti-Pattern Quick Scan, cite ✅ fix + severity). AUDIT = full MASVS scan of a repo (run the Audit Workflow, produce the report + coverage matrix). FIX = "how do I fix X" (identify the pattern, give the ✅ secure replacement + MASVS rationale + migration if needed).

Mode	Trigger	Go to
IMPLEMENT	"store a token", "add Face ID", "encrypt this", "implement pinning", "Sign in with Apple"	§ IMPLEMENT mode → Domain Guide
REVIEW	"is this secure?", "review my keychain/crypto code", paste of a snippet	§ REVIEW mode → Anti-Pattern Quick Scan
AUDIT	"security audit", "OWASP/MASVS scan", "find vulnerabilities", "is this ready for release"	§ AUDIT mode → references/audit-workflow.md
FIX	"how do I fix this", "secure alternative for X"	Identify the anti-pattern below → give ✅ replacement

---

The 13 Core Rules (non-negotiable invariants)

These are security invariants, not style preferences — use directive tone ("always"/"never") only for these and the 13 anti-patterns. Everything else is advisory.

1. Secrets live in Keychain — never UserDefaults, @AppStorage, Info.plist, .xcconfig, or NSCoding. Those produce plaintext artifacts readable from unencrypted backups and jailbroken devices. → references/keychain.md, references/anti-patterns.md #1
2. Never ignore OSStatus. Every SecItem* call returns one. Use an exhaustive switch covering at minimum errSecSuccess, errSecDuplicateItem (-25299), errSecItemNotFound (-25300), errSecInteractionNotAllowed (-25308). → references/keychain.md
3. Always use add-or-update. SecItemAdd, then SecItemUpdate on errSecDuplicateItem. Never delete-then-add (race window + destroys persistent references). → references/keychain.md
4. Always set kSecAttrAccessible explicitly (or kSecAttrAccessControl — never both, they conflict → errSecParam). The implicit default (WhenUnlocked) breaks background ops and hides policy from review. → references/keychain.md
5. Never call SecItem* on @MainActor/main thread. Each call is an IPC round-trip to securityd. Use a dedicated actor (iOS 17+) or serial DispatchQueue. → references/keychain.md
6. Biometrics must be keychain-bound — never LAContext.evaluatePolicy() as a standalone gate. That returns a Bool in hookable user-space memory; Frida/objection forces it true in one command. Store the secret behind SecAccessControl with .biometryCurrentSet; let the Secure Enclave gate SecItemCopyMatching. → references/biometrics.md, references/anti-patterns.md #3
7. Use the correct kSecClass. Web credentials → kSecClassInternetPassword (for AutoFill); crypto keys → kSecClassKey; app secrets → kSecClassGenericPassword with kSecAttrService + kSecAttrAccount. → references/keychain.md
8. Never reuse a nonce with the same AES-GCM key. A single reuse leaks C1 ⊕ C2 = P1 ⊕ P2 and the auth key (forbidden attack). Omit the nonce: parameter — CryptoKit generates a random one. → references/cryptokit.md, references/anti-patterns.md #6
9. Never use a raw ECDH shared secret as a symmetric key — always derive via sharedSecret.hkdfDerivedSymmetricKey(...). (CryptoKit's SharedSecret has no withUnsafeBytes on purpose.) → references/cryptokit.md
10. Never use Insecure.MD5/Insecure.SHA1/CC_MD5/CC_SHA1 for security. Both broken (2005/2017, CISA Jan 2025). Use SHA256+; passwords use a KDF (Argon2id/bcrypt server-side; PBKDF2 ≥600,000 iters on-device). → references/cryptokit.md
11. Use only cryptographic RNG for tokens/nonces/salts/keys — SecRandomCopyBytes or CryptoKit. Never arc4random*, rand(), drand48, or GameplayKit RNG. → references/anti-patterns.md #10
12. Keep ATS on. Never NSAllowsArbitraryLoads = true. For dev use NSAllowsLocalNetworking; for legacy production endpoints use a justified per-domain NSExceptionDomains entry. (Global ATS-off also triggers App Store review.) → references/network.md
13. macOS targets the data protection keychain — set kSecUseDataProtectionKeychain: true on every SecItem* call (Mac Catalyst / iOS-on-Mac do it automatically). Without it, queries silently route to the legacy file-based keychain. → references/keychain.md

---

The 13 Anti-Patterns — Quick Scan (REVIEW/AUDIT backbone)

When reviewing code, search for these. Any match is a finding. ❌ = insecure signature to detect; ✅ = corrective pattern (full ❌/✅ code pairs, MASTG test IDs, and detection heuristics in references/anti-patterns.md).

#	Search for	Anti-Pattern	Severity	OWASP 2024	MASTG
1	UserDefaults/@AppStorage + token/key/secret/password	Plaintext credential storage	🔴 CRITICAL	M9	MASTG-TEST-0302
2	High-entropy string literal (≥20 chars), sk_live_/pk_live_/AIza/AKIA	Hardcoded API key/secret	🔴 CRITICAL	M1	MASTG-TEST-0213
3	evaluatePolicy without nearby SecItemCopyMatching + SecAccessControl	LAContext-only biometric gate	🔴 CRITICAL	M3	MASTG-TEST-0266
4	SecItemAdd( with discarded return / no errSecDuplicateItem	Ignored OSStatus	🟡 HIGH	M8	MASTG-TEST-0300
5	SecItemAdd with no kSecAttrAccessible; kSecAttrAccessibleAlways	Wrong/missing data protection class	🟡 HIGH	M9	MASTG-TEST-0299
6	AES.GCM.Nonce(data:, .seal(... nonce:, Data(repeating: 0, count: 12)	Nonce reuse / hardcoded IV	🔴 CRITICAL	M10	MASTG-TEST-0317
7	sharedSecret.withUnsafeBytes without HKDF	Raw ECDH secret as key	🟡 HIGH	M10	MASTG-TEST-0318
8	print(/NSLog(/os_log(... %{public} + token/password/secret	Logging sensitive data	🟡 HIGH	M9	MASTG-TEST-0297
9	Insecure.MD5/Insecure.SHA1/CC_MD5/CC_SHA1	Broken hash for security	🟡 HIGH	M10	MASTG-TEST-0211
10	arc4random/rand()/drand48/GameplayKit RNG in security context	Non-crypto RNG	🟡 HIGH	M10	MASTG-TEST-0311
11	NSAllowsArbitraryLoads</key><true/> in Info.plist	Globally disabled ATS	🔴 CRITICAL	M5	MASTG-TEST-0233
12	NSKeyedUnarchiver.unarchiveObject(; SecTrustEvaluate( (sync, deprecated)	Insecure deserialization / legacy trust eval	🟡 HIGH	M4 / M5	MASTG-TEST-0305
13	Missing first-launch SecItemDelete across all kSecClass	Stale keychain after reinstall	🟢 MEDIUM	M9	MASTG-TEST-0301

Severity model: 🔴 CRITICAL = directly exploitable (exposes secrets/PII). 🟡 HIGH = silent data loss, wrong security boundary, or context-dependent exploit. 🟢 MEDIUM = defense-in-depth gap. 🔵 LOW = best-practice nit.

---

IMPLEMENT mode

1. Pick the domain(s) from the Domain Guide below. Load the 1–2 named reference file(s).
2. Follow the ✅ patterns verbatim for the core security logic — do not improvise crypto/keychain.
3. Satisfy every applicable Core Rule.
4. Run the reference file's Summary Checklist before declaring done.
5. Add tests per references/testing.md (protocol mocks for unit; real keychain on device).

Domain Guide

If the task involves…	Load
Storing/reading a password, token, API key	references/keychain.md
Choosing kSecClass / accessibility constant	references/keychain.md
Face ID / Touch ID / biometric gating	references/biometrics.md
Hardware-backed keys (Secure Enclave)	references/cryptokit.md (Secure Enclave §)
Encrypt / hash / HMAC / KDF	references/cryptokit.md
Sign / key-agreement / HPKE / post-quantum	references/cryptokit.md
Sign in with Apple / passkeys / OAuth / AutoFill	references/authentication.md
OAuth token lifecycle / refresh / logout cleanup	references/keychain.md (credential lifecycle §)
TLS certificate pinning / mTLS	references/network.md
App Transport Security configuration	references/network.md
Privacy manifest / ATT / permissions	references/privacy.md
Jailbreak / anti-tamper / App Attest / DeviceCheck / obfuscation / binary-hardening build settings	references/resilience.md
"Is API X private?" / entitlement gating / which framework exports a symbol (ipsw)	references/private-api-research.md
Writing tests for security code	references/testing.md
OWASP / MASVS compliance mapping	references/audit-workflow.md

---

REVIEW mode

1. Run the Anti-Pattern Quick Scan (table above) against the code. Load references/anti-patterns.md for the ❌/✅ detail of any match.
2. Add the domain-specific reference file(s) for whatever the code does (Domain Guide).
3. For each finding state: what's wrong → which reference covers it → the ✅ pattern → severity → MASVS/MASTG ID.
4. Always show both ❌ and ✅ code (exception: pure informational queries).
5. Cite the iOS version requirement inline for every API ("HPKE is iOS 17+").

---

AUDIT mode

A full repo audit. Read references/audit-workflow.md for the complete process, report template, model-tiering, and the MASVS coverage matrix. Summary:

Phase 0 — Scope gate (MANDATORY, do not skip). Discover targets (.xcodeproj/.xcworkspace), dependencies (Podfile/Package.swift/Cartfile), languages (Swift / ObjC / mixed), file counts. Present the scope menu (target scope A–D × MASVS depth 1–4 × profile L1/L2/R) and wait for the user to choose before scanning.

Phase 1 — Audit (after scope confirmed). In order:

1. Run scripts/quick-scan.sh (zero-token whole-repo grep) and your own search tools in parallel — neither alone is sufficient (script catches literals at any depth; agent search catches multi-file/data-flow patterns).
2. CRITICAL patterns → references/anti-patterns.md.
3. Info.plist + entitlements → references/privacy.md (plist audit §).
4. Storage → Keychain accessibility, file protection, leakage.
5. Crypto → deprecated algorithms, weak RNG, hardcoded keys/IVs.
6. Network → ATS, pinning → references/network.md.
7. If ObjC present → references/resilience.md (ObjC surface §): swizzling, KVC, format strings, NSPredicate injection, NSSecureCoding trap, associated-objects, category collisions.
8. If depth ≥ 3 and L2/R → resilience: jailbreak/debugger/Frida detection → references/resilience.md.
9. If depth = 4 → compliance gaps (HIPAA/PCI/GDPR/SOC2) → references/audit-workflow.md.
10. App Store rejection gate (AS1–AS9) → references/appstore-gate.md.
11. If a release .ipa is available → binary self-audit (scripts/binary-scan.sh: secret scan + cryptid + __RESTRICT) → references/audit-workflow.md. Off-Mac/CI: tier findings (verified vs heuristic) and always emit a "🍎 requires macOS" list.

Phase 2 — Report. Use the template in references/audit-workflow.md. Every finding has file:line, MASVS control, MASWE where applicable, risk, and a compiling ✅ fix. Always end with the MASVS Coverage Matrix (all 8 categories, real counts, status icons) — this is mandatory even if the user didn't ask for it.

Audit critical rules (apply during any audit)

• L1 vs L2: never flag an L2-only control (mandatory pinning, jailbreak detection) as a failure for a general-purpose L1 app — downgrade to informational.
• Every CRITICAL finding is double-checked for false positives before it ships in the report.
• No duplicate findings for the same root cause.
• Note static-analysis limits: you cannot observe runtime; mark conditional findings ("only exploitable if this flag is set in production").
• Give credit: list the security controls that ARE in place (secure storage, pinning, obfuscation).

---

Quick reference — accessibility constants

Constant	Decryptable when	In backup	Migrates device	Background-safe	Use for
WhenPasscodeSetThisDeviceOnly	Unlocked + passcode set	❌	❌	❌	Highest-value secrets (deleted if passcode removed)
WhenUnlockedThisDeviceOnly	Unlocked	❌	❌	❌	Foreground-only device-bound secrets
WhenUnlocked (system default)	Unlocked	✅	✅	❌	Syncable secrets — avoid implicit use
AfterFirstUnlockThisDeviceOnly	After 1st unlock → restart	❌	❌	✅	Background tasks / push handlers, device-bound
AfterFirstUnlock	After 1st unlock → restart	✅	✅	✅	Background tasks that must survive restore

Deprecated — never use: kSecAttrAccessibleAlways, kSecAttrAccessibleAlwaysThisDeviceOnly (iOS 12). Rule of thumb: background access → start AfterFirstUnlockThisDeviceOnly; foreground-only → WhenUnlockedThisDeviceOnly; high-value → WhenPasscodeSetThisDeviceOnly. Use non-ThisDeviceOnly only when iCloud sync or backup migration is genuinely required.

Quick reference — CryptoKit algorithm selection

Need	Algorithm	Min iOS	Notes
Hash	SHA256/SHA384/SHA512	13	SHA3_256/512 are iOS 18+ (not 26)
MAC	HMAC<SHA256>	13	constant-time verify built in
Encrypt (authenticated)	AES.GCM	13	256-bit key, omit nonce (auto-random)
Encrypt (no AES-NI hw)	ChaChaPoly	13	better on older Apple Watch
Sign	P256.Signing / Curve25519.Signing	13	P256 for interop, Curve25519 for speed
Key agreement	P256/Curve25519.KeyAgreement	13	always hkdfDerivedSymmetricKey
Hybrid PKE	HPKE	17	replaces manual ECDH+HKDF+AES-GCM
Hardware signing	SecureEnclave.P256.Signing	13	P256 only; key never leaves hardware
Post-quantum KEM	MLKEM768/MLKEM1024	26	FIPS 203
Post-quantum sign	MLDSA65/MLDSA87	26	FIPS 204
Password → key	PBKDF2 (CommonCrypto)	13	≥600,000 iters SHA-256 (OWASP 2024)
Key → key	HKDF<SHA256>	13	always pass info for domain separation

---

References

File	Read when
references/anti-patterns.md	Every REVIEW/AUDIT — the 13 anti-patterns with full ❌/✅ pairs, MASTG IDs, grep heuristics, CI/CD detection
references/keychain.md	SecItem CRUD, OSStatus, kSecClass selection, accessibility, actor wrappers, credential/OAuth lifecycle, macOS data-protection keychain, first-launch cleanup
references/biometrics.md	Keychain-bound biometrics, the boolean-gate bypass, flag selection, enrollment-change detection, graceful degradation, actor isolation
references/cryptokit.md	SHA-2/3, HMAC, AES-GCM/ChaChaPoly, ECDSA/ECDH, HPKE, Secure Enclave, ML-KEM/ML-DSA, HKDF/PBKDF2, key lifecycle
references/authentication.md	Sign in with Apple, passkeys/WebAuthn, ASWebAuthenticationSession OAuth, Password AutoFill, credential-state checks, nonce/token validation
references/network.md	ATS configuration, the 4 pinning strategies, SPKI hashing (with ASN.1 header), NSPinnedDomains, mTLS, backup pins/rotation
references/privacy.md	Privacy manifest (PrivacyInfo.xcprivacy), required-reason APIs, ATT, usage-description keys, permission UX, data minimization
references/resilience.md	Jailbreak/debugger/Frida/injection detection, integrity checks, App Attest + DeviceCheck server attestation, ObjC runtime attack surface
references/testing.md	Protocol-based mocking, simulator vs device gotchas, CI/CD keychain, Frida bypass verification
references/audit-workflow.md	Full audit process, scope menu, report template, MASVS coverage matrix, MASVS↔pattern mapping, model tiering, binary self-audit (own IPA), off-Mac/CI determinism tiers
references/appstore-gate.md	App Store rejection checks AS1–AS9 (UIWebView, private-API + false positives, per-app SPM symbol isolation, privacy manifest, usage-key→symbol map, ATT, ATS, export compliance)
references/private-api-research.md	"Is API X private?" / "what entitlement gates Y?" / "which framework exports Z?" via the ipsw toolkit (dyld shared cache, class-dump, entitlement DB, Mach-O) — research only

Authoritative sources

Apple Keychain Services docs · Apple Platform Security Guide · TN3137 (macOS keychain) · Quinn "The Eskimo!" DTS posts ("SecItem: Fundamentals" / "Pitfalls and Best Practices") · WWDC 2014-711 (Touch ID + Keychain) · WWDC 2019-709 (CryptoKit) · WWDC 2025-314 (post-quantum crypto) · OWASP Mobile Top 10 (2024) + MASVS v2.1.0 + MASTG v2 · CISA/FBI Product Security Bad Practices v2.0 (Jan 2025, hardcoded credentials = CWE-798). Never fabricate WWDC session numbers or citations — if not in a reference file, say it's unverified.