@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/cryptokit/SKILL.md

@@ -1,495 +1,354 @@
 ---
 name: cryptokit
-description: "Use Apple CryptoKit for Swift cryptographic primitives. Use when hashing with SHA-2 or SHA-3, generating HMACs, encrypting with AES-GCM or ChaChaPoly, signing with P256/P384/P521/Curve25519 or ML-DSA keys, performing ECDH, HPKE, ML-KEM, or X-Wing key exchange, using Secure Enclave CryptoKit keys, or migrating CommonCrypto code to CryptoKit."
+description: "CryptoKit primitives in Swift: SHA-2 and SHA-3, HMAC, AES-GCM and ChaChaPoly, P256, P384, P521, Curve25519 and ML-DSA signatures, ECDH with HKDF, HPKE, ML-KEM and X-Wing, Secure Enclave keys. Use when hashing, encrypting, signing or exchanging keys, or migrating from CommonCrypto. Not for Keychain policy (swift-security)."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # CryptoKit
 
-Apple CryptoKit provides a Swift-native API for cryptographic operations:
-hashing, message authentication, symmetric encryption, public-key signing,
-key agreement, HPKE, quantum-secure key encapsulation/signing, and Secure
-Enclave-backed keys. Most core primitives are available on iOS 13+; check
-availability for HPKE (iOS 17+) and SHA-3 / post-quantum APIs (iOS 26+).
-Prefer CryptoKit over CommonCrypto or raw Security framework APIs for new
-cryptographic primitive code targeting Swift 6.3+.
-
-## Contents
-
-- [Hashing](#hashing)
-- [HMAC](#hmac)
-- [Symmetric Encryption](#symmetric-encryption)
-- [Public-Key Signing](#public-key-signing)
-- [Key Agreement](#key-agreement)
-- [HPKE](#hpke)
-- [Post-Quantum CryptoKit](#post-quantum-cryptokit)
-- [Secure Enclave](#secure-enclave)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+CryptoKit is Apple's Swift API for hashing, message authentication, symmetric
+encryption, signatures, key agreement, HPKE, quantum-secure key encapsulation
+and signatures, and keys kept in the Secure Enclave. For new code (Swift 6.3+)
+reach for it before CommonCrypto or raw Security framework calls.
 
-## Hashing
+| Feature set | Minimum iOS |
+|---|---|
+| Hashing, HMAC, AES-GCM, ChaChaPoly, P-curves, Curve25519, Secure Enclave P256 | 13 |
+| HPKE | 17 |
+| SHA-3, ML-KEM, ML-DSA, X-Wing | 26 |
 
-CryptoKit provides SHA256, SHA384, and SHA512 hash functions on iOS 13+.
-SHA3_256, SHA3_384, and SHA3_512 are available on iOS 26+. All conform
-to the `HashFunction` protocol.
+## Hashing
 
-### One-shot hashing
+`SHA256`, `SHA384` and `SHA512` exist from iOS 13; `SHA3_256`, `SHA3_384` and
+`SHA3_512` from iOS 26. All of them conform to `HashFunction`, so the API is the
+same for each.
 
 ```swift
 import CryptoKit
+import Foundation
 
-let data = Data("Hello, world!".utf8)
-let digest = SHA256.hash(data: data)
-let hex = digest.compactMap { String(format: "%02x", $0) }.joined()
-```
-
-SHA384 and SHA512 work identically -- substitute the type name.
-
-### SHA-3 availability
-
-Use SHA-3 only behind an availability check unless the deployment target is
-iOS 26+:
-
-```swift
-if #available(iOS 26.0, *) {
-    let digest = SHA3_256.hash(data: data)
+func fingerprint(_ blob: Data) -> String {
+    SHA256.hash(data: blob).map { String(format: "%02x", $0) }.joined()
 }
-```
-
-### Incremental hashing
-
-For large data or streaming input, hash incrementally:
-
-```swift
-var hasher = SHA256()
-hasher.update(data: chunk1)
-hasher.update(data: chunk2)
-let digest = hasher.finalize()
-```
-
-### Digest comparison
 
-Compare CryptoKit digest values directly. Do not convert digests to
-strings or arrays for security-sensitive equality checks.
+func strongerFingerprint(_ blob: Data) -> Data {
+    if #available(iOS 26.0, *) {
+        return Data(SHA3_384.hash(data: blob))
+    }
+    return Data(SHA384.hash(data: blob))
+}
 
-```swift
-let expected = SHA256.hash(data: reference)
-let actual = SHA256.hash(data: received)
-if expected == actual {
-    // Data integrity verified
+func streamingDigest(_ chunks: [Data]) -> SHA512.Digest {
+    var running = SHA512()
+    for chunk in chunks {
+        running.update(data: chunk)
+    }
+    return running.finalize()
 }
 ```
 
-## HMAC
+- Put SHA-3 behind `if #available(iOS 26.0, *)` unless the deployment target is
+  already 26.
+- Use the incremental `update(data:)` / `finalize()` form for large or
+  streamed input.
+- Compare digests with `==` on the digest values. Do not turn them into strings
+  or arrays for a security-relevant equality check.
 
-HMAC provides message authentication using a symmetric key and a hash function.
+## HMAC
 
-### Computing an authentication code
+An HMAC proves that data came from someone holding a shared symmetric key.
 
 ```swift
-let key = SymmetricKey(size: .bits256)
-let data = Data("message".utf8)
-
-let mac = HMAC<SHA256>.authenticationCode(for: data, using: key)
-```
+import CryptoKit
+import Foundation
 
-### Verifying an authentication code
+let webhookKey = SymmetricKey(size: .bits256)
 
-```swift
-let isValid = HMAC<SHA256>.isValidAuthenticationCode(
-    mac, authenticating: data, using: key
-)
-```
-
-This uses constant-time comparison internally.
+func tag(_ body: Data) -> HMAC<SHA256>.MAC {
+    HMAC<SHA256>.authenticationCode(for: body, using: webhookKey)
+}
 
-### Incremental HMAC
+func isGenuine(_ body: Data, mac: HMAC<SHA256>.MAC) -> Bool {
+    HMAC<SHA256>.isValidAuthenticationCode(mac, authenticating: body, using: webhookKey)
+}
 
-```swift
-var hmac = HMAC<SHA256>(key: key)
-hmac.update(data: chunk1)
-hmac.update(data: chunk2)
-let mac = hmac.finalize()
+func tagInPieces(_ parts: [Data]) -> HMAC<SHA256>.MAC {
+    var signer = HMAC<SHA256>(key: webhookKey)
+    parts.forEach { signer.update(data: $0) }
+    return signer.finalize()
+}
 ```
 
-## Symmetric Encryption
+`isValidAuthenticationCode(_:authenticating:using:)` compares in constant time.
 
-CryptoKit provides two authenticated encryption ciphers: AES-GCM and
-ChaChaPoly. Both produce a sealed box containing the nonce, ciphertext,
-and authentication tag.
+## Symmetric encryption
 
-### AES-GCM
+Both ciphers are AEAD: the sealed box bundles a nonce, the ciphertext and an
+authentication tag.
 
-The default choice for symmetric encryption. Hardware-accelerated on Apple
-silicon.
+- **AES-GCM** is the default. Apple silicon accelerates it in hardware.
+- **ChaChaPoly** fits devices without AES acceleration or protocols that
+  mandate ChaCha20-Poly1305, such as TLS cipher suites or WireGuard.
 
 ```swift
-let key = SymmetricKey(size: .bits256)
-let plaintext = Data("Secret message".utf8)
-
-// Encrypt
-let sealedBox = try AES.GCM.seal(plaintext, using: key)
-let ciphertext = sealedBox.combined!  // nonce + ciphertext + tag
-
-// Decrypt
-let box = try AES.GCM.SealedBox(combined: ciphertext)
-let decrypted = try AES.GCM.open(box, using: key)
-```
-
-### ChaChaPoly
-
-Use ChaChaPoly when AES hardware acceleration is unavailable or when
-interoperating with protocols that require ChaCha20-Poly1305 (e.g., TLS,
-WireGuard).
-
-```swift
-let sealedBox = try ChaChaPoly.seal(plaintext, using: key)
-let combined = sealedBox.combined  // Always non-optional for ChaChaPoly
-
-let box = try ChaChaPoly.SealedBox(combined: combined)
-let decrypted = try ChaChaPoly.open(box, using: key)
-```
-
-### Authenticated data
+import CryptoKit
+import Foundation
 
-Both ciphers support additional authenticated data (AAD). The AAD is
-authenticated but not encrypted -- useful for metadata that must remain
-in the clear but be tamper-proof.
+func lockNote(_ note: Data, key: SymmetricKey) throws -> Data {
+    let box = try AES.GCM.seal(note, using: key)
+    guard let packed = box.combined else { throw CryptoKitError.incorrectParameterSize }
+    return packed
+}
 
-```swift
-let header = Data("v1".utf8)
-let sealedBox = try AES.GCM.seal(
-    plaintext, using: key, authenticating: header
-)
-let decrypted = try AES.GCM.open(
-    sealedBox, using: key, authenticating: header
-)
-```
+func unlockNote(_ packed: Data, key: SymmetricKey) throws -> Data {
+    try AES.GCM.open(AES.GCM.SealedBox(combined: packed), using: key)
+}
 
-Use `.bits256` as the default `SymmetricKey` size for AES-256-GCM or
-ChaChaPoly. To create a key from existing data:
+func lockWithChaCha(_ note: Data, key: SymmetricKey) throws -> Data {
+    try ChaChaPoly.seal(note, using: key).combined
+}
 
-```swift
-let key = SymmetricKey(data: existingKeyData)
+func unlockWithChaCha(_ packed: Data, key: SymmetricKey) throws -> Data {
+    try ChaChaPoly.open(ChaChaPoly.SealedBox(combined: packed), using: key)
+}
 ```
 
-## Public-Key Signing
+`combined` is optional on `AES.GCM.SealedBox` (it is `nil` when a non-standard
+nonce size was used) and non-optional on `ChaChaPoly.SealedBox`.
 
-CryptoKit supports ECDSA signing with NIST curves and Ed25519 via
-Curve25519.
+### Additional authenticated data
 
-### NIST curves: P256, P384, P521
+Metadata that must travel in the clear but must not be altered goes in the AAD.
+It is authenticated, not encrypted.
 
 ```swift
-let signingKey = P256.Signing.PrivateKey()
-let publicKey = signingKey.publicKey
+import CryptoKit
+import Foundation
 
-// Sign
-let signature = try signingKey.signature(for: data)
+func sealRecord(_ payload: Data, recordID: String, key: SymmetricKey) throws -> AES.GCM.SealedBox {
+    try AES.GCM.seal(payload, using: key, authenticating: Data(recordID.utf8))
+}
 
-// Verify
-let isValid = publicKey.isValidSignature(signature, for: data)
+func openRecord(_ box: AES.GCM.SealedBox, recordID: String, key: SymmetricKey) throws -> Data {
+    try AES.GCM.open(box, using: key, authenticating: Data(recordID.utf8))
+}
 ```
 
-P384 and P521 use the same API -- substitute the curve name.
+### Keys
+
+`SymmetricKey(size: .bits256)` gives AES-256-GCM or ChaChaPoly strength and is
+the right default. Wrap existing key bytes with `SymmetricKey(data:)`.
 
-NIST keys support DER, PEM, X9.63, and raw representations. See
-[references/cryptokit-patterns.md](references/cryptokit-patterns.md) for
-serialization examples.
+## Signatures
 
-### Curve25519 / Ed25519
+ECDSA uses the NIST curves; Ed25519 comes from `Curve25519`.
 
 ```swift
-let signingKey = Curve25519.Signing.PrivateKey()
-let publicKey = signingKey.publicKey
+import CryptoKit
+import Foundation
 
-// Sign
-let signature = try signingKey.signature(for: data)
+func signRelease(_ manifest: Data) throws -> (P256.Signing.PublicKey, P256.Signing.ECDSASignature) {
+    let signer = P256.Signing.PrivateKey()
+    return (signer.publicKey, try signer.signature(for: manifest))
+}
+
+func verifyRelease(_ manifest: Data, key: P256.Signing.PublicKey, sig: P256.Signing.ECDSASignature) -> Bool {
+    key.isValidSignature(sig, for: manifest)
+}
 
-// Verify
-let isValid = publicKey.isValidSignature(signature, for: data)
+func edSign(_ message: Data) throws -> (Curve25519.Signing.PublicKey, Data) {
+    let signer = Curve25519.Signing.PrivateKey()
+    return (signer.publicKey, try signer.signature(for: message))
+}
 ```
 
-Curve25519 keys use `rawRepresentation` only (no DER/PEM/X9.63).
+P384 and P521 have the same shape as P256. NIST keys serialize as DER, PEM,
+X9.63 or raw. Curve25519 keys offer only `rawRepresentation`.
 
 ### Choosing a curve
 
-| Curve | Signature Scheme | Key Size | Typical Use |
+| Curve | Algorithm | Size | Notes |
 |---|---|---|---|
-| P256 | ECDSA | 256-bit | General purpose; Secure Enclave support |
-| P384 | ECDSA | 384-bit | Higher security requirements |
-| P521 | ECDSA | 521-bit | Maximum NIST security level |
-| Curve25519 | Ed25519 | 256-bit | Fast; simple API; no Secure Enclave |
+| P256 | ECDSA | 256-bit | general default; Secure Enclave capable |
+| P384 | ECDSA | 384-bit | higher margin |
+| P521 | ECDSA | 521-bit | top NIST level |
+| Curve25519 | Ed25519 | 256-bit | fast and simple; no Secure Enclave |
 
-Use P256 by default. Use Curve25519 when interoperating with Ed25519-based
-protocols.
+Start with P256. Use Curve25519 when a protocol specifies Ed25519.
 
-## Key Agreement
+## Key agreement
 
-Key agreement lets two parties derive a shared symmetric key from their
-public/private key pairs using ECDH.
-
-### ECDH with P256
+ECDH turns two key pairs into one shared secret. Each side combines its own
+private key with the other side's public key, and both arrive at the same value.
 
 ```swift
-// Alice
-let aliceKey = P256.KeyAgreement.PrivateKey()
-
-// Bob
-let bobKey = P256.KeyAgreement.PrivateKey()
-
-// Alice computes shared secret
-let sharedSecret = try aliceKey.sharedSecretFromKeyAgreement(
-    with: bobKey.publicKey
-)
-
-// Derive a symmetric key using HKDF
-let symmetricKey = sharedSecret.hkdfDerivedSymmetricKey(
-    using: SHA256.self,
-    salt: Data("salt".utf8),
-    sharedInfo: Data("my-app-v1".utf8),
-    outputByteCount: 32
-)
-```
-
-Bob computes the same `sharedSecret` using his private key and Alice's
-public key. Both derive the same `symmetricKey`.
-
-### ECDH with Curve25519
+import CryptoKit
+import Foundation
+
+func sessionKey(mine: P256.KeyAgreement.PrivateKey, theirs: P256.KeyAgreement.PublicKey) throws -> SymmetricKey {
+    let secret = try mine.sharedSecretFromKeyAgreement(with: theirs)
+    return secret.hkdfDerivedSymmetricKey(
+        using: SHA256.self,
+        salt: Data("chat-v2-salt".utf8),
+        sharedInfo: Data("chat-v2 message key".utf8),
+        outputByteCount: 32
+    )
+}
 
-```swift
-let aliceKey = Curve25519.KeyAgreement.PrivateKey()
-let bobKey = Curve25519.KeyAgreement.PrivateKey()
-
-let sharedSecret = try aliceKey.sharedSecretFromKeyAgreement(
-    with: bobKey.publicKey
-)
-
-let symmetricKey = sharedSecret.hkdfDerivedSymmetricKey(
-    using: SHA256.self,
-    salt: Data(),
-    sharedInfo: Data("context".utf8),
-    outputByteCount: 32
-)
+func x25519Key(mine: Curve25519.KeyAgreement.PrivateKey, theirs: Curve25519.KeyAgreement.PublicKey) throws -> SymmetricKey {
+    try mine.sharedSecretFromKeyAgreement(with: theirs).hkdfDerivedSymmetricKey(
+        using: SHA256.self,
+        salt: Data(),
+        sharedInfo: Data("sync-pairing v1".utf8),
+        outputByteCount: 32
+    )
+}
 ```
 
-### Key derivation functions
+### Derivation
 
-`SharedSecret` is not directly usable as a `SymmetricKey`. Always derive
-a key using one of:
+A `SharedSecret` is not a `SymmetricKey` and must always go through a KDF.
 
-| Method | Standard | Use |
+| Method | Standard | When |
 |---|---|---|
-| `hkdfDerivedSymmetricKey` | HKDF (RFC 5869) | Recommended default |
-| `x963DerivedSymmetricKey` | ANSI X9.63 | Interop with X9.63 systems |
+| `hkdfDerivedSymmetricKey` | HKDF, RFC 5869 | default choice |
+| `x963DerivedSymmetricKey` | ANSI X9.63 | interoperating with X9.63 systems |
 
-Always provide a non-empty `sharedInfo` string to bind the derived key
-to a specific protocol context.
+Always pass a non-empty `sharedInfo` that names the protocol and purpose, so
+the derived key cannot be reused somewhere else.
 
 ## HPKE
 
-HPKE is available on iOS 17+ for public-key encryption workflows. Prefer it over
-hand-rolled ECDH + HKDF + AEAD protocols when encrypting to a recipient public key.
+HPKE (iOS 17+) is the ready-made way to encrypt to someone's public key.
+Prefer it over wiring ECDH, HKDF and an AEAD together by hand.
 
 ```swift
-let info = Data("my-protocol-v1".utf8)
-let recipientKey = Curve25519.KeyAgreement.PrivateKey()
-var sender = try HPKE.Sender(
-    recipientKey: recipientKey.publicKey,
-    ciphersuite: .Curve25519_SHA256_ChachaPoly,
-    info: info
-)
-let encapsulatedKey = sender.encapsulatedKey
-let ciphertext = try sender.seal(
-    plaintext,
-    authenticating: Data("metadata".utf8)
-)
-
-var recipient = try HPKE.Recipient(
-    privateKey: recipientKey,
-    ciphersuite: .Curve25519_SHA256_ChachaPoly,
-    info: info,
-    encapsulatedKey: encapsulatedKey
-)
-```
-
-`HPKE.Sender` and `HPKE.Recipient` are stateful; keep them as `var`, send
-`encapsulatedKey` alongside the ciphertext, and open messages in the same
-order they were sealed. See [references/cryptokit-patterns.md](references/cryptokit-patterns.md)
-for ciphersuite selection and post-quantum HPKE.
-
-## Post-Quantum CryptoKit
-
-iOS 26+ adds quantum-secure APIs:
-
-- Key encapsulation: `MLKEM768`, `MLKEM1024`
-- Hybrid HPKE: `XWingMLKEM768X25519` with `.XWingMLKEM768X25519_SHA256_AES_GCM_256`
-- Digital signatures: `MLDSA65`, `MLDSA87`
-- Secure Enclave variants: `SecureEnclave.MLKEM768`, `SecureEnclave.MLKEM1024`,
-  `SecureEnclave.MLDSA65`, `SecureEnclave.MLDSA87`
-
-Use hybrid mechanisms for migration when both classical and quantum-secure
-resistance matter. Account for much larger public keys, ciphertexts, and
-signatures than P256 or Curve25519.
-
-## Secure Enclave
-
-The Secure Enclave provides hardware-backed key storage. Private keys
-never leave the hardware. For classical elliptic-curve CryptoKit, Secure
-Enclave supports P256 signing and key agreement. On iOS 26+ supported
-hardware, CryptoKit also exposes Secure Enclave ML-KEM key encapsulation
-and ML-DSA signing types.
-
-### Availability check
+import CryptoKit
+import Foundation
 
-```swift
-guard SecureEnclave.isAvailable else {
-    // Fall back to software keys
-    return
+func encryptForDevice(_ messages: [Data], to device: Curve25519.KeyAgreement.PublicKey) throws -> (Data, [Data]) {
+    let context = Data("device-backup v3".utf8)
+    var sender = try HPKE.Sender(recipientKey: device, ciphersuite: .Curve25519_SHA256_ChachaPoly, info: context)
+    let sealed = try messages.map { try sender.seal($0, authenticating: Data("header".utf8)) }
+    return (sender.encapsulatedKey, sealed)
 }
-```
-
-### Creating a Secure Enclave signing key
-
-```swift
-let privateKey = try SecureEnclave.P256.Signing.PrivateKey()
-let publicKey = privateKey.publicKey  // Standard P256.Signing.PublicKey
-
-let signature = try privateKey.signature(for: data)
-let isValid = publicKey.isValidSignature(signature, for: data)
-```
-
-### Access control
-
-Use `SecAccessControl` with `.privateKeyUsage` when the key requires biometric
-or passcode-gated use. Keep detailed Keychain policy decisions in the
-`swift-security` domain.
-
-### Persisting Secure Enclave keys
-
-The `dataRepresentation` is an encrypted blob that only the same device's
-Secure Enclave can restore. Store it in the Keychain.
-
-```swift
-// Export
-let blob = privateKey.dataRepresentation
 
-// Restore
-let restored = try SecureEnclave.P256.Signing.PrivateKey(
-    dataRepresentation: blob
-)
-```
-
-### Secure Enclave key agreement
-
-```swift
-let seKey = try SecureEnclave.P256.KeyAgreement.PrivateKey()
-let peerPublicKey: P256.KeyAgreement.PublicKey = // from peer
-
-let sharedSecret = try seKey.sharedSecretFromKeyAgreement(
-    with: peerPublicKey
-)
-```
-
-## Common Mistakes
-
-### 1. Using the shared secret directly as a key
-
-```swift
-// DON'T
-let badKey = sharedSecret.withUnsafeBytes { bytes in
-    SymmetricKey(data: Data(bytes))
+func decryptOnDevice(_ sealed: [Data], encapsulated: Data, key: Curve25519.KeyAgreement.PrivateKey) throws -> [Data] {
+    let context = Data("device-backup v3".utf8)
+    var receiver = try HPKE.Recipient(privateKey: key, ciphersuite: .Curve25519_SHA256_ChachaPoly,
+                                      info: context, encapsulatedKey: encapsulated)
+    return try sealed.map { try receiver.open($0, authenticating: Data("header".utf8)) }
 }
-
-// DO -- derive with HKDF
-let goodKey = sharedSecret.hkdfDerivedSymmetricKey(
-    using: SHA256.self,
-    salt: salt,
-    sharedInfo: info,
-    outputByteCount: 32
-)
 ```
 
-### 2. Reusing nonces
+- `HPKE.Sender` and `HPKE.Recipient` keep a sequence counter, so they must be
+  `var`.
+- Ship `encapsulatedKey` together with the ciphertext.
+- The recipient must open messages in the same order the sender sealed them.
 
-```swift
-// DON'T -- hardcoded nonce
-let nonce = try AES.GCM.Nonce(data: Data(repeating: 0, count: 12))
-let box = try AES.GCM.seal(data, using: key, nonce: nonce)
+## Post-quantum CryptoKit (iOS 26+)
 
-// DO -- let CryptoKit generate a random nonce (default behavior)
-let box = try AES.GCM.seal(data, using: key)
-```
+| Purpose | Types |
+|---|---|
+| Key encapsulation | `MLKEM768`, `MLKEM1024` |
+| Hybrid HPKE | `XWingMLKEM768X25519` with `.XWingMLKEM768X25519_SHA256_AES_GCM_256` |
+| Signatures | `MLDSA65`, `MLDSA87` |
+| Secure Enclave | `SecureEnclave.MLKEM768`, `SecureEnclave.MLKEM1024`, `SecureEnclave.MLDSA65`, `SecureEnclave.MLDSA87` |
 
-### 3. Ignoring authentication tag verification
+- During a migration where both classical and quantum resistance matter, use
+  the hybrid X-Wing suite.
+- Keys, ciphertexts and signatures are far larger than their P256 or
+  Curve25519 counterparts. Budget for that in storage and on the wire.
 
-```swift
-// DON'T -- manually strip tag and decrypt
-// DO -- always use AES.GCM.open() or ChaChaPoly.open()
-// which verifies the tag automatically
-```
-
-### 4. Using Insecure hashes for security
-
-```swift
-// DON'T -- MD5/SHA1 for integrity or security
-import CryptoKit
-let bad = Insecure.MD5.hash(data: data)
-
-// DO -- use SHA256 or stronger
-let good = SHA256.hash(data: data)
-```
+## Secure Enclave
 
-`Insecure.MD5` and `Insecure.SHA1` exist only for legacy compatibility
-(checksum verification, protocol interop). Never use them for new
-security-sensitive operations.
+The Secure Enclave generates and holds private keys in hardware; they never
+leave it.
 
-### 5. Storing symmetric keys in UserDefaults
+- Classical support covers P256 signing and P256 key agreement only.
+- On iOS 26 with supported hardware, ML-KEM and ML-DSA keys can live there too.
+- Always check `SecureEnclave.isAvailable` and fall back to software keys.
 
 ```swift
-// DON'T
-UserDefaults.standard.set(rawKeyData, forKey: "encryptionKey")
+import CryptoKit
+import Foundation
+import Security
 
-// DO -- store in Keychain
-// See references/cryptokit-patterns.md for Keychain storage patterns
-```
+enum DeviceKeyError: Error {
+    case noSecureEnclave
+    case accessControlRejected
+}
 
-### 6. Not checking Secure Enclave availability
+func deviceSigningKey() throws -> Data {
+    guard SecureEnclave.isAvailable else { throw DeviceKeyError.noSecureEnclave }
+    guard let rule = SecAccessControlCreateWithFlags(nil, kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
+                                                     [.privateKeyUsage, .biometryCurrentSet], nil) else {
+        throw DeviceKeyError.accessControlRejected
+    }
+    let key = try SecureEnclave.P256.Signing.PrivateKey(accessControl: rule)
+    _ = key.publicKey
+    return key.dataRepresentation
+}
 
-```swift
-// DON'T -- crash on simulator or unsupported hardware
-let key = try SecureEnclave.P256.Signing.PrivateKey()
+func restoreDeviceKey(_ blob: Data) throws -> SecureEnclave.P256.Signing.PrivateKey {
+    try SecureEnclave.P256.Signing.PrivateKey(dataRepresentation: blob)
+}
 
-// DO
-guard SecureEnclave.isAvailable else { /* fallback */ }
-let key = try SecureEnclave.P256.Signing.PrivateKey()
+func enclaveAgreement(with peer: P256.KeyAgreement.PublicKey) throws -> SharedSecret {
+    let mine = try SecureEnclave.P256.KeyAgreement.PrivateKey()
+    return try mine.sharedSecretFromKeyAgreement(with: peer)
+}
 ```
 
-## Review Checklist
-
-- [ ] Using CryptoKit, not CommonCrypto or raw Security framework
-- [ ] SHA256+ for hashing; no MD5/SHA1 for security purposes
-- [ ] HMAC verification uses `isValidAuthenticationCode` (constant-time)
-- [ ] AES-GCM or ChaChaPoly for symmetric encryption; 256-bit keys
-- [ ] Nonces are random (default) -- not hardcoded or reused
-- [ ] Authenticated data (AAD) used where metadata needs integrity
-- [ ] SharedSecret derived via HKDF, not used directly
-- [ ] sharedInfo parameter is non-empty and context-specific
-- [ ] HPKE used instead of custom ECDH+HKDF+AEAD for recipient public-key encryption on iOS 17+
-- [ ] SHA-3 and post-quantum APIs guarded with iOS 26+ availability
-- [ ] Secure Enclave availability checked before use
-- [ ] Secure Enclave key `dataRepresentation` stored in Keychain
-- [ ] Private keys not logged, printed, or serialized unnecessarily
-- [ ] Symmetric keys stored in Keychain, not UserDefaults or files
-- [ ] Encryption export compliance considered (`ITSAppUsesNonExemptEncryption`)
+- The public key of a Secure Enclave signing key is an ordinary
+  `P256.Signing.PublicKey`; signing and verifying look the same as in software.
+- Gate use behind biometrics or the passcode with a `SecAccessControl` that
+  includes `.privateKeyUsage`. Deeper Keychain policy choices belong to
+  `swift-security`.
+- `dataRepresentation` is an encrypted blob that only the same device's Secure
+  Enclave can turn back into a key. Store it in the Keychain and restore it
+  with `init(dataRepresentation:)`.
+
+## Common mistakes
+
+- **Using the raw shared secret as a key.** Always derive with HKDF.
+- **Fixed or repeated nonces.** Passing something like
+  `AES.GCM.Nonce(data: Data(count: 12))` to `seal(_:using:nonce:)` for every
+  message breaks GCM. Let CryptoKit pick a random nonce by leaving the argument
+  out.
+- **Decrypting without the tag check.** Never peel the tag off and decrypt by
+  hand. `AES.GCM.open` and `ChaChaPoly.open` verify it for you.
+- **Insecure hashes for security.** `Insecure.MD5` and `Insecure.SHA1` exist
+  for legacy checksums and protocol interop only.
+- **Key bytes in `UserDefaults`.** Keys go in the Keychain; see
+  [the Keychain patterns](references/cryptokit-patterns.md#keychain-storage).
+- **Secure Enclave without an availability check.** Key creation fails in
+  Simulator and on unsupported hardware.
+
+## Review checklist
+
+- [ ] CryptoKit is used instead of CommonCrypto or raw Security calls
+- [ ] Hashing uses SHA-256 or stronger; no MD5 or SHA-1 for security
+- [ ] HMACs are verified with `isValidAuthenticationCode`
+- [ ] Encryption is AES-GCM or ChaChaPoly with 256-bit keys
+- [ ] Nonces are random, never hardcoded or reused
+- [ ] AAD protects metadata that needs integrity
+- [ ] Every `SharedSecret` goes through HKDF
+- [ ] `sharedInfo` is non-empty and specific to the context
+- [ ] HPKE replaces hand-built ECDH + HKDF + AEAD for recipient encryption on iOS 17+
+- [ ] SHA-3 and post-quantum code is behind an iOS 26 availability check
+- [ ] `SecureEnclave.isAvailable` is checked
+- [ ] Secure Enclave `dataRepresentation` is stored in the Keychain
+- [ ] Private keys are never logged, printed or serialized without need
+- [ ] Symmetric keys live in the Keychain, not `UserDefaults` or loose files
+- [ ] Export compliance (`ITSAppUsesNonExemptEncryption`) has been considered
 
 ## References
 
-- Extended patterns (key serialization, Insecure module, Keychain integration, AES key wrapping, HPKE): [references/cryptokit-patterns.md](references/cryptokit-patterns.md)
-- Apple documentation: [CryptoKit](https://sosumi.ai/documentation/cryptokit)
-- Apple documentation: [HPKE](https://sosumi.ai/documentation/cryptokit/hpke)
-- Apple documentation: [Quantum-secure workflows](https://sosumi.ai/documentation/cryptokit/enhancing-your-app-s-privacy-and-security-with-quantum-secure-workflows)
-- Apple sample: [Performing Common Cryptographic Operations](https://sosumi.ai/documentation/cryptokit/performing-common-cryptographic-operations)
-- Apple sample: [Storing CryptoKit Keys in the Keychain](https://sosumi.ai/documentation/cryptokit/storing-cryptokit-keys-in-the-keychain)
+- [CryptoKit patterns](references/cryptokit-patterns.md) - key serialization, Keychain storage, AES key wrap, HKDF, HPKE ciphersuites, post-quantum usage, the Insecure namespace, sealed box layout, digest signing, export compliance, performance, CommonCrypto migration
+- [CryptoKit](https://developer.apple.com/documentation/cryptokit)
+- [HPKE](https://developer.apple.com/documentation/cryptokit/hpke)
+- [Enhancing your app's privacy and security with quantum-secure workflows](https://developer.apple.com/documentation/cryptokit/enhancing-your-app-s-privacy-and-security-with-quantum-secure-workflows)
+- [Performing common cryptographic operations](https://developer.apple.com/documentation/cryptokit/performing-common-cryptographic-operations)
+- [Storing CryptoKit keys in the keychain](https://developer.apple.com/documentation/cryptokit/storing-cryptokit-keys-in-the-keychain)