ios-security
How to Install
Claude Code:
git clone --depth 1 https://github.com/joecrotchett/spec-driven-claude.git && cp spec-driven-claude/.claude/skills/ios-security ~/.claude/skills/ios-security -r---
name: ios-security
description: "Secure iOS apps with Keychain Services, CryptoKit encryption, biometric authentication (Face ID, Touch ID), Secure Enclave key storage, LAContext, App Transport Security (ATS), certificate pinning, data protection classes, and secure coding patterns. Use when implementing app security features, auditing privacy manifests, configuring App Transport Security, securing keychain access, adding biometric authentication, or encrypting sensitive data with CryptoKit."
---
# iOS Security
Guidance for handling sensitive data, authenticating users, encrypting
correctly, and following Apple's security best practices on iOS.
## Contents
- [Keychain Services](#keychain-services)
- [Data Protection](#data-protection)
- [CryptoKit](#cryptokit)
- [Secure Enclave](#secure-enclave)
- [Biometric Authentication](#biometric-authentication)
- [App Transport Security (ATS)](#app-transport-security-ats)
- [Certificate Pinning](#certificate-pinning)
- [Secure Coding Patterns](#secure-coding-patterns)
- [Privacy Manifests](#privacy-manifests)
- [Common Mistakes](#common-mistakes)
- [Review Checklist](#review-checklist)
- [References](#references)
## Keychain Services
The Keychain is the ONLY correct place to store sensitive data. Never store
passwords, tokens, API keys, or secrets in UserDefaults, files, or Core Data.
### Storing Credentials
```swift
func saveToKeychain(account: String, data: Data, service: String) throws {
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrAccount as String: account,
kSecAttrService as String: service,
kSecValueData as String: data,
kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
]
let status = SecItemAdd(query as CFDictionary, nil)
if status == errSecDuplicateItem {
let updateQuery: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrAccount as String: account,
kSecAttrService as String: service
]
let updates: [String: Any] = [kSecValueData as String: data]
let updateStatus = SecItemUpdate(updateQuery as CFDictionary, updates as CFDictionary)
guard updateStatus == errSecSuccess else {
throw KeychainError.updateFailed(updateStatus)
}
} else if status != errSecSuccess {
throw KeychainError.saveFailed(status)
}
}
```
### Reading Credentials
```swift
func readFromKeychain(account: String, service: String) throws -> Data {
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrAccount as String: account,
kSecAttrService as String: service,
kSecReturnData as String: true,
kSecMatchLimit as String: kSecMatchLimitOne
]
var result: AnyObject?
let status = SecItemCopyMatching(query as CFDictionary, &result)
guard status == errSecSuccess, let data = result as? Data else {
throw KeychainError.readFailed(status)
}
return data
}
```
### Deleting Credentials
```swift
func deleteFromKeychain(account: String, service: String) throws {
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrAccount as String: account,
kSecAttrService as String: service
]
let status = SecItemDelete(query as CFDictionary)
guard status == errSecSuccess || status == errSecItemNotFound else {
throw KeychainError.deleteFailed(status)
}
}
```
### kSecAttrAccessible Values
| Value | When Available | Device-Only | Use For |
|---|---|---|---|
| `kSecAttrAccessibleWhenUnlocked` | Device unlocked | No | General credentials |
| `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` | Device unlocked | Yes | Sensitive credentials |
| `kSecAttrAccessibleAfterFirstUnlock` | After first unlock | No | Background-accessible tokens |
| `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` | After first unlock | Yes | Background tokens, no backup |
| `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly` | Passcode set + unlocked | Yes | Highest security |
Rules:
- Use `ThisDeviceOnly` variants for sensitive data. Prevents backup/restore to other devices.
- Use `AfterFirstUnlock` for tokens needed by background operations.
- Use `WhenPasscodeSetThisDeviceOnly` for most sensitive data. Item is deleted if passcode is removed.
- NEVER use `kSecAttrAccessibleAlways` (deprecated and insecure).
### Keychain Access Groups
Share keychain items across apps from the same team:
```swift
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrAccount as String: "shared-token",
kSecAttrAccessGroup as String: "TEAMID.com.company.shared"
]
```
### @AppStorage vs Keychain
| Storage | Use For | Security |
|---------|---------|----------|
| `@AppStorage` / `UserDefaults` | Non-sensitive preferences (theme, onboarding state, feature flags) | Not encrypted at rest |
| Keychain | Passwords, tokens, API keys, secrets | Hardware-encrypted, access-controlled |
**Rule:** If the data would be embarrassing or dangerous if exposed, it goes in Keychain. Everything else can use `@AppStorage`.
```swift
// Non-sensitive preference -- @AppStorage is fine
@AppStorage("hasCompletedOnboarding") private var hasOnboarded = false
// Sensitive credential -- MUST use Keychain
// WRONG: @AppStorage("authToken") private var token = ""
// CORRECT: Use saveToKeychain(account:data:service:)
```
## Data Protection
iOS encrypts files based on their protection class:
| Class | When Available | Use For |
|---|---|---|
| `.complete` | Only when unlocked | Sensitive user data |
| `.completeUnlessOpen` | Open handles survive lock | Active downloads, recordings |
| `.completeUntilFirstUserAuthentication` | After first unlock (default) | Most app data |
| `.none` | Always | Non-sensitive, system-needed data |
```swift
// Set file protection
try data.write(to: url, options: .completeFileProtection)
// Check protection level
let attributes = try FileManager.default.attributesOfItem(atPath: path)
let protection = attributes[.protectionKey] as? FileProtectionType
```
Use `.complete` for any file containing user-sensitive data. The default
`.completeUntilFirstUserAuthentication` is acceptable for general app data.
## CryptoKit
Use CryptoKit for all cryptographic operations. Do not use CommonCrypto or the
raw Security framework for new code.
### Symmetric Encryption (AES-GCM)
```swift
import CryptoKit
let key = SymmetricKey(size: .bits256)
func encrypt(_ data: Data, using key: SymmetricKey) throws -> Data {
let sealed = try AES.GCM.seal(data, using: key)
guard let combined = sealed.combined else {
throw CryptoError.sealFailed
}
return combined
}
func decrypt(_ data: Data, using key: SymmetricKey) throws -> Data {
let box = try AES.GCM.SealedBox(combined: data)
return try AES.GCM.open(box, using: key)
}
```
### Hashing
```swift
let hash = SHA256.hash(data: data)
let hashString = hash.compactMap { String(format: "%02x", $0) }.joined()
// Also available: SHA384, SHA512
```
### HMAC (Message Authentication)
```swift
let key = SymmetricKey(size: .bits256)
// Sign
let signature = HMAC.authenticationCode(for: data, using: key)
// Verify
let isValid = HMAC.isValidAuthenticationCode(signature, authenticating: data, using: key)
```
For digital signatures (P256/ECDSA), key agreement (Curve25519), ChaChaPoly,
and HKDF key derivation, see `references/cryptokit-advanced.md`.
## Secure Enclave
For the highest security, store keys in the Secure Enclave. Keys never leave
the hardware. Only P256 is supported.
```swift
guard SecureEnclave.isAvailable else { return }
let accessControl = SecAccessControlCreateWithFlags(
nil, kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
[.privateKeyUsage, .biometryCurrentSet], nil
)!
let privateKey = try SecureEnclave.P256.Signing.PrivateKey(accessControl: accessControl)
let signature = try privateKey.signature(for: data) // May trigger biometric prompt
let isValid = privateKey.publicKey.isValidSignature(signature, for: data)
// Persist: store dataRepresentation in Keychain, restore with:
let restored = try SecureEnclave.P256.Signing.PrivateKey(
dataRepresentation: privateKey.dataRepresentation
)
```
## Biometric Authentication
This section covers biometric protection for Keychain items and data
access. For user-facing biometric sign-in flows (`LAContext.evaluatePolicy`
as a login mechanism), see the `authentication` skill.
### LocalAuthentication (Face ID / Touch ID)
```swift
import LocalAuthentication
func authenticateWithBiometrics() async throws -> Bool {
let context = LAContext()
var error: NSError?
guard context.canEvaluatePolicy(
.deviceOwnerAuthenticationWithBiometrics, error: &error
) else {
// Biometrics not available -- fall back to passcode
if context.canEvaluatePolicy(.deviceOwnerAuthentication, error: &error) {
return try await context.evaluatePolicy(
.deviceOwnerAuthentication,
localizedReason: "Authenticate to access your account"
)
}
throw AuthError.biometricsUnavailable
}
return try await context.evaluatePolicy(
.deviceOwnerAuthenticationWithBiometrics,
localizedReason: "Authenticate to access your account"
)
}
```
### Info.plist Requirement
You MUST include `NSFaceIDUsageDescription` in Info.plist:
```xml
NSFaceIDUsageDescription
Authenticate to access your secure data
```
Missing this key causes a crash on Face ID devices.
### LAContext Configuration
```swift
let context = LAContext()
context.localizedFallbackTitle = "Use Passcode"
context.touchIDAuthenticationAllowableReuseDuration = 30
let currentState = context.evaluatedPolicyDomainState // Compare to detect enrollment changes
```
### Biometric + Keychain
Protect keychain items with biometric access:
```swift
let access = SecAccessControlCreateWithFlags(
nil,
kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
.biometryCurrentSet,
nil
)!
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrAccount as String: "auth-token",
kSecValueData as String: tokenData,
kSecAttrAccessControl as String: access,
kSecUseAuthenticationContext as String: LAContext()
]
```
SecAccessControl flags:
- `.biometryCurrentSet` -- Requires biometry, invalidated if enrollment changes. Most secure.
- `.biometryAny` -- Requires biometry, survives enrollment changes.
- `.userPresence` -- Biometry or passcode. Most flexible.
## App Transport Security (ATS)
ATS enforces HTTPS by default. Do NOT disable it.
### What ATS Requires
- TLS 1.2 or later
- Forward secrecy cipher suites
- SHA-256 or better certificates
- 2048-bit or greater RSA keys (or 256-bit ECC)
### Exception Domains (Last Resort)
```xml
NSAppTransportSecurity
NSExceptionDomains
legacy-api.example.com
NSExceptionAllowsInsecureHTTPLoads
NSExceptionMinimumTLSVersion
TLSv1.2
```
Rules:
- NEVER set `NSAllowsArbitraryLoads` to true. Apple will reject the app.
- Exception domains require justification in App Review notes.
- Use exception domains only for third-party servers you cannot control.
## Certificate Pinning
Pin certificates for sensitive API connections to prevent MITM attacks.
### URLSession Delegate Pinning
```swift
import CryptoKit
class PinnedSessionDelegate: NSObject, URLSessionDelegate {
// SHA-256 hash of the certificate's Subject Public Key Info
private let pinnedHashes: Set = [
"base64EncodedSHA256HashOfSPKI=="
]
func urlSession(
_ session: URLSession,
didReceive challenge: URLAuthenticationChallenge
) async -> (URLSession.AuthChallengeDisposition, URLCredential?) {
guard let trust = challenge.protectionSpace.serverTrust,
let chain = SecTrustCopyCertificateChain(trust) as? [SecCertificate],
let certificate = chain.first else {
return (.cancelAuthenticationChallenge, nil)
}
guard let publicKey = SecCertificateCopyKey(certificate),
let publicKeyData = SecKeyCopyExternalRepresentation(
publicKey, nil
) as Data? else {
return (.cancelAuthenticationChallenge, nil)
}
let hash = SHA256.hash(data: publicKeyData)
let hashString = Data(hash).base64EncodedString()
if pinnedHashes.contains(hashString) {
return (.useCredential, URLCredential(trust: trust))
}
return (.cancelAuthenticationChallenge, nil)
}
}
```
Rules:
- Pin the public key hash, not the certificate. Certificates rotate; public keys are more stable.
- Always include at least one backup pin.
- Have a rotation plan. If all pinned keys expire, the app cannot connect.
- Consider a kill switch (remote config to disable pinning in emergency).
## Secure Coding Patterns
### Never Log Sensitive Data
```swift
// WRONG
logger.debug("User logged in with token: \(token)")
// CORRECT
logger.debug("User logged in successfully")
```
### Clear Sensitive Data From Memory
```swift
var sensitiveData = Data(/* ... */)
defer {
sensitiveData.resetBytes(in: 0..
Details
| Category | Security → vulnerability |
| Source | joecrotchett/spec-driven-claude |
| SKILL.md | View on GitHub → |
| Repo Stars | N/A |
| Est. per Skill | N/A (shared across 28 skills from this repo) |
| Difficulty | Advanced |
| Risk Level | Safe |
Related Skills
seo
SEO: Universal SEO Analysis Skill Comprehensive SEO analysis across all industries (SaaS, local serv
varlock
Varlock Security Skill Secure-by-default environment variable management for Claude Code sessions. R
solidity-security
Solidity Security Master smart contract security best practices, vulnerability prevention, and secur
007
007 — Licenca para Auditar Overview Security audit, hardening, threat modeling (STRIDE/PASTA), Red/B
Works Well With
Skills from the same repository — often designed to work together
gh-cli
--- name: gh-cli description: GitHub CLI (gh) comprehensive reference for repositories, issues, pull
ios-hig
--- name: ios-hig description: Use when designing iOS interfaces, implementing accessibility (VoiceO
swiftui-pro
--- name: swiftui-pro description: Comprehensively reviews SwiftUI code for best practices on modern