@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swift-security/references/cryptokit-symmetric.md

@@ -1,530 +1,429 @@
-# CryptoKit Symmetric Cryptography
+# CryptoKit: Hashing, MACs and Symmetric Encryption
 
-> **Scope:** SHA-2/SHA-3 hashing, HMAC authentication, AES-GCM and ChaChaPoly authenticated encryption, SymmetricKey management, nonce handling, key derivation (HKDF + PBKDF2), and CommonCrypto migration. iOS 13+ baseline; SHA-3 requires iOS 26+.
->
-> **Key APIs:** `SHA256`, `SHA384`, `SHA512`, `SHA3_256` (iOS 26+), `HMAC`, `AES.GCM.seal/open`, `ChaChaPoly.seal/open`, `SymmetricKey`, `AES.GCM.Nonce`, `HKDF`, `SealedBox`
->
-> **Cross-references:** [secure-enclave.md] for hardware-backed asymmetric keys · [cryptokit-public-key.md] for ECDSA/ECDH/HPKE · [credential-storage-patterns.md] for key storage in Keychain · [common-anti-patterns.md] for the top-5 AI mistakes including hardcoded keys and nonce reuse
+This file covers the symmetric half of CryptoKit: digests (SHA-2 and SHA-3), HMAC,
+the two AEAD ciphers (AES-GCM and ChaChaPoly), `SymmetricKey`, nonce handling, key
+derivation with HKDF and PBKDF2, and moving old CommonCrypto code over. The baseline
+is iOS 13; HKDF as a standalone type needs iOS 14; SHA-3 needs iOS 26.
 
----
+Types you will meet below: `SHA256`, `SHA384`, `SHA512`, `SHA3_256`, `HMAC`,
+`AES.GCM.seal` / `AES.GCM.open`, `ChaChaPoly.seal` / `ChaChaPoly.open`,
+`SymmetricKey`, `AES.GCM.Nonce`, `HKDF`, and the per-cipher `SealedBox`.
 
 ## Contents
 
-- [Hashing: SHA-2 and SHA-3](#hashing-sha-2-and-sha-3)
-  - [One-Shot Hashing](#one-shot-hashing)
-  - [Streaming Hash for Large Files](#streaming-hash-for-large-files)
-  - [SHA-3 with Availability Check](#sha-3-with-availability-check)
-  - [Insecure Hash Functions](#insecure-hash-functions)
-- [HMAC: Message Authentication with Symmetric Keys](#hmac-message-authentication-with-symmetric-keys)
-- [AES-GCM: Authenticated Encryption in One Operation](#aes-gcm-authenticated-encryption-in-one-operation)
-  - [Basic Encryption and Decryption](#basic-encryption-and-decryption)
-  - [Associated Data (AAD)](#associated-data-aad)
-  - [The Catastrophic Danger of Nonce Reuse](#the-catastrophic-danger-of-nonce-reuse)
-- [ChaChaPoly: Software-Friendly AEAD Alternative](#chachapoly-software-friendly-aead-alternative)
-  - [Performance: AES-GCM vs ChaChaPoly on Apple Hardware](#performance-aes-gcm-vs-chachapoly-on-apple-hardware)
-  - [Streaming Encryption Limitation](#streaming-encryption-limitation)
-- [SymmetricKey: Creation, Derivation, and Lifecycle](#symmetrickey-creation-derivation-and-lifecycle)
-  - [Random Key Generation](#random-key-generation)
-  - [Password-Based Key Derivation (PBKDF2 + HKDF)](#password-based-key-derivation-pbkdf2-hkdf)
-  - [HKDF for High-Entropy Key Derivation](#hkdf-for-high-entropy-key-derivation)
-  - [Key Storage and Hardcoding](#key-storage-and-hardcoding)
-- [Migrating from CommonCrypto to CryptoKit](#migrating-from-commoncrypto-to-cryptokit)
-  - [Hashing: CC_SHA256 → SHA256](#hashing-ccsha256-sha256)
-  - [Encryption: CCCrypt (AES-CBC) → AES.GCM](#encryption-cccrypt-aes-cbc-aesgcm)
-  - [HMAC: CCHmac → HMAC](#hmac-cchmac-hmac)
-  - [What to Keep in CommonCrypto](#what-to-keep-in-commoncrypto)
-- [AI Code Generator Mistakes](#ai-code-generator-mistakes)
-- [Quantum Considerations for Symmetric Cryptography](#quantum-considerations-for-symmetric-cryptography)
-- [OWASP Mapping](#owasp-mapping)
-- [Testing Guidance](#testing-guidance)
-- [WWDC and Reference Citations](#wwdc-and-reference-citations)
-- [Conclusion](#conclusion)
-- [Summary Checklist](#summary-checklist)
-
-## Hashing: SHA-2 and SHA-3
-
-CryptoKit's hash functions follow a unified `HashFunction` protocol. The SHA-2 family (`SHA256`, `SHA384`, `SHA512`) ships with iOS 13+. The SHA-3 family (`SHA3_256`, `SHA3_384`, `SHA3_512`) requires **iOS 26+ / macOS 26+** (added via apple/swift-crypto PR #397, tagged [WWDC25]).
-
-The swift-crypto open-source package provides SHA-3 under `import Crypto` for older deployment targets. The Apple CryptoKit framework (`import CryptoKit`) requires iOS 26+ for SHA-3. Do not confuse package availability with framework availability.
-
-All hash functions produce digest types that conform to `Sequence` (of `UInt8`), `ContiguousBytes`, `Hashable`, and `CustomStringConvertible`. Digest equality checks use **constant-time comparison** internally to prevent timing side-channels.
-
-### One-Shot Hashing
-
-**✅ Correct: SHA-256 hashing with hex output**
+- [Digests](#digests)
+- [HMAC](#hmac)
+- [AES-GCM](#aes-gcm)
+- [ChaChaPoly](#chachapoly)
+- [SymmetricKey](#symmetrickey)
+- [Moving off CommonCrypto](#moving-off-commoncrypto)
+- [Frequent mistakes](#frequent-mistakes)
+- [Post-quantum outlook](#post-quantum-outlook)
+- [OWASP mapping](#owasp-mapping)
+- [Tests worth writing](#tests-worth-writing)
+- [Sources](#sources)
+- [Checklist](#checklist)
 
-```swift
-import CryptoKit
+## Digests
 
-let data = "Hello, CryptoKit".data(using: .utf8)!
-let digest = SHA256.hash(data: data)
+Every hash type conforms to `HashFunction`.
 
-// Convert to hex string  -  Digest conforms to Sequence
-let hexString = digest.map { String(format: "%02x", $0) }.joined()
+| Family | Types | Availability |
+| --- | --- | --- |
+| SHA-2 | `SHA256`, `SHA384`, `SHA512` | iOS 13+, macOS 10.15+ |
+| SHA-3 | `SHA3_256`, `SHA3_384`, `SHA3_512` | iOS 26+, macOS 26+ (added alongside the WWDC25 release, mirrored in swift-crypto PR #397) |
 
-// Constant-time comparison
-let otherDigest = SHA256.hash(data: data)
-if digest == otherDigest {
-    print("Integrity verified")
-}
-```
+The open-source swift-crypto package (`import Crypto`) ships SHA-3 for older
+deployment targets, but that does not make it available in Apple's framework:
+`import CryptoKit` still requires the iOS 26 SDK and runtime. Check which module
+you import before assuming availability.
 
-Never rely on `.description` for hex output  -  Apple warns its format may change between OS versions.
+A digest value is a `Sequence` of `UInt8`, conforms to `ContiguousBytes`,
+`Hashable` and `CustomStringConvertible`, and its `==` compares in constant time.
 
-### Streaming Hash for Large Files
+```swift
+import CryptoKit
+import Foundation
 
-**✅ Correct: Incremental hashing to avoid loading entire file into memory**
+let manifest = Data("release-manifest-v4".utf8)
+let fingerprint = SHA256.hash(data: manifest)
+let hexFingerprint = fingerprint.map { String(format: "%02x", $0) }.joined()
 
-```swift
-var hasher = SHA256()
-let fileHandle = try FileHandle(forReadingFrom: fileURL)
-while autoreleasepool(invoking: {
-    let chunk = fileHandle.readData(ofLength: 1_048_576) // 1 MB chunks
-    guard !chunk.isEmpty else { return false }
-    hasher.update(data: chunk)
-    return true
-}) {}
-let digest = hasher.finalize()
+let expected = SHA256.hash(data: Data("release-manifest-v4".utf8))
+let matches = fingerprint == expected
 ```
 
-All hash functions support `init()` → `update(data:)` → `finalize()`. The `autoreleasepool` wrapper prevents memory accumulation during chunk reads.
-
-### SHA-3 with Availability Check
+Build hex strings yourself as above. Do not rely on `.description`; Apple states
+its format is not stable.
 
-**✅ Correct: SHA-3 with fallback (iOS 26+)**
+Large inputs should be streamed so the whole file never sits in memory. Read in
+chunks (1 MB works well) and wrap each read in `autoreleasepool` so the
+temporary `Data` buffers are released per iteration:
 
 ```swift
-func computeHash(data: Data) -> String {
-    if #available(iOS 26.0, macOS 26.0, *) {
-        let digest = SHA3_256.hash(data: data)
-        return digest.map { String(format: "%02x", $0) }.joined()
-    } else {
-        let digest = SHA256.hash(data: data)
-        return digest.map { String(format: "%02x", $0) }.joined()
+func digestOfFile(at url: URL) throws -> SHA256.Digest {
+    let handle = try FileHandle(forReadingFrom: url)
+    defer { try? handle.close() }
+    var hasher = SHA256()
+    var reachedEnd = false
+    while !reachedEnd {
+        try autoreleasepool {
+            let block = try handle.read(upToCount: 1_048_576) ?? Data()
+            if block.isEmpty {
+                reachedEnd = true
+            } else {
+                hasher.update(data: block)
+            }
+        }
     }
+    return hasher.finalize()
 }
 ```
 
-SHA-3 uses a completely different internal construction (Keccak sponge) from SHA-2 (Merkle-Damgård). The API surface is identical  -  only the type name changes. Adopt SHA-3 when compliance standards require it or for defense-in-depth against future SHA-2 structural weaknesses.
-
-### Insecure Hash Functions
-
-**❌ Wrong: Using MD5 or SHA-1 for any security purpose**
+SHA-3 uses the Keccak sponge construction rather than SHA-2's Merkle-Damgard
+chaining, but the Swift API is the same. Reach for it when a compliance profile
+names it or you want algorithm diversity. Gate it and fall back:
 
 ```swift
-// NEVER  -  MD5 collision resistance is ~2^18 operations (seconds on commodity hardware)
-let broken = Insecure.MD5.hash(data: data)
-
-// SHA-1 fell to chosen-prefix collisions in 2020 (~$45,000 GPU time)
-let alsoBroken = Insecure.SHA1.hash(data: data)
+func contentTag(for payload: Data) -> Data {
+    if #available(iOS 26.0, macOS 26.0, *) {
+        return Data(SHA3_256.hash(data: payload))
+    }
+    return Data(SHA256.hash(data: payload))
+}
 ```
 
-CryptoKit deliberately places both in the `Insecure` namespace as an API-level warning. Use `SHA256` minimum for all security purposes  -  it is equally fast on modern hardware and provides actual collision resistance.
-
-**Algorithm selection quick reference:**
+Broken hashes live under `Insecure` on purpose. `Insecure.MD5` collisions take on
+the order of 2^18 operations (seconds on a laptop), and `Insecure.SHA1` fell to a
+practical chosen-prefix collision in 2020 costing roughly $45,000 of GPU time.
+Neither belongs anywhere security matters; SHA-256 is the floor.
 
-| Algorithm | Type            | Availability | Status     | Use When                                   |
-| --------- | --------------- | ------------ | ---------- | ------------------------------------------ |
-| SHA-256   | `SHA256`        | iOS 13+      | Strong     | Default for integrity, signing, HMAC       |
-| SHA-384   | `SHA384`        | iOS 13+      | Strong     | Certificate chains, higher security margin |
-| SHA-512   | `SHA512`        | iOS 13+      | Strong     | Large data, performance on 64-bit          |
-| SHA3-256  | `SHA3_256`      | iOS 26+      | Strong     | Compliance requiring SHA-3                 |
-| SHA3-384  | `SHA3_384`      | iOS 26+      | Strong     | Future-proofing                            |
-| SHA3-512  | `SHA3_512`      | iOS 26+      | Strong     | High-security contexts                     |
-| MD5       | `Insecure.MD5`  | iOS 13+      | **Broken** | Legacy non-security checksums only         |
-| SHA-1     | `Insecure.SHA1` | iOS 13+      | **Broken** | Legacy non-security checksums only         |
+| Algorithm | Pick it for |
+| --- | --- |
+| SHA-256 | Default: integrity checks, signatures, HMAC |
+| SHA-384 | Certificate chains, extra margin |
+| SHA-512 | Large data, faster on 64-bit cores |
+| SHA3-256 | Compliance requirements naming SHA-3 |
+| SHA3-384 | Longer-term margin |
+| SHA3-512 | Highest-assurance profiles |
+| MD5, SHA-1 | Broken. Only for legacy, non-security checksums |
 
----
+## HMAC
 
-## HMAC: Message Authentication with Symmetric Keys
-
-HMAC combines a hash function with a secret key to produce an authentication code. CryptoKit's `HMAC<H>` is generic over any `HashFunction`, provides constant-time verification, and supports both one-shot and streaming patterns.
-
-**✅ Correct: HMAC generation and verification**
+`HMAC<H>` is generic over any `HashFunction`, supports one-shot and incremental
+use, and verifies in constant time.
 
 ```swift
-import CryptoKit
-
-let key = SymmetricKey(size: .bits256)
-let message = "Transfer $500 to account 12345".data(using: .utf8)!
+let webhookKey = SymmetricKey(size: .bits256)
+let body = Data(#"{"event":"invoice.paid"}"#.utf8)
 
-// Generate authentication code
-let mac = HMAC<SHA256>.authenticationCode(for: message, using: key)
+let tag = HMAC<SHA256>.authenticationCode(for: body, using: webhookKey)
+let tagBytes = Data(tag)
 
-// Verify  -  constant-time comparison prevents timing attacks
-let isValid = HMAC<SHA256>.isValidAuthenticationCode(
-    mac, authenticating: message, using: key
+let authentic = HMAC<SHA256>.isValidAuthenticationCode(
+    tagBytes, authenticating: body, using: webhookKey
 )
-
-// Serialize MAC for transmission
-let macData = Data(mac)
 ```
 
-**Critical:** Always use `isValidAuthenticationCode(_:authenticating:using:)` for verification  -  never manually compare raw bytes with `==`. CryptoKit's method uses `safeCompare` internally, which runs in constant time regardless of how many bytes match, defeating timing side-channel attacks.
-
-The return type `HMAC<SHA256>.MAC` (alias for `HashedAuthenticationCode<SHA256>`) conforms to `ContiguousBytes`, `Sequence`, `Hashable`, and `CustomStringConvertible`.
-
-**Common HMAC use cases:** API request signing, webhook payload verification, data integrity in transit, token-based authentication schemes. HMAC proves authenticity and integrity  -  not confidentiality. For encryption, use AES-GCM or ChaChaPoly below.
-
----
+Verification must go through `isValidAuthenticationCode(_:authenticating:using:)`,
+which compares safely in constant time. Never compare MAC bytes with `==` on `Data`.
 
-## AES-GCM: Authenticated Encryption in One Operation
+`HMAC<SHA256>.MAC` is a typealias for `HashedAuthenticationCode<SHA256>`, which is
+`ContiguousBytes`, `Sequence`, `Hashable` and `CustomStringConvertible`.
 
-AES-GCM is CryptoKit's primary symmetric cipher, providing **Authenticated Encryption with Associated Data (AEAD)**  -  confidentiality, integrity, and authenticity in a single `seal()` call. This eliminates the historically dangerous pattern of combining AES-CBC + HMAC manually.
+Typical uses: signing API requests, verifying webhooks, integrity of data in transit,
+token schemes. HMAC proves who produced the data and that it was not changed; it
+does not hide the data.
 
-### Basic Encryption and Decryption
+## AES-GCM
 
-**✅ Correct: AES-GCM encryption with automatic nonce**
+AES-GCM is the cipher to use by default. It is an AEAD mode: one `seal()` call gives
+confidentiality, integrity and authenticity, replacing the old AES-CBC plus
+separate HMAC construction.
 
 ```swift
-import CryptoKit
-
-let key = SymmetricKey(size: .bits256)
-let plaintext = "Sensitive data".data(using: .utf8)!
+let vaultKey = SymmetricKey(size: .bits256)
+let note = Data("door code 4411".utf8)
 
-// Encrypt  -  CryptoKit auto-generates a random 12-byte nonce
-let sealedBox = try AES.GCM.seal(plaintext, using: key)
-
-// Serialize for storage/transmission: nonce(12) || ciphertext || tag(16)
-guard let combined = sealedBox.combined else {
-    fatalError("Combined representation unavailable (non-standard nonce size)")
-}
+let box = try AES.GCM.seal(note, using: vaultKey)
+guard let stored = box.combined else { throw CryptoKitError.incorrectParameterSize }
 
-// Deserialize and decrypt
-let restoredBox = try AES.GCM.SealedBox(combined: combined)
-let decrypted = try AES.GCM.open(restoredBox, using: key)
+let reopened = try AES.GCM.SealedBox(combined: stored)
+let recovered = try AES.GCM.open(reopened, using: vaultKey)
 ```
 
-The `SealedBox` contains three components: a **12-byte nonce**, the **ciphertext** (same length as plaintext), and a **16-byte authentication tag**. The `combined` property is `Data?` (optional) because non-standard nonce sizes prevent combined representation. For ChaChaPoly, `combined` is non-optional.
+`seal` picks a fresh random 12-byte nonce when you do not pass one. A sealed box
+holds three parts: the 12-byte nonce, ciphertext of the same length as the
+plaintext, and a 16-byte tag. `combined` lays them out as nonce, ciphertext, tag.
 
-### Associated Data (AAD)
+`AES.GCM.SealedBox.combined` is `Data?`: it is nil when the box was built with a
+non-standard nonce length. `ChaChaPoly.SealedBox.combined` is not optional.
 
-**✅ Correct: Binding ciphertext to context with associated data**
+### Additional authenticated data
 
-```swift
-let metadata = "user:42,action:payment".data(using: .utf8)!
-let sealedBox = try AES.GCM.seal(plaintext, using: key, authenticating: metadata)
+Pass context that must match on decryption but need not be secret:
 
-// Decryption requires the same AAD  -  tampered metadata causes authenticationFailure
-let decrypted = try AES.GCM.open(sealedBox, using: key, authenticating: metadata)
+```swift
+let context = Data("owner=81923|doc=receipt-77|v=2".utf8)
+let bound = try AES.GCM.seal(note, using: vaultKey, authenticating: context)
+let plain = try AES.GCM.open(bound, using: vaultKey, authenticating: context)
 ```
 
-Associated data is authenticated but **not encrypted**. Use it to bind ciphertext to context (user ID, timestamp, resource identifier) so encrypted data cannot be transplanted to a different context without detection.
+AAD is authenticated but not encrypted. Binding a user id, resource id, version or
+timestamp stops an attacker from moving a valid ciphertext into another record. A
+mismatch makes `open` throw `CryptoKitError.authenticationFailure`.
 
-### The Catastrophic Danger of Nonce Reuse
+### Nonce reuse
 
-**❌ CRITICAL: Never reuse a nonce with the same key**
+This is the classic mistake:
 
 ```swift
-// CATASTROPHIC  -  enables FULL key recovery
-let staticNonce = try AES.GCM.Nonce(data: Data(repeating: 0, count: 12))
-let box1 = try AES.GCM.seal(message1, using: key, nonce: staticNonce)
-let box2 = try AES.GCM.seal(message2, using: key, nonce: staticNonce)
-// With C1 and C2, attacker computes: C1 ⊕ C2 = P1 ⊕ P2
+// Broken: the same fixed nonce for every message
+let fixedNonce = try AES.GCM.Nonce(data: Data(count: 12))
+let first = try AES.GCM.seal(Data("alpha".utf8), using: vaultKey, nonce: fixedNonce)
+let second = try AES.GCM.seal(Data("bravo".utf8), using: vaultKey, nonce: fixedNonce)
 ```
 
-Nonce reuse in AES-GCM is not "bad practice"  -  it is a **total cryptographic break** known as the "Forbidden Attack" (Joux, 2006):
-
-1. **Plaintext recovery:** Identical nonce + key produces identical keystream. XORing two ciphertexts yields `P1 ⊕ P2`. If either plaintext is known or guessable, the other is immediately recovered.
-2. **Authentication forgery:** GCM's authentication uses GHASH, a polynomial over GF(2^128) with a secret hash key `H = AES_k(0^128)`. Two messages sharing a nonce yield a polynomial equation solvable via Cantor-Zassenhaus root-finding to recover H. Once H is known, the attacker can **forge valid authentication tags for arbitrary messages**.
-
-A USENIX WOOT'16 study found 184 HTTPS servers reusing AES-GCM nonces in production, including financial institutions.
+Two messages under one key and one nonce share a keystream, so XOR of the
+ciphertexts equals XOR of the plaintexts. Worse, the authentication subkey
+H = AES_k(0^128) can be recovered by root finding (Cantor-Zassenhaus), after which
+tags can be forged for any message. This is the "forbidden attack" described by
+Joux in 2006, and a 2016 USENIX WOOT study found 184 HTTPS servers, some at
+financial institutions, reusing GCM nonces in the wild.
 
-**The fix:** Omit the `nonce:` parameter entirely. CryptoKit generates cryptographically random 12-byte nonces automatically, giving collision probability below 2^-32 after 2^32 encryptions under the same key. Only supply explicit nonces when interoperating with external systems that dictate nonce values.
+The fix is to omit `nonce:`. With random 12-byte nonces the chance of any
+collision stays below 2^-32 after 2^32 messages under one key. Supply an explicit
+nonce only when an external protocol defines it, and then follow that protocol's
+counter rules exactly.
 
----
+## ChaChaPoly
 
-## ChaChaPoly: Software-Friendly AEAD Alternative
-
-ChaCha20-Poly1305 provides equivalent AEAD security with an identical API surface. It exists primarily for **software-only environments** where it delivers constant-time execution without hardware acceleration, eliminating cache-timing side channels that plague software AES implementations.
-
-**✅ Correct: ChaChaPoly encryption**
+ChaCha20-Poly1305 gives the same AEAD guarantees with the same API shape; switching
+is a type-name change.
 
 ```swift
-let key = SymmetricKey(size: .bits256)
-let sealedBox = try ChaChaPoly.seal(plaintext, using: key)
-
-// ChaChaPoly.SealedBox.combined is non-optional (unlike AES.GCM)
-let combined = sealedBox.combined
-
-// Decrypt
-let restoredBox = try ChaChaPoly.SealedBox(combined: combined)
-let decrypted = try ChaChaPoly.open(restoredBox, using: key)
+let sealed = try ChaChaPoly.seal(note, using: vaultKey)
+let wire = sealed.combined
+let parsed = try ChaChaPoly.SealedBox(combined: wire)
+let opened = try ChaChaPoly.open(parsed, using: vaultKey)
 ```
 
-The API mirrors AES-GCM exactly  -  same `seal`/`open` methods, same `SealedBox` structure. Switching between ciphers requires changing only the type name.
-
-### Performance: AES-GCM vs ChaChaPoly on Apple Hardware
-
-On all Apple Silicon (A-series since A7, all M-series), **AES-GCM is significantly faster** due to dedicated hardware AES instructions:
-
-| Metric              | AES-256-GCM                                                   | ChaChaPoly  | Source                  |
-| ------------------- | ------------------------------------------------------------- | ----------- | ----------------------- |
-| Throughput (M2 Pro) | ~3-4 GB/s                                                     | ~1.5-2 GB/s | OpenSSL benchmarks      |
-| Relative speed      | 134%-236% faster                                              | Baseline    | Ashvardanian (2025)     |
-| Apple internal use  | Keychain encryption, file Data Protection, Watch↔iPhone comms |  -            | Platform Security Guide |
-
-**Default to AES-GCM on Apple hardware.** Choose ChaChaPoly when: targeting platforms without hardware AES acceleration, requiring guaranteed constant-time behavior independent of hardware, or interoperating with ChaCha20-based protocols (WireGuard, some TLS configurations).
+Every Apple chip since A7, and every M-series chip, has AES instructions. Published
+2025 benchmarks on an M2 Pro (OpenSSL) put AES-256-GCM at roughly 3-4 GB/s and
+ChaChaPoly at roughly 1.5-2 GB/s, AES being 134% to 236% faster depending on size.
+Apple's own keychain, file Data Protection and Watch-to-iPhone links all use AES.
 
-### Streaming Encryption Limitation
+So: AES-GCM on Apple hardware. Choose ChaChaPoly when there is no hardware AES,
+when you need guaranteed constant-time software (no table lookups, no cache-timing
+side channel), or when a protocol such as WireGuard or a ChaCha20 TLS suite
+specifies it.
 
-Neither `seal()` nor `open()` supports streaming  -  both operate on the full message in memory. For large files, implement a **chunked AEAD scheme** with unique nonces per chunk and a monotonic chunk index in AAD to prevent reordering attacks. Alternatively, use Apple's file-level Data Protection (AES-XTS via the hardware crypto engine) for at-rest file encryption.
+Neither cipher streams. For large files, either split into chunks with a unique
+nonce per chunk and the chunk index (monotonic) in the AAD so chunks cannot be
+reordered or dropped silently, or lean on file Data Protection, which the hardware
+engine applies with AES-XTS.
 
----
+## SymmetricKey
 
-## SymmetricKey: Creation, Derivation, and Lifecycle
+`SymmetricKey` zeroes its memory when deallocated (WWDC 2019 session 709), exposes
+no `Data` property (only `withUnsafeBytes`), and validates its size.
 
-`SymmetricKey` is CryptoKit's opaque key container. It **zeroes memory on deallocation** (confirmed WWDC 2019-709 and Apple documentation), prevents accidental exposure (no `Data` property  -  only `withUnsafeBytes` access), and validates key sizes at construction.
+`SymmetricKey(size: .bits256)` is 32 random bytes; `.bits128` and `.bits192` also
+exist. Use 256 bits: Grover's algorithm halves effective strength, leaving AES-256
+at 128 bits but AES-128 at 64 bits, which is not enough.
 
-### Random Key Generation
-
-**✅ Correct: Cryptographically random key**
-
-```swift
-let key = SymmetricKey(size: .bits256) // 32 bytes, cryptographically random
-// Also available: .bits128, .bits192
-```
-
-For quantum resilience, prefer `.bits256`. Grover's algorithm halves effective symmetric key strength  -  AES-256 retains 128-bit security against quantum adversaries, while AES-128 drops to 64-bit (insufficient).
-
-### Password-Based Key Derivation (PBKDF2 + HKDF)
-
-**❌ Wrong: Raw password as key material**
+### Passwords are not keys
 
 ```swift
-// NEVER  -  passwords have ~20-40 bits of entropy, not 256
-let key = SymmetricKey(data: "MyPassword123".data(using: .utf8)!)
-// Trivially brute-forceable via dictionary attack  -  no computational cost barrier, no salt
+// Broken: a password is low-entropy, unsalted and free to guess
+let weak = SymmetricKey(data: Data("summer2026".utf8))
 ```
 
-CryptoKit ships HKDF but **not** PBKDF2. For password-based key derivation, use CommonCrypto's `CCKeyDerivationPBKDF` first, then optionally HKDF for subkey derivation:
-
-**✅ Correct: Password → key via PBKDF2 + HKDF**
+A human password carries around 20-40 bits of entropy, and this has no salt and no
+work factor. CryptoKit provides HKDF but not PBKDF2, so stretch the password with
+CommonCrypto first, then optionally split it with HKDF:
 
 ```swift
 import CommonCrypto
-import CryptoKit
-
-// Step 1: PBKDF2 stretches the low-entropy password
-let password = "MyPassword123"
-let salt = Data((0..<32).map { _ in UInt8.random(in: 0...255) })
-var derivedBytes = [UInt8](repeating: 0, count: 32)
-
-CCKeyDerivationPBKDF(
-    CCPBKDFAlgorithm(kCCPBKDF2),
-    password, password.utf8.count,
-    Array(salt), salt.count,
-    CCPseudoRandomAlgorithm(kCCPRFHmacAlgSHA256),
-    600_000,  // OWASP 2023 recommended minimum for HMAC-SHA256
-    &derivedBytes, derivedBytes.count
-)
 
-// Step 2: HKDF derives purpose-specific subkeys (domain separation)
-let masterKey = SymmetricKey(data: derivedBytes)
-let encryptionKey = HKDF<SHA256>.deriveKey(
-    inputKeyMaterial: masterKey,
-    info: Data("encryption".utf8),
-    outputByteCount: 32
-)
-let authKey = HKDF<SHA256>.deriveKey(
-    inputKeyMaterial: masterKey,
-    info: Data("authentication".utf8),
-    outputByteCount: 32
-)
-```
-
-> **Iteration count note:** The OWASP Password Storage Cheat Sheet recommends **600,000 iterations minimum** for PBKDF2-HMAC-SHA256. Use at least 600,000 for new implementations; only use lower counts when supporting legacy interoperability with documented justification.
-
-**Critical distinction:** HKDF is designed for already-high-entropy input (shared secrets, master keys). It does **not** add computational cost. Never use HKDF alone for passwords  -  always PBKDF2 first.
-
-### HKDF for High-Entropy Key Derivation
-
-**✅ Correct: Deriving subkeys from a high-entropy master key**
-
-```swift
-// When input is already high-entropy (e.g., ECDH shared secret)
-let inputKey = SymmetricKey(size: .bits256)
-let derivedKey = HKDF<SHA256>.deriveKey(
-    inputKeyMaterial: inputKey,
-    salt: Data("app-specific-salt".utf8),
-    info: Data("aes-encryption-key-v1".utf8),
-    outputByteCount: 32
-)
-```
-
-HKDF follows RFC 5869 and supports one-shot `deriveKey()` and two-phase `extract()` → `expand()`. Use distinct `info` strings for domain separation when deriving multiple subkeys from a single shared secret. Available since iOS 14+.
-
-> **API note:** `HKDF.deriveKey()` does not throw  -  no `try` required despite some code examples showing it.
-
-### Key Storage and Hardcoding
+func stretch(passphrase: String, salt: Data, rounds: UInt32 = 600_000) -> SymmetricKey? {
+    let secret = Array(passphrase.utf8)
+    var output = [UInt8](repeating: 0, count: 32)
+    let status = salt.withUnsafeBytes { saltBytes in
+        CCKeyDerivationPBKDF(
+            CCPBKDFAlgorithm(kCCPBKDF2),
+            secret.map { Int8(bitPattern: $0) }, secret.count,
+            saltBytes.bindMemory(to: UInt8.self).baseAddress, salt.count,
+            CCPseudoRandomAlgorithm(kCCPRFHmacAlgSHA256), rounds,
+            &output, output.count
+        )
+    }
+    guard status == kCCSuccess else { return nil }
+    return SymmetricKey(data: output)
+}
 
-**❌ Wrong: Hardcoding keys in source code**
+struct PasswordKeys {
+    let salt: Data
+    let encryption: SymmetricKey
+    let authentication: SymmetricKey
+}
 
-```swift
-// NEVER  -  extractable via `strings` command on the binary
-let key = SymmetricKey(data: Data(base64Encoded: "c2VjcmV0S2V5MTIzNDU2Nzg5MDEyMzQ1Ng==")!)
+func passwordKeys(for passphrase: String) -> PasswordKeys? {
+    var saltBytes = [UInt8](repeating: 0, count: 32)
+    guard SecRandomCopyBytes(kSecRandomDefault, saltBytes.count, &saltBytes) == errSecSuccess else { return nil }
+    let salt = Data(saltBytes)
+    guard let master = stretch(passphrase: passphrase, salt: salt) else { return nil }
+    return PasswordKeys(
+        salt: salt,
+        encryption: HKDF<SHA256>.deriveKey(
+            inputKeyMaterial: master, info: Data("encryption".utf8), outputByteCount: 32
+        ),
+        authentication: HKDF<SHA256>.deriveKey(
+            inputKeyMaterial: master, info: Data("authentication".utf8), outputByteCount: 32
+        )
+    )
+}
 ```
 
-A Zimperium 2025 study found 48% of mobile apps contain hardcoded secrets. iOS binaries can be decrypted and analyzed with tools like Hopper or IDA Pro. **Store keys in the Keychain** with `kSecAttrAccessibleWhenUnlockedThisDeviceOnly`, derive them at runtime from user credentials, or fetch from a secure server. See [credential-storage-patterns.md] for detailed patterns.
+Keep the salt with the ciphertext: it is not secret, and deriving the same keys
+again later needs it.
 
-**SymmetricKey memory behavior:** Keys live in regular process memory (not the Secure Enclave  -  only asymmetric `SecureEnclave.P256` keys are hardware-backed). CryptoKit automatically overwrites key material during deallocation. For persistent storage, serialize to the Keychain  -  never UserDefaults or files.
+The OWASP Password Storage Cheat Sheet sets 600,000 PBKDF2-HMAC-SHA256 iterations
+as the minimum; go lower only for a documented legacy interop requirement. Salts
+must be random and at least 16 bytes (32 above).
 
----
+For random bytes, `SecRandomCopyBytes` and `SymmetricKey(size:)` are the APIs to
+use. On Apple platforms `arc4random_buf` and `SystemRandomNumberGenerator` also draw
+from the kernel CSPRNG and are cryptographically secure, so they are not a
+vulnerability; still prefer the Security and CryptoKit calls for key material so the
+intent is explicit and the status is checked. What is never acceptable is a seeded
+or non-cryptographic generator (`rand()`, `random()`, `srand48`, a custom LCG) or
+`arc4random() % n` where modulo bias matters (use `arc4random_uniform`).
 
-## Migrating from CommonCrypto to CryptoKit
+### HKDF
 
-CommonCrypto's C API requires manual buffer allocation, unsafe pointer management, and provides no authenticated encryption. CryptoKit replaces all common operations with type-safe Swift that is harder to misuse.
-
-### Hashing: CC_SHA256 → SHA256
+HKDF (RFC 5869) expands high-entropy input into subkeys. It adds no work factor, so
+it is never enough on its own for a password.
 
 ```swift
-// ❌ Legacy CommonCrypto  -  unsafe pointers, manual buffer sizing
-import CommonCrypto
-var digest = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
-data.withUnsafeBytes { bytes in
-    CC_SHA256(bytes.baseAddress, CC_LONG(data.count), &digest)
-}
-
-// ✅ CryptoKit  -  one line, type-safe
-import CryptoKit
-let digest = SHA256.hash(data: data)
-```
-
-### Encryption: CCCrypt (AES-CBC) → AES.GCM
-
-```swift
-// ❌ Legacy CommonCrypto  -  AES-CBC, unauthenticated, manual IV, buffer math
-import CommonCrypto
-var outputBuffer = [UInt8](repeating: 0, count: data.count + kCCBlockSizeAES128)
-var numBytesEncrypted = 0
-let status = CCCrypt(
-    CCOperation(kCCEncrypt), CCAlgorithm(kCCAlgorithmAES),
-    CCOptions(kCCOptionPKCS7Padding),
-    keyBytes, kCCKeySizeAES256, ivBytes,
-    dataBytes, data.count,
-    &outputBuffer, outputBuffer.count, &numBytesEncrypted
+let rootKey = SymmetricKey(size: .bits256)
+let sessionKey = HKDF<SHA256>.deriveKey(
+    inputKeyMaterial: rootKey,
+    salt: Data("session-salt-01".utf8),
+    info: Data("chat-session/aes".utf8),
+    outputByteCount: 32
 )
-// ⚠️ Still need to add HMAC separately for integrity!
-
-// ✅ CryptoKit  -  one line, authenticated, automatic nonce
-import CryptoKit
-let sealedBox = try AES.GCM.seal(data, using: key)
 ```
 
-The critical architectural shift: CommonCrypto's `CCCrypt` provides AES-CBC (unauthenticated). Without manual Encrypt-then-MAC (HMAC), CBC ciphertext is vulnerable to **padding oracle attacks** and silent tampering. CryptoKit's AES-GCM bundles authentication  -  `open()` throws `CryptoKitError.authenticationFailure` if any byte is modified.
+Use one-shot `deriveKey` or the two-step `extract` then `expand`. Give each subkey
+its own `info` string for domain separation. The standalone `HKDF` type is iOS 14+.
+`deriveKey` does not throw, so there is no `try`.
 
-### HMAC: CCHmac → HMAC
+### Where keys live
 
 ```swift
-// ❌ Legacy CommonCrypto  -  C-style pointers
-import CommonCrypto
-var hmac = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
-CCHmac(CCHmacAlgorithm(kCCHmacAlgSHA256),
-       keyBytes, keyData.count, dataBytes, data.count, &hmac)
-
-// ✅ CryptoKit  -  generic, type-safe, constant-time verification built in
-import CryptoKit
-let mac = HMAC<SHA256>.authenticationCode(for: data, using: key)
-let valid = HMAC<SHA256>.isValidAuthenticationCode(mac, authenticating: data, using: key)
+// Broken: extractable from the binary with `strings`
+let embedded = SymmetricKey(data: Data(base64Encoded: "q83vEjRWeJq8...")!)
 ```
 
-### What to Keep in CommonCrypto
-
-CryptoKit deliberately omits: **PBKDF2** (use `CCKeyDerivationPBKDF`), **AES-CBC** (needed for legacy system interop), **AES-ECB** (almost never appropriate). For everything else, CryptoKit is the correct choice.
-
----
-
-## AI Code Generator Mistakes
-
-Large language models producing iOS cryptography code frequently introduce these errors:
-
-**1. Using CommonCrypto instead of CryptoKit.** Models trained on older code default to `CC_SHA256` and `CCCrypt`. These require manual memory management and lack authenticated encryption. Always use CryptoKit for iOS 13+ targets.
-
-**2. Reusing or hardcoding nonces.** Generators sometimes create a nonce once and reuse it, or use `Data(repeating: 0, count: 12)`. This enables complete AES-GCM key recovery (see nonce reuse section above). Omit the `nonce:` parameter to use automatic generation.
-
-**3. Using AES-CBC without authentication.** Models produce `CCCrypt`-based AES-CBC without HMAC, leaving ciphertext vulnerable to padding oracle attacks. AES-GCM and ChaChaPoly authenticate by default  -  no reason for unauthenticated encryption in new code.
-
-**4. Creating SymmetricKey directly from a password string.** `SymmetricKey(data: password.data(using: .utf8)!)` appears constantly. This skips key stretching entirely. Use PBKDF2 (≥600,000 iterations) for passwords, then optionally HKDF for subkey derivation.
-
-**5. Recommending MD5 or SHA-1 for checksums.** Models suggest `Insecure.MD5` for file integrity. SHA-256 is equally fast on modern hardware with actual collision resistance.
-
-**6. Manual SealedBox serialization.** Generators sometimes manually concatenate nonce + ciphertext + tag instead of using `SealedBox.combined`. This introduces serialization bugs  -  use the built-in `combined` property and `SealedBox(combined:)` initializer.
-
----
-
-## Quantum Considerations for Symmetric Cryptography
-
-WWDC 2025 session 314 ("Get ahead with quantum-secure cryptography") introduced ML-KEM and ML-DSA for asymmetric crypto (see [cryptokit-public-key.md]). For symmetric crypto, quantum computers weaken effective key strength by roughly half via Grover's algorithm:
-
-- **AES-256:** 128-bit post-quantum security  -  **sufficient**
-- **AES-128:** 64-bit post-quantum security  -  **insufficient**
-
-**Recommendation:** Use `SymmetricKey(size: .bits256)` exclusively. Quantum-secure TLS 1.3 is enabled by default in iOS 26 for `URLSession` and Network.framework connections.
-
-CryptoKit is built on Apple's **corecrypto** library (FIPS 140-2/140-3 validated, hand-tuned assembly per Apple microarchitecture). Apple's hardware crypto engine sits in the DMA path between flash storage and system memory, performing inline AES-256 encryption at line speed with zero CPU overhead.
-
----
-
-## OWASP Mapping
-
-CryptoKit symmetric practices address **OWASP Mobile Top 10 M10 (Insufficient Cryptography)**: weak algorithms, insufficient key lengths, improper key management, flawed implementation.
-
-**Relevant MASTG test cases:** MASTG-TEST-0061 (algorithm configuration), MASTG-TEST-0062 (key management), MASTG-TEST-0209 (insufficient key sizes), MASTG-TEST-0210 (broken symmetric algorithms), MASTG-TEST-0211 (broken hashing), MASTG-TEST-0213 (hardcoded keys), MASTG-TEST-0317 (broken encryption modes).
-
-**MASTG knowledge base:** MASTG-KNOW-0066 (CryptoKit), MASTG-KNOW-0067 (CommonCrypto).
-
-**MASWE entries:** MASWE-0010 (improper key derivation), MASWE-0013 (hardcoded cryptographic keys), MASWE-0020 (improper encryption), MASWE-0021 (improper hashing), MASWE-0022 (predictable initialization vectors).
-
-See [compliance-owasp-mapping.md] for the full compliance matrix.
-
----
-
-## Testing Guidance
-
-| Test Case                                  | What It Proves                 | Expected Outcome                       |
-| ------------------------------------------ | ------------------------------ | -------------------------------------- |
-| AES-GCM decrypt after ciphertext tampering | Authentication works           | `CryptoKitError.authenticationFailure` |
-| AES-GCM decrypt with wrong AAD             | Metadata binding               | `CryptoKitError.authenticationFailure` |
-| HMAC verify with wrong key                 | Timing-safe verification       | Returns `false`                        |
-| HMAC verify with tampered message          | Integrity detection            | Returns `false`                        |
-| SHA-3 availability fallback                | Backward compatibility         | Falls back to SHA-256 on <iOS 26       |
-| SealedBox round-trip (combined format)     | Serialization correctness      | Decrypted output matches plaintext     |
-| PBKDF2 + HKDF derivation determinism       | Key derivation reproducibility | Same password + salt → same key        |
-
-**CI scanning rules:** Flag `Insecure.MD5`, `Insecure.SHA1`, `CCCrypt`, `SymmetricKey(data:` followed by string literal, and hardcoded base64 key patterns in code review.
-
----
-
-## WWDC and Reference Citations
-
-- **WWDC 2019-709**  -  "Cryptography and Your Apps": CryptoKit introduction, SymmetricKey memory zeroing, automatic nonce generation rationale
-- **WWDC 2020**  -  "What's New in CryptoKit": HKDF addition (iOS 14), expanded key agreement
-- **WWDC 2025 Session 314**  -  "Get ahead with quantum-secure cryptography": AES-256 quantum guidance, SHA-3 context, ML-KEM/ML-DSA (asymmetric)
-- **Apple CryptoKit Documentation**  -  https://sosumi.ai/documentation/cryptokit/
-- **Apple Platform Security Guide**  -  corecrypto FIPS validation, hardware crypto engine, file Data Protection
-- **OWASP Mobile Top 10 (2024)**  -  M10: Insufficient Cryptography
-- **OWASP MASTG**  -  iOS cryptographic testing methodology
-- **RFC 5869**  -  HKDF specification
-- **Joux (2006)**  -  "Authentication Failures in NIST version of GCM" (nonce reuse attack)
-
----
-
-## Conclusion
-
-CryptoKit's design philosophy  -  authenticated encryption by default, automatic nonce generation, memory zeroing, constant-time comparisons  -  eliminates the most common categories of cryptographic implementation errors. For new code: `AES.GCM.seal()` with automatic nonces for encryption, `SHA256` (or `SHA3_256` on iOS 26+) for hashing, `HMAC<SHA256>` for authentication, and `SymmetricKey(size: .bits256)` for key generation. Derive keys from passwords with PBKDF2 (≥600,000 iterations, CommonCrypto) followed by HKDF (CryptoKit)  -  never pass raw passwords to `SymmetricKey(data:)`. Store keys in the Keychain, not source code. Prefer AES-GCM over ChaChaPoly on Apple hardware for the hardware acceleration advantage, but ChaChaPoly remains sound for cross-platform consistency or software-only environments.
-
----
-
-## Summary Checklist
-
-1. **CryptoKit over CommonCrypto**  -  All new hashing, HMAC, and encryption uses `import CryptoKit`, not `import CommonCrypto` (except PBKDF2)
-2. **SHA-256 minimum**  -  No `Insecure.MD5` or `Insecure.SHA1` for any security purpose; CI rules flag these
-3. **AES-GCM or ChaChaPoly**  -  All symmetric encryption uses AEAD; no unauthenticated AES-CBC in new code
-4. **Automatic nonces**  -  The `nonce:` parameter is omitted from `seal()` calls unless protocol-mandated; no static or zero nonces
-5. **256-bit keys**  -  `SymmetricKey(size: .bits256)` for quantum resilience; no `.bits128` for security-sensitive data
-6. **PBKDF2 before HKDF for passwords**  -  Password → `CCKeyDerivationPBKDF` (≥600,000 iterations, ≥16-byte random salt) → `SymmetricKey` → optional HKDF for subkeys; never raw password to `SymmetricKey(data:)`
-7. **SealedBox.combined for serialization**  -  Use `.combined` / `SealedBox(combined:)` for storage and network; no manual nonce/ciphertext/tag concatenation
-8. **Keys in Keychain**  -  Symmetric keys persisted via Keychain with `kSecAttrAccessibleWhenUnlockedThisDeviceOnly`; no hardcoded keys in source, no UserDefaults, no plist
-9. **Constant-time HMAC verification**  -  Use `HMAC.isValidAuthenticationCode()`, never manual byte comparison
-10. **SHA-3 availability guarded**  -  `SHA3_256` wrapped in `#available(iOS 26.0, macOS 26.0, *)` with SHA-256 fallback
-11. **Associated data for context binding**  -  AES-GCM `authenticating:` parameter used when ciphertext must be bound to metadata (user ID, resource ID, version)
+A 2025 industry study found hardcoded secrets in 48% of mobile apps, and any
+disassembler recovers them from the shipped binary. Keys instead come from one of:
+the Keychain with `kSecAttrAccessibleWhenUnlockedThisDeviceOnly`, derivation from
+something the user knows, or a secure server.
+
+A `SymmetricKey` lives in process memory. It is not in the Secure Enclave; only the
+asymmetric `SecureEnclave.P256` (and on iOS 26 the post-quantum SE types) are
+hardware-backed (see [secure-enclave.md](secure-enclave.md)). Persist symmetric keys
+only in the Keychain, never in UserDefaults or plain files
+(see [credential-storage-patterns.md](credential-storage-patterns.md)).
+
+## Moving off CommonCrypto
+
+CommonCrypto means manual buffers, unsafe pointers and no authenticated encryption.
+
+| CommonCrypto | CryptoKit |
+| --- | --- |
+| `CC_SHA256` with `withUnsafeBytes` and `CC_SHA256_DIGEST_LENGTH` | `SHA256.hash(data:)` |
+| `CCCrypt` AES-CBC, `kCCOptionPKCS7Padding`, `kCCKeySizeAES256`, manual IV, output buffer sized with `kCCBlockSizeAES128` | `AES.GCM.seal(_:using:)` |
+| `CCHmac(kCCHmacAlgSHA256, ...)` | `HMAC<SHA256>.authenticationCode` and `isValidAuthenticationCode` |
+
+CBC without encrypt-then-MAC is exposed to padding-oracle attacks and accepts
+tampered ciphertext silently. GCM's `open` throws
+`CryptoKitError.authenticationFailure` if any byte changed.
+
+Keep CommonCrypto only for PBKDF2 (`CCKeyDerivationPBKDF`), interop with an existing
+AES-CBC format, and AES-ECB, which is almost never the right choice.
+
+## Frequent mistakes
+
+1. Writing CommonCrypto for new code when the target is iOS 13+.
+2. Fixed, zero-filled or reused nonces. Leave `nonce:` out.
+3. AES-CBC with no MAC.
+4. Turning a password straight into a `SymmetricKey`. Use PBKDF2 with at least
+   600,000 iterations, then HKDF if subkeys are needed.
+5. MD5 or SHA-1 "just for a checksum". SHA-256 is just as fast in practice.
+6. Hand-concatenating nonce, ciphertext and tag. Use `SealedBox.combined` and
+   `SealedBox(combined:)`.
+
+## Post-quantum outlook
+
+WWDC 2025 session 314 introduced ML-KEM and ML-DSA for the asymmetric side (see
+[cryptokit-public-key.md](cryptokit-public-key.md)). Symmetric primitives survive a
+quantum adversary with roughly half their bit strength, so use
+`SymmetricKey(size: .bits256)` and nothing smaller. iOS 26 also turns on
+quantum-secure TLS 1.3 key exchange by default for `URLSession` and
+Network.framework.
+
+Under the hood CryptoKit calls corecrypto, which carries FIPS 140-2 / 140-3
+validation and hand-tuned assembly per CPU microarchitecture, and the hardware
+engine in the storage DMA path encrypts with AES-256 inline at line speed.
+
+## OWASP mapping
+
+This material addresses OWASP Mobile Top 10 (2024) M10, Insufficient Cryptography.
+
+- MASTG tests: MASTG-TEST-0061 (algorithm configuration), 0062 (key management),
+  0209 (key sizes), 0210 (broken symmetric algorithms), 0211 (broken hashing),
+  0213 (hardcoded keys), 0317 (broken modes).
+- MASTG knowledge: MASTG-KNOW-0066 (CryptoKit), MASTG-KNOW-0067 (CommonCrypto).
+- MASWE: 0010 (key derivation), 0013 (hardcoded keys), 0020 (improper encryption),
+  0021 (improper hashing), 0022 (predictable IVs).
+
+See also [common-anti-patterns.md](common-anti-patterns.md) (#6 nonce reuse, #7 weak
+hashes) and [compliance-owasp-mapping.md](compliance-owasp-mapping.md).
+
+## Tests worth writing
+
+- Flip one ciphertext byte; `open` throws `CryptoKitError.authenticationFailure`.
+- Open with different AAD; same error.
+- HMAC checked with the wrong key returns false.
+- HMAC over a modified message returns false.
+- Below iOS 26 the SHA-3 path falls back to SHA-256.
+- A `combined` round trip returns the original plaintext.
+- PBKDF2 plus HKDF is deterministic: same password and salt give the same key.
+
+CI should flag `Insecure.MD5`, `Insecure.SHA1`, `CCCrypt`, `SymmetricKey(data:` fed
+from a string literal, and base64 blobs that look like embedded keys.
+
+## Sources
+
+WWDC 2019 session 709 (Cryptography and Your Apps); WWDC 2020 "What's New in
+CryptoKit" (HKDF, iOS 14); WWDC 2025 session 314; the CryptoKit documentation; Apple
+Platform Security Guide; OWASP Mobile Top 10 (2024) M10; OWASP MASTG; RFC 5869;
+Joux 2006 on GCM nonce reuse.
+
+## Checklist
+
+- [ ] CryptoKit everywhere except PBKDF2.
+- [ ] Nothing weaker than SHA-256; CI flags MD5 and SHA-1.
+- [ ] Only AEAD (AES-GCM or ChaChaPoly); no unauthenticated CBC.
+- [ ] `nonce:` omitted unless a protocol dictates it; never static or zero.
+- [ ] 256-bit keys; no `.bits128` for sensitive data.
+- [ ] Passwords: `CCKeyDerivationPBKDF` with at least 600,000 iterations and a random
+      salt of 16 bytes or more, then HKDF if needed.
+- [ ] Serialization through `.combined` and `SealedBox(combined:)`.
+- [ ] Keys in the Keychain as WhenUnlockedThisDeviceOnly; never in source,
+      UserDefaults or a plist.
+- [ ] MACs verified with `HMAC.isValidAuthenticationCode()`.
+- [ ] `SHA3_256` behind `#available(iOS 26.0, macOS 26.0, *)` with a SHA-256 fallback.
+- [ ] Metadata (user id, resource id, version) bound through `authenticating:`.