@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

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

@@ -1,538 +1,467 @@
-# CryptoKit Public-Key Cryptography
+# CryptoKit: Signatures, Key Agreement, HPKE and Post-Quantum
 
-> **Scope:** ECDSA signing, ECDH key agreement, HPKE (iOS 17+), ML-KEM/ML-DSA and hybrid migration patterns (iOS 26+), key serialization, and Secure Enclave integration boundaries on Apple platforms.
->
-> **Cross-references:** Secure Enclave key lifecycle → `secure-enclave.md`. Symmetric encryption after key agreement → `cryptokit-symmetric.md`. Keychain storage of CryptoKit keys → `credential-storage-patterns.md`. RSA → ECC migration → section "Stop Using RSA for New Apple Development" below.
+Topics: digital signatures (ECDSA, EdDSA), Diffie-Hellman over elliptic curves,
+hybrid public-key encryption from iOS 17,
+ML-KEM and ML-DSA with hybrid migration (iOS 26+), key serialization, and where the
+Secure Enclave fits.
 
-CryptoKit's asymmetric cryptography API covers ECDSA signing, ECDH key agreement, HPKE (iOS 17+), and post-quantum ML-KEM/ML-DSA (iOS 26+). The framework enforces correct usage through its type system  -  signing keys cannot perform key agreement, shared secrets must pass through HKDF before use, and Secure Enclave access is limited to P256 for classical curves. This reference covers every asymmetric primitive from iOS 13 through iOS 26 with verified Swift implementations, common AI-generator mistakes, and the quantum migration path.
+CryptoKit's types carry several rules for you: a signing key cannot perform key
+agreement, a shared secret cannot be used as a key until it is run through a KDF,
+and the only classical curve the Secure Enclave accepts is P-256.
 
-CryptoKit was introduced at WWDC 2019 (session 709, "Cryptography and Your Apps") as a Swift-native replacement for the Security framework's C-based `SecKey` API. It wraps Apple's corecrypto library with hand-tuned assembly per microarchitecture, delivering both performance and memory safety  -  private key material is automatically zeroed on deallocation. iOS 14 added PEM/DER interoperability and standalone HKDF. iOS 17 brought HPKE (RFC 9180). iOS 26 (WWDC 2025, session 314, "Get ahead with quantum-secure cryptography") completes the picture with formally verified post-quantum algorithms and quantum-secure TLS enabled by default.
-
----
+Background: CryptoKit arrived at WWDC 2019 (session 709) as a Swift replacement for
+the C-level `SecKey` API. It sits on corecrypto and zeroes private key memory on
+deallocation. iOS 14 added PEM/DER import and export plus standalone HKDF. iOS 17
+added HPKE (RFC 9180). iOS 26 (WWDC 2025 session 314) added formally verified
+post-quantum algorithms and turned on post-quantum TLS by default.
 
 ## Contents
 
-- [Curve and Algorithm Selection Guide](#curve-and-algorithm-selection-guide)
-  - [Classical Curves](#classical-curves)
-  - [Post-Quantum Algorithms (iOS 26+)](#post-quantum-algorithms-ios-26)
-  - [Selection Decision Matrix](#selection-decision-matrix)
-  - [Algorithm Quick Reference](#algorithm-quick-reference)
-- [Signing and Key Agreement Are Separate Type Hierarchies](#signing-and-key-agreement-are-separate-type-hierarchies)
-  - [✅ Correct: P256 key generation, signing, and verification](#correct-p256-key-generation-signing-and-verification)
-  - [❌ Wrong: Mixing signing and key agreement key types](#wrong-mixing-signing-and-key-agreement-key-types)
-- [Key Agreement with HKDF Derivation](#key-agreement-with-hkdf-derivation)
-  - [✅ Correct: Curve25519 key agreement with HKDF derivation](#correct-curve25519-key-agreement-with-hkdf-derivation)
-  - [❌ Wrong: Using SharedSecret directly as an encryption key](#wrong-using-sharedsecret-directly-as-an-encryption-key)
-- [HPKE Simplifies Public-Key Encryption (iOS 17+)](#hpke-simplifies-public-key-encryption-ios-17)
-  - [Built-in Cipher Suites](#built-in-cipher-suites)
-  - [✅ Correct: HPKE encryption and decryption](#correct-hpke-encryption-and-decryption)
-  - [Three Critical HPKE Details AI Generators Get Wrong](#three-critical-hpke-details-ai-generators-get-wrong)
-- [Post-Quantum Cryptography (iOS 26+)](#post-quantum-cryptography-ios-26)
-  - [✅ Correct: ML-KEM-768 key encapsulation](#correct-ml-kem-768-key-encapsulation)
-  - [✅ Correct: ML-DSA-65 signing](#correct-ml-dsa-65-signing)
-  - [✅ Correct: Hybrid post-quantum with HPKE (recommended migration path)](#correct-hybrid-post-quantum-with-hpke-recommended-migration-path)
-  - [✅ Correct: Hybrid signing (ML-DSA + ECDSA) for transition period](#correct-hybrid-signing-ml-dsa-ecdsa-for-transition-period)
-- [PEM and DER Interoperability (iOS 14+)](#pem-and-der-interoperability-ios-14)
-  - [✅ Correct: PEM key export and import](#correct-pem-key-export-and-import)
-  - [Key Format Reference](#key-format-reference)
-  - [Keychain Storage of CryptoKit Keys](#keychain-storage-of-cryptokit-keys)
-- [Secure Enclave Integration (Brief  -  See `secure-enclave.md`)](#secure-enclave-integration-brief-see-secure-enclavemd)
-- [Stop Using RSA for New Apple Development](#stop-using-rsa-for-new-apple-development)
-  - [❌ Wrong: RSA when EC is available](#wrong-rsa-when-ec-is-available)
-  - [Preferred replacement: P256 signing in CryptoKit](#preferred-replacement-p256-signing-in-cryptokit)
-- [Common AI-Generator Mistakes](#common-ai-generator-mistakes)
-- [iOS Version Requirements](#ios-version-requirements)
-- [Performance and Thread Safety](#performance-and-thread-safety)
-- [WWDC Sessions and Documentation References](#wwdc-sessions-and-documentation-references)
-- [Conclusion](#conclusion)
-- [Summary Checklist](#summary-checklist)
-
-## Curve and Algorithm Selection Guide
-
-The single most important decision is choosing the right curve or algorithm. AI generators frequently recommend Curve25519 when Secure Enclave protection is required, or default to P-256 when modern constant-time performance matters more.
-
-### Classical Curves
-
-**P256 (secp256r1 / NIST P-256)**  -  The only classical curve supported by the Secure Enclave. Required for hardware-backed key storage with biometric access control. Conforms to NIST FIPS 186-5 for US government compliance and has the broadest interoperability with TLS, X.509 certificates, and server-side libraries. Public keys are 64 bytes (uncompressed raw), signatures are 64 bytes (raw r‖s). PEM and DER export supported from iOS 14.
-
-**Curve25519 (X25519 / Ed25519)**  -  Should be the default for software-only keys. Its rigid parameter design eliminates entire classes of implementation vulnerabilities  -  constant-time execution is inherent to the curve arithmetic, no point validation is required, and public keys are a compact 32 bytes. Ed25519 handles signing; X25519 handles key agreement. The tradeoff: only `rawRepresentation` is available (no PEM, no DER, no x963), and there is no Secure Enclave support.
-
-**P384 and P521**  -  Exist for specific compliance requirements. P384 provides ~192-bit security (NIST Category 3); P521 provides ~256-bit security (Category 5). Their API surface mirrors P256 exactly. Use only when a specification or regulatory framework demands them.
-
-### Post-Quantum Algorithms (iOS 26+)
-
-**ML-KEM-768 / ML-KEM-1024**  -  FIPS 203 lattice-based key encapsulation. ML-KEM-768 targets ~AES-128 equivalent security; ML-KEM-1024 targets ~AES-192. Both support Secure Enclave hardware isolation on iOS 26+.
-
-**ML-DSA-65 / ML-DSA-87**  -  FIPS 204 lattice-based digital signatures. ML-DSA-65 targets ~AES-128 equivalent; ML-DSA-87 targets ~AES-192. Both support Secure Enclave on iOS 26+.
-
-**X-Wing (XWingMLKEM768X25519)**  -  Hybrid KEM combining ML-KEM-768 with X25519. Both algorithms must be broken to compromise the exchange. This is Apple's recommended migration path for custom protocols via HPKE.
-
-### Selection Decision Matrix
-
-| Scenario                      | iOS Version | Default Choice                                     | Rationale                                    |
-| ----------------------------- | ----------- | -------------------------------------------------- | -------------------------------------------- |
-| Hardware-isolated keys        | All         | `SecureEnclave.P256.*`                             | Private key never leaves the coprocessor     |
-| Software signing/agreement    | All         | `Curve25519.*`                                     | Constant-time, compact, modern protocols     |
-| FIPS/enterprise interop       | 17+         | `P256` or `P384`                                   | Aligns with legacy standards                 |
-| E2E encryption (modern)       | 17+         | HPKE with `Curve25519_SHA256_ChachaPoly`           | High performance, broad client support       |
-| E2E encryption (future-proof) | 26+         | HPKE with `XWingMLKEM768X25519_SHA256_AES_GCM_256` | Hybrid PQC against harvest-now-decrypt-later |
-| Maximum classical security    | All         | `P521`                                             | ~256-bit security; only when mandated        |
-
-### Algorithm Quick Reference
-
-| Algorithm   | Security | iOS | Secure Enclave | Pub Key Size | Best For                        |
-| ----------- | -------- | --- | -------------- | ------------ | ------------------------------- |
-| P256        | ~128-bit | 13+ | ✅ Yes         | 64 bytes     | Hardware keys, NIST compliance  |
-| P384        | ~192-bit | 13+ | ❌ No          | 96 bytes     | Government/compliance           |
-| P521        | ~256-bit | 13+ | ❌ No          | 132 bytes    | Maximum classical security      |
-| Curve25519  | ~128-bit | 13+ | ❌ No          | 32 bytes     | Modern protocols, software keys |
-| ML-KEM-768  | ~AES-128 | 26+ | ✅ Yes         | 1,184 bytes  | Key encapsulation               |
-| ML-KEM-1024 | ~AES-192 | 26+ | ✅ Yes         | 1,568 bytes  | Higher-security KEM             |
-| ML-DSA-65   | ~AES-128 | 26+ | ✅ Yes         | 1,952 bytes  | Post-quantum signatures         |
-| ML-DSA-87   | ~AES-192 | 26+ | ✅ Yes         | 2,592 bytes  | Higher-security signatures      |
-| X-Wing      | Hybrid   | 26+ | ✅ Yes         | 1,216 bytes  | Hybrid PQC KEM                  |
-
-On Apple Silicon, both P256 and Curve25519 are heavily optimized in corecrypto with hand-tuned assembly. Performance differences are negligible for most applications  -  Apple's NISTZ256 optimization closes the gap that Curve25519 holds in non-Apple benchmarks.
-
----
-
-## Signing and Key Agreement Are Separate Type Hierarchies
-
-CryptoKit's most important design decision is splitting each curve into two non-interchangeable type families: `Signing` and `KeyAgreement`. A `P256.Signing.PrivateKey` cannot perform key agreement. A `Curve25519.KeyAgreement.PrivateKey` cannot sign. The compiler enforces this at build time. AI generators frequently conflate these, producing code that fails to compile.
-
-### ✅ Correct: P256 key generation, signing, and verification
+- [Picking a curve or algorithm](#picking-a-curve-or-algorithm)
+- [Signing and key agreement are different types](#signing-and-key-agreement-are-different-types)
+- [Key agreement always goes through a KDF](#key-agreement-always-goes-through-a-kdf)
+- [HPKE (iOS 17+)](#hpke-ios-17)
+- [Post-quantum cryptography (iOS 26+)](#post-quantum-cryptography-ios-26)
+- [PEM and DER (iOS 14+)](#pem-and-der-ios-14)
+- [The Secure Enclave, briefly](#the-secure-enclave-briefly)
+- [RSA](#rsa)
+- [Frequent mistakes](#frequent-mistakes)
+- [Availability](#availability)
+- [Performance and threads](#performance-and-threads)
+- [Sources](#sources)
+- [Summary](#summary)
+- [Checklist](#checklist)
+
+## Picking a curve or algorithm
+
+Two errors show up often: suggesting Curve25519 when the key must live in the
+Secure Enclave, and suggesting P-256 when the goal is simple constant-time software
+keys.
+
+- **P256 (secp256r1).** The only classical curve the Secure Enclave supports, so
+  required for hardware keys with a biometric access control. NIST FIPS 186-5, the
+  widest TLS, X.509 and server interop. Raw public key 64 bytes (uncompressed x||y),
+  raw signature 64 bytes (r||s). PEM/DER from iOS 14.
+- **Curve25519** (X25519 for agreement, Ed25519 for signing). The default for
+  software-only keys: fixed, rigid parameters, constant time by construction, no
+  point validation to forget, 32-byte public keys. Only `rawRepresentation` exists
+  (no PEM, DER or x963). Not available in the Secure Enclave.
+- **P384** and **P521**, roughly 192-bit and 256-bit strength (NIST levels 3 and 5).
+  They mirror the P256 API. Pick them only because an external standard or auditor
+  insists.
+- **ML-KEM-768** (roughly AES-128 strength) and **ML-KEM-1024** (roughly AES-192).
+  Lattice KEM from FIPS 203. Secure Enclave capable on iOS 26+.
+- **ML-DSA-65** (roughly AES-128) and **ML-DSA-87** (roughly AES-192). Lattice
+  signatures from FIPS 204. Secure Enclave capable on iOS 26+.
+- **X-Wing** (`XWingMLKEM768X25519`). A hybrid of ML-KEM-768 and X25519; an attacker
+  must break both. Apple's recommended path for migrating custom protocols, used
+  through HPKE.
+
+| Need | Choose |
+| --- | --- |
+| Key must never leave hardware | `SecureEnclave.P256.*` |
+| Software signing or agreement | `Curve25519.*` |
+| FIPS or enterprise interop | `P256` or `P384` |
+| End-to-end encryption, iOS 17+ | HPKE `Curve25519_SHA256_ChachaPoly` |
+| End-to-end encryption resistant to harvest-now-decrypt-later, iOS 26+ | HPKE `XWingMLKEM768X25519_SHA256_AES_GCM_256` |
+| Highest classical level | `P521`, only if mandated |
+
+| Algorithm | Public key | Secure Enclave |
+| --- | --- | --- |
+| P256 | 64 B | yes |
+| P384 | 96 B | no |
+| P521 | 132 B | no |
+| Curve25519 | 32 B | no |
+| ML-KEM-768 | 1,184 B | yes (iOS 26) |
+| ML-KEM-1024 | 1,568 B | yes (iOS 26) |
+| ML-DSA-65 | 1,952 B | yes (iOS 26) |
+| ML-DSA-87 | 2,592 B | yes (iOS 26) |
+| X-Wing | 1,216 B | yes (iOS 26) |
+
+Speed is not a reason to prefer one of P256 and Curve25519 on Apple Silicon;
+corecrypto's NISTZ256 code makes the difference negligible.
+
+## Signing and key agreement are different types
+
+Each curve has two separate families, `Signing` and `KeyAgreement`, and the compiler
+will not let you mix them.
 
 ```swift
 import CryptoKit
+import Foundation
 
-// Generate a signing key pair
-let signingKey = P256.Signing.PrivateKey()
-let verifyingKey = signingKey.publicKey  // P256.Signing.PublicKey
-
-// Sign data (CryptoKit hashes internally with SHA-256)
-let message = Data("Transfer $100 to Alice".utf8)
-let signature = try signingKey.signature(for: message)
-// signature is P256.Signing.ECDSASignature
-
-// Verify
-let isValid = verifyingKey.isValidSignature(signature, for: message)
-
-// Signature serialization
-let derSig = signature.derRepresentation    // ASN.1 DER (interoperable)
-let rawSig = signature.rawRepresentation    // Raw r‖s concatenation (64 bytes)
-let restored = try P256.Signing.ECDSASignature(derRepresentation: derSig)
-```
-
-For pre-hashed data (when the digest is computed externally), use `signature(for:)` with a `Digest` parameter or the `SHA256Digest` directly.
-
-### ❌ Wrong: Mixing signing and key agreement key types
+let releaseSigner = P256.Signing.PrivateKey()
+let verifierKey: P256.Signing.PublicKey = releaseSigner.publicKey
 
-```swift
-// This will NOT compile  -  signing keys cannot do key agreement
-let key = P256.Signing.PrivateKey()
-let shared = try key.sharedSecretFromKeyAgreement(with: otherPublicKey)
-// Error: P256.Signing.PrivateKey has no member 'sharedSecretFromKeyAgreement'
+let artifact = Data("build 5120 checksum".utf8)
+let signature = try releaseSigner.signature(for: artifact)
 
-// Likewise, Curve25519.KeyAgreement.PrivateKey has no .signature(for:) method
+let valid = verifierKey.isValidSignature(signature, for: artifact)
+let asn1 = signature.derRepresentation
+let compact = signature.rawRepresentation
+let decoded = try P256.Signing.ECDSASignature(derRepresentation: asn1)
 ```
 
----
+`signature(for:)` hashes `Data` with SHA-256 internally and returns a
+`P256.Signing.ECDSASignature`. `derRepresentation` is the ASN.1 form most servers
+expect; `rawRepresentation` is the 64-byte r||s form. If you already have a digest,
+pass the `SHA256Digest` (any `Digest`) to `signature(for:)` instead.
 
-## Key Agreement with HKDF Derivation
+Calling `sharedSecretFromKeyAgreement` on a `P256.Signing.PrivateKey`, or
+`signature(for:)` on a `Curve25519.KeyAgreement.PrivateKey`, is a compile error.
+Generate one key per purpose.
 
-The `SharedSecret` produced by ECDH is not uniformly distributed and must never be used directly as an encryption key. CryptoKit enforces this  -  `SharedSecret` is not directly convertible to `SymmetricKey`. The only sanctioned paths are `.hkdfDerivedSymmetricKey()` or `.x963DerivedSymmetricKey()`. Apple's documentation states explicitly: "The shared secret isn't suitable as a symmetric cryptographic key by itself."
+## Key agreement always goes through a KDF
 
-### ✅ Correct: Curve25519 key agreement with HKDF derivation
+An ECDH `SharedSecret` is not uniformly random and cannot be turned into a
+`SymmetricKey` directly. Apple's documentation says it is not suitable as a key on
+its own; the two sanctioned routes are `hkdfDerivedSymmetricKey` and
+`x963DerivedSymmetricKey`.
 
 ```swift
-import CryptoKit
-
-// Both parties generate key agreement keys (NOT signing keys)
-let aliceKey = Curve25519.KeyAgreement.PrivateKey()
-let bobKey = Curve25519.KeyAgreement.PrivateKey()
+let deviceKey = Curve25519.KeyAgreement.PrivateKey()
+let serverKey = Curve25519.KeyAgreement.PrivateKey()
 
-// Alice computes shared secret using Bob's public key
-let sharedSecret = try aliceKey.sharedSecretFromKeyAgreement(
-    with: bobKey.publicKey
-)
-
-// CRITICAL: Derive a symmetric key via HKDF  -  never use SharedSecret directly
-let symmetricKey = sharedSecret.hkdfDerivedSymmetricKey(
+let secret = try deviceKey.sharedSecretFromKeyAgreement(with: serverKey.publicKey)
+let channelKey = secret.hkdfDerivedSymmetricKey(
     using: SHA256.self,
-    salt: Data("my-app-salt".utf8),
-    sharedInfo: Data("encryption-v1".utf8),
-    outputByteCount: 32  // 256-bit key for AES-256 or ChaChaPoly
+    salt: Data("pairing-2026".utf8),
+    sharedInfo: Data("telemetry-channel/v1/encrypt".utf8),
+    outputByteCount: 32
 )
-
-// Now use the derived key for authenticated encryption
-let sealed = try ChaChaPoly.seal(plaintext, using: symmetricKey)
+let packet = try ChaChaPoly.seal(Data("temp=21.5".utf8), using: channelKey)
 ```
 
-The `sharedInfo` parameter serves as protocol binding  -  it ensures keys derived for different purposes within the same application cannot be confused. Use distinct `sharedInfo` values for encryption keys vs authentication keys when deriving multiple subkeys.
-
-### ❌ Wrong: Using SharedSecret directly as an encryption key
+`sharedInfo` ties the key to your protocol and role. Derive separate keys with
+different `sharedInfo` for encryption and for authentication.
 
 ```swift
-// NEVER DO THIS  -  SharedSecret is not uniformly distributed
-let sharedSecret = try aliceKey.sharedSecretFromKeyAgreement(with: bobPublicKey)
-
-// SharedSecret is NOT a SymmetricKey and cannot be used as one directly.
-// Its byte distribution is non-uniform (only ~2^255 of 2^256 values are
-// valid P-256 x-coordinates). Skipping HKDF also prevents protocol binding
-// and removes the salt's entropy-concentration benefit.
-
-// This forced extraction is dangerous:
-let insecureKey = SymmetricKey(data: sharedSecret.withUnsafeBytes { Data($0) })
-// ⚠️ Non-uniform key material, no domain separation, no salt
+// Broken: raw secret bytes used as a key
+let bad = SymmetricKey(data: secret.withUnsafeBytes { Data($0) })
 ```
 
----
-
-## HPKE Simplifies Public-Key Encryption (iOS 17+)
-
-Before iOS 17, encrypting data for a recipient's public key required manually implementing ECIES: perform ECDH, derive a key via HKDF, encrypt with AES-GCM, and transmit the ephemeral public key alongside the ciphertext. HPKE (RFC 9180) packages this entire flow into a single API. CryptoKit supports all four RFC modes  -  Base, Auth, PSK, and AuthPSK  -  with five built-in cipher suites.
+This skips extraction over non-uniform material (on P-256 roughly half of all 256-bit strings can
+occur as an x-coordinate, so the bits are biased), and has no salt and no domain
+separation.
 
-### Built-in Cipher Suites
+## HPKE (iOS 17+)
 
-| Cipher Suite                              | KEM           | KDF         | AEAD              | Min iOS |
-| ----------------------------------------- | ------------- | ----------- | ----------------- | ------- |
-| `.Curve25519_SHA256_ChachaPoly`           | X25519        | HKDF-SHA256 | ChaCha20-Poly1305 | 17+     |
-| `.P256_SHA256_AES_GCM_256`                | P-256         | HKDF-SHA256 | AES-GCM-256       | 17+     |
-| `.P384_SHA384_AES_GCM_256`                | P-384         | HKDF-SHA384 | AES-GCM-256       | 17+     |
-| `.P521_SHA512_AES_GCM_256`                | P-521         | HKDF-SHA512 | AES-GCM-256       | 17+     |
-| `.XWingMLKEM768X25519_SHA256_AES_GCM_256` | X-Wing hybrid | HKDF-SHA256 | AES-GCM-256       | 26+     |
+Before iOS 17, encrypting to a public key meant building ECIES by hand: ECDH, HKDF,
+AES-GCM, and shipping the ephemeral public key alongside. HPKE (RFC 9180) packages
+that. Every mode the RFC defines is available (base, sender-authenticated, pre-shared key,
+and the combination of the last two), and five suites come predefined:
 
-Custom suites can be constructed: `HPKE.Ciphersuite(kem: .P521_HKDF_SHA512, kdf: .HKDF_SHA512, aead: .AES_GCM_256)`.
+| Suite name | KEM | KDF | AEAD | Since |
+| --- | --- | --- | --- | --- |
+| `.Curve25519_SHA256_ChachaPoly` | X25519 | SHA-256 HKDF | ChaCha20 with Poly1305 | 17 |
+| `.P256_SHA256_AES_GCM_256` | NIST P-256 | SHA-256 HKDF | AES-GCM, 256-bit key | 17 |
+| `.P384_SHA384_AES_GCM_256` | NIST P-384 | SHA-384 HKDF | AES-GCM, 256-bit key | 17 |
+| `.P521_SHA512_AES_GCM_256` | NIST P-521 | SHA-512 HKDF | AES-GCM, 256-bit key | 17 |
+| `.XWingMLKEM768X25519_SHA256_AES_GCM_256` | X-Wing hybrid | SHA-256 HKDF | AES-GCM, 256-bit key | 26 |
 
-### ✅ Correct: HPKE encryption and decryption
+Other combinations are built with `HPKE.Ciphersuite(kem:kdf:aead:)`, for example a
+P-384 KEM with the SHA-384 KDF and ChaChaPoly:
+`HPKE.Ciphersuite(kem: .P384_HKDF_SHA384, kdf: .HKDF_SHA384, aead: .chaChaPoly)`.
 
 ```swift
-import CryptoKit
-
-let ciphersuite = HPKE.Ciphersuite.Curve25519_SHA256_ChachaPoly
-let info = Data("MyApp-FileEncryption-v1".utf8)
-
-// Recipient generates a key pair and shares the public key
-let recipientPrivateKey = Curve25519.KeyAgreement.PrivateKey()
-let recipientPublicKey = recipientPrivateKey.publicKey
+@available(iOS 17.0, macOS 14.0, *)
+func exchangeMedicalNote() throws -> Data {
+    let suite = HPKE.Ciphersuite.Curve25519_SHA256_ChachaPoly
+    let clinicKey = Curve25519.KeyAgreement.PrivateKey()
+    let context = Data("clinic-inbox/v3".utf8)
+    let header = Data("patient=5521".utf8)
+
+    var outbound = try HPKE.Sender(
+        recipientKey: clinicKey.publicKey, ciphersuite: suite, info: context
+    )
+    let ciphertext = try outbound.seal(Data("allergy: penicillin".utf8), authenticating: header)
+    let encapsulated = outbound.encapsulatedKey
 
-// === SENDER ===
-// 'var' is required  -  seal() mutates internal nonce state
-var sender = try HPKE.Sender(
-    recipientKey: recipientPublicKey,
-    ciphersuite: ciphersuite,
-    info: info
-)
-let ciphertext = try sender.seal(
-    Data("Confidential document".utf8),
-    authenticating: Data("metadata".utf8)  // optional AAD
-)
-let encapsulatedKey = sender.encapsulatedKey  // MUST be sent with ciphertext
-
-// === RECIPIENT ===
-var recipient = try HPKE.Recipient(
-    privateKey: recipientPrivateKey,
-    ciphersuite: ciphersuite,
-    info: info,
-    encapsulatedKey: encapsulatedKey  // from sender
-)
-let plaintext = try recipient.open(
-    ciphertext,
-    authenticating: Data("metadata".utf8)  // same AAD
-)
+    var inbound = try HPKE.Recipient(
+        privateKey: clinicKey, ciphersuite: suite, info: context,
+        encapsulatedKey: encapsulated
+    )
+    return try inbound.open(ciphertext, authenticating: header)
+}
 ```
 
-### Three Critical HPKE Details AI Generators Get Wrong
-
-1. **The encapsulated key is not embedded in the ciphertext.** Your protocol must transmit `encapsulatedKey` alongside the ciphertext. Losing it means permanent decryption failure.
-
-2. **`HPKE.Sender` and `HPKE.Recipient` are stateful structs that must be declared with `var`** because `seal()` and `open()` are mutating methods  -  they increment an internal nonce counter. Using `let` causes a compiler error.
+Three things break HPKE code:
 
-3. **Message ordering matters.** If the sender seals messages A then B, the recipient must open A before B. The internal counter must stay synchronized.
+1. `encapsulatedKey` is not part of the ciphertext. You must send it with the
+   message. Without it nothing can be decrypted, ever.
+2. `Sender` and `Recipient` are structs with state (an internal nonce counter), and
+   `seal` / `open` are `mutating`. Declaring them with `let` does not compile.
+3. Messages must be opened in the order they were sealed; out-of-order opens fail
+   because the counters disagree.
 
----
+## Post-quantum cryptography (iOS 26+)
 
-## Post-Quantum Cryptography (iOS 26+)
+The threat is harvest now, decrypt later: traffic recorded today is decrypted once
+a large quantum computer exists. From iOS 26, `URLSession` and Network.framework
+offer the hybrid `X25519MLKEM768` group in the TLS ClientHello by default.
 
-At WWDC 2025 (session 314, "Get ahead with quantum-secure cryptography"), Apple announced CryptoKit support for NIST's post-quantum standards. The threat model is "harvest now, decrypt later"  -  adversaries storing encrypted traffic today to decrypt once cryptographically relevant quantum computers exist. iOS 26 enables quantum-secure TLS by default for `URLSession` and `Network.framework`, advertising `X25519MLKEM768` in the TLS ClientHello.
+CryptoKit adds five types, formally verified against the FIPS specifications, all
+usable in the Secure Enclave:
 
-Five new types join CryptoKit, all backed by formally verified implementations proven functionally equivalent to their FIPS specifications:
+| Type | Public key | Output |
+| --- | --- | --- |
+| `MLKEM768` | 1,184 B | ciphertext 1,088 B |
+| `MLKEM1024` | 1,568 B | |
+| `XWingMLKEM768X25519` (draft-connolly-cfrg-xwing-kem) | 1,216 B | encapsulation 1,120 B |
+| `MLDSA65` | 1,952 B | signature 3,309 B |
+| `MLDSA87` | 2,592 B | signature 4,627 B |
 
-| Type                  | Algorithm     | Standard                      | Operation          | Secure Enclave | Key/Sig Size                     |
-| --------------------- | ------------- | ----------------------------- | ------------------ | -------------- | -------------------------------- |
-| `MLKEM768`            | ML-KEM-768    | FIPS 203                      | Key encapsulation  | ✅             | 1,184 B pub / 1,088 B ciphertext |
-| `MLKEM1024`           | ML-KEM-1024   | FIPS 203                      | Key encapsulation  | ✅             | 1,568 B pub                      |
-| `XWingMLKEM768X25519` | X-Wing hybrid | draft-connolly-cfrg-xwing-kem | Key encapsulation  | ✅             | 1,216 B pub / 1,120 B encap      |
-| `MLDSA65`             | ML-DSA-65     | FIPS 204                      | Digital signatures | ✅             | 1,952 B pub / 3,309 B sig        |
-| `MLDSA87`             | ML-DSA-87     | FIPS 204                      | Digital signatures | ✅             | 2,592 B pub / 4,627 B sig        |
+What you pay is bytes on the wire, not CPU. Compare 3,309 bytes per ML-DSA-65
+signature with 64 per Ed25519 signature, and 1,184 bytes of ML-KEM-768 public key
+with 32 for X25519. Timing is in the same range as the classical algorithms.
 
-The size cost of quantum resistance is substantial  -  an ML-DSA-65 signature is 3,309 bytes versus 64 bytes for Ed25519; an ML-KEM-768 public key is 1,184 bytes versus 32 bytes for X25519. But computational performance is competitive with classical algorithms.
-
-### ✅ Correct: ML-KEM-768 key encapsulation
-
-Key encapsulation differs fundamentally from Diffie-Hellman key agreement. In ECDH, both parties contribute public keys. In KEM, only the recipient has a key pair  -  the sender calls `encapsulate()` on the public key, which produces both a shared secret and an opaque ciphertext that only the private key can decapsulate.
+Encapsulation works differently from Diffie-Hellman: the sending side has no key
+pair at all. It runs `encapsulate()` against the receiver's public key, which yields
+both the shared secret and a ciphertext that has to travel to the receiver.
 
 ```swift
-import CryptoKit
-
-if #available(iOS 26, macOS 26, *) {
-    // Recipient generates a key pair
-    let privateKey = try MLKEM768.PrivateKey()
-    let publicKey = privateKey.publicKey
-
-    // Sender encapsulates (only needs recipient's public key)
-    let encapsulation = try publicKey.encapsulate()
-    let senderSharedSecret = encapsulation.sharedSecret     // 32 bytes
-    let encapsulatedCiphertext = encapsulation.encapsulated  // 1,088 bytes
-
-    // Recipient decapsulates
-    let recipientSharedSecret = try privateKey.decapsulate(encapsulatedCiphertext)
-
-    // senderSharedSecret == recipientSharedSecret
-    // Derive a symmetric key via HKDF, as with ECDH
+@available(iOS 26, macOS 26, *)
+func quantumSafeSession() throws -> SymmetricKey {
+    let receiver = try MLKEM768.PrivateKey()
+
+    let result = try receiver.publicKey.encapsulate()
+    let sentOverWire = result.encapsulated          // 1,088 bytes
+    // result.sharedSecret (32 bytes) stays with the sender
+
+    let receiverSecret = try receiver.decapsulate(sentOverWire)
+    return HKDF<SHA256>.deriveKey(
+        inputKeyMaterial: receiverSecret, info: Data("kem-session".utf8),
+        outputByteCount: 32
+    )
 }
-```
 
-### ✅ Correct: ML-DSA-65 signing
-
-```swift
-if #available(iOS 26, macOS 26, *) {
-    let signingKey = try MLDSA65.PrivateKey()
-    let verifyingKey = signingKey.publicKey  // 1,952 bytes
-
-    let message = Data("Authenticate this payload".utf8)
-    let signature = try signingKey.signature(for: message)  // 3,309 bytes
-
-    let isValid = verifyingKey.isValidSignature(
-        signature,
-        for: message
-    )
+@available(iOS 26, macOS 26, *)
+func signFirmware(_ image: Data) throws -> Bool {
+    let authority = try MLDSA65.PrivateKey()
+    let sig = try authority.signature(for: image)    // 3,309 bytes
+    return authority.publicKey.isValidSignature(sig, for: image)
 }
 ```
 
-### ✅ Correct: Hybrid post-quantum with HPKE (recommended migration path)
+Both sides end up with the same 32-byte `SymmetricKey`. As with ECDH, derive the
+working key from it with HKDF and a protocol label rather than using it directly.
 
-Apple's recommended approach for custom protocols is to switch the HPKE cipher suite to X-Wing, which combines ML-KEM-768 with X25519 so that both algorithms must be broken to compromise the exchange:
+Hybrid key exchange through HPKE is the migration Apple recommends: the classical
+code above changes only in suite and key type. The encapsulated key grows from
+about 32 bytes to 1,120.
 
 ```swift
-if #available(iOS 26, macOS 26, *) {
-    // Quantum-secure HPKE
-    let ciphersuite = HPKE.Ciphersuite.XWingMLKEM768X25519_SHA256_AES_GCM_256
-    let privateKey = try XWingMLKEM768X25519.PrivateKey()
-
+@available(iOS 26, macOS 26, *)
+func hybridSeal(_ message: Data) throws -> (Data, Data) {
+    let suite = HPKE.Ciphersuite.XWingMLKEM768X25519_SHA256_AES_GCM_256
+    let mailboxKey = try XWingMLKEM768X25519.PrivateKey()
     var sender = try HPKE.Sender(
-        recipientKey: privateKey.publicKey,  // 1,216 bytes
-        ciphersuite: ciphersuite,
-        info: Data("quantum-secure-v1".utf8)
+        recipientKey: mailboxKey.publicKey, ciphersuite: suite, info: Data("mailbox".utf8)
     )
-    let ciphertext = try sender.seal(sensitiveData)
-    // encapsulatedKey is 1,120 bytes (vs ~32 bytes for classical X25519)
+    let sealed = try sender.seal(message)
+    return (sender.encapsulatedKey, sealed)
 }
 ```
 
-### ✅ Correct: Hybrid signing (ML-DSA + ECDSA) for transition period
-
-For signatures, Apple demonstrates hybrid signatures at the application level  -  concatenating ML-DSA and ECDSA signatures and verifying both:
+Hybrid signatures follow the same idea: sign with both `MLDSA65` and `P256.Signing`,
+ship both, and accept only if both verify.
 
 ```swift
-if #available(iOS 26, macOS 26, *) {
-    let pqKey = try MLDSA65.PrivateKey()
-    let ecKey = P256.Signing.PrivateKey()
-
-    let pqSig = try pqKey.signature(for: message)
-    let ecSig = try ecKey.signature(for: message).rawRepresentation
-    let hybridSignature = pqSig + ecSig  // Concatenate both
-
-    // Verify both  -  reject if either fails
-    let pqValid = pqKey.publicKey.isValidSignature(pqSig, for: message)
-    let ecValid = ecKey.publicKey.isValidSignature(
-        try P256.Signing.ECDSASignature(rawRepresentation: ecSig), for: message
-    )
-    let isValid = pqValid && ecValid
+@available(iOS 26, macOS 26, *)
+struct DualSignature {
+    let pq: Data
+    let classical: Data
+
+    static func make(for body: Data, pqKey: MLDSA65.PrivateKey,
+                     ecKey: P256.Signing.PrivateKey) throws -> DualSignature {
+        DualSignature(
+            pq: try pqKey.signature(for: body),
+            classical: try ecKey.signature(for: body).rawRepresentation
+        )
+    }
+
+    func verify(_ body: Data, pqKey: MLDSA65.PublicKey,
+                ecKey: P256.Signing.PublicKey) -> Bool {
+        guard let ecSig = try? P256.Signing.ECDSASignature(rawRepresentation: classical) else {
+            return false
+        }
+        return pqKey.isValidSignature(pq, for: body) && ecKey.isValidSignature(ecSig, for: body)
+    }
 }
 ```
 
----
-
-## PEM and DER Interoperability (iOS 14+)
-
-CryptoKit's PEM support uses PKCS#8 for private keys (`-----BEGIN PRIVATE KEY-----`) and X.509 SubjectPublicKeyInfo for public keys (`-----BEGIN PUBLIC KEY-----`). Import also accepts SEC 1 format (`-----BEGIN EC PRIVATE KEY-----`). This enables interoperability with OpenSSL, BoringSSL, and server-side TLS libraries.
+## PEM and DER (iOS 14+)
 
-### ✅ Correct: PEM key export and import
+PEM private keys are PKCS#8 (`BEGIN PRIVATE KEY`); PEM public keys are X.509
+SubjectPublicKeyInfo (`BEGIN PUBLIC KEY`). Import also accepts SEC 1
+(`BEGIN EC PRIVATE KEY`). These interoperate with OpenSSL, BoringSSL and typical
+server TLS stacks.
 
 ```swift
-// Generate and export
-let privateKey = P256.Signing.PrivateKey()
-let privatePEM = privateKey.pemRepresentation   // PKCS#8 PEM string
-let publicPEM = privateKey.publicKey.pemRepresentation  // X.509 SPKI PEM string
-let publicDER = privateKey.publicKey.derRepresentation  // Binary DER Data
-
-// Import from PEM (works for P256, P384, P521  -  NOT Curve25519)
-let imported = try P256.Signing.PrivateKey(pemRepresentation: privatePEM)
-let importedPub = try P256.Signing.PublicKey(derRepresentation: publicDER)
-```
+let tokenSigner = P384.Signing.PrivateKey()
+let privatePEM = tokenSigner.pemRepresentation
+let publicPEM = tokenSigner.publicKey.pemRepresentation
+let publicDER = tokenSigner.publicKey.derRepresentation
 
-### Key Format Reference
+let restoredSigner = try P384.Signing.PrivateKey(pemRepresentation: privatePEM)
+let restoredVerifier = try P384.Signing.PublicKey(derRepresentation: publicDER)
+```
 
-| Algorithm             | Public Key Format       | Private Key Format            | Notes                       |
-| --------------------- | ----------------------- | ----------------------------- | --------------------------- |
-| P-256 / P-384 / P-521 | SPKI DER/PEM, x963, raw | PKCS#8 DER/PEM, x963, raw     | Full interop from iOS 14+   |
-| Curve25519            | Raw 32 bytes only       | Raw 32 bytes only             | No PEM/DER/x963 support     |
-| Secure Enclave P256   | Standard SPKI DER/PEM   | Encrypted blob (device-bound) | Public key exports normally |
-| ML-KEM / ML-DSA       | Raw representation      | Raw representation            | iOS 26+                     |
+| Key | Public formats | Private formats |
+| --- | --- | --- |
+| P256 / P384 / P521 (iOS 14+) | SPKI DER and PEM, x963, raw | PKCS#8 DER and PEM, x963, raw |
+| Curve25519 | raw 32 bytes only | raw 32 bytes only |
+| Secure Enclave P256 | SPKI as usual | `dataRepresentation`: an encrypted blob bound to this device |
+| ML-KEM / ML-DSA (iOS 26+) | raw | raw |
 
-**Curve25519 keys do not support PEM/DER.** They only have `rawRepresentation` (32 bytes for both public and private). If you need to exchange Curve25519 keys with external systems, handle raw byte serialization yourself or wrap the raw bytes in a custom format.
+PEM and DER apply to the NIST curves only. Exchanging Curve25519 keys with another
+system means agreeing on raw 32-byte encoding yourself.
 
-### Keychain Storage of CryptoKit Keys
+### Storing keys in the Keychain
 
-NIST curve keys (P-256/P-384/P-521) can be stored as `kSecClassKey` items in the keychain via their `SecKey` bridge. Curve25519 keys and Secure Enclave key blobs must be stored as `kSecClassGenericPassword` items using their `rawRepresentation` / `dataRepresentation`. Apple recommends implementing a `GenericPasswordConvertible` protocol for standardized conversion  -  see `credential-storage-patterns.md` for the full pattern.
+- NIST private keys go in as `kSecClassKey` by converting to `SecKey`.
+- Curve25519 keys, post-quantum keys and Secure Enclave blobs go in as
+  `kSecClassGenericPassword`, using `rawRepresentation` or `dataRepresentation`.
+  Apple's sample code wraps this in a `GenericPasswordConvertible` protocol (see
+  [credential-storage-patterns.md](credential-storage-patterns.md), which also shows
+  the add-then-update-on-duplicate save).
 
-**Peer / recipient public keys** received from a server or counterpart (for ECDH, HPKE, or signature verification) must also be persisted in the keychain  -  never in UserDefaults, plain files, or hardcoded in source. For NIST curves, store them as `kSecClassKey` with `kSecAttrKeyClass: kSecAttrKeyClassPublic`. For Curve25519 and post-quantum public keys, store the `rawRepresentation` as a `kSecClassGenericPassword` item. Use `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` for accessibility, and assign a distinct `kSecAttrApplicationTag` or `kSecAttrAccount` value (e.g., a `"peer-"` prefix) to separate received peer keys from your own key pairs. See `credential-storage-patterns.md` for the add-or-update pattern.
+Public keys of peers and recipients also need to be stored safely, because swapping
+one lets an attacker impersonate the peer. Keep them in the Keychain, never in
+UserDefaults, files or source:
 
----
+- NIST public keys as `kSecClassKey` with `kSecAttrKeyClass: kSecAttrKeyClassPublic`.
+- Curve25519 and post-quantum public keys as raw bytes in a generic password item.
+- Accessibility `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`.
+- A distinct tag or account name, for example a `peer-` prefix, so they never
+  collide with your own keys.
 
-## Secure Enclave Integration (Brief  -  See `secure-enclave.md`)
+## The Secure Enclave, briefly
 
-The Secure Enclave generates, stores, and operates on private keys entirely within its hardware boundary  -  raw key material never enters application memory.
+Full coverage is in [secure-enclave.md](secure-enclave.md). A signing key there needs
+`.privateKeyUsage` in its access control flags; without it key creation fails.
+`SecureEnclave.isAvailable` is false in the Simulator, so guard it and test the
+hardware path on a device.
 
 ```swift
-guard SecureEnclave.isAvailable else { return }
-
-let accessControl = SecAccessControlCreateWithFlags(
-    nil,
-    kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
-    .biometryCurrentSet,
-    nil
-)!
-
-// Signing key with biometric protection
-let seKey = try SecureEnclave.P256.Signing.PrivateKey(
-    accessControl: accessControl
-)
-let signature = try seKey.signature(for: data)
-
-// The public key is a standard P256.Signing.PublicKey  -  exports normally
-let publicPEM = seKey.publicKey.pemRepresentation
-```
-
-For classical curves, only P256 works with the Secure Enclave. On iOS 26, the Secure Enclave gains support for `SecureEnclave.MLKEM768`, `SecureEnclave.MLKEM1024`, `SecureEnclave.MLDSA65`, and `SecureEnclave.MLDSA87`.
-
-**Critical lifecycle constraint:** Secure Enclave keys are non-exportable and cryptographically bound to the specific device and OS installation. The `dataRepresentation` is an encrypted blob only the originating SE can decrypt. After iCloud backup restore to a new device, SE keys are irrecoverable. Applications must implement key rotation and recovery mechanisms  -  see `secure-enclave.md` for the full lifecycle pattern.
-
----
-
-## Stop Using RSA for New Apple Development
+enum HardwareKeyError: Error {
+    case enclaveUnavailable
+    case accessControlRejected
+}
 
-CryptoKit does not include RSA at all. RSA requires dropping down to the Security framework's C-based `SecKey` API, which lacks type safety, automatic memory management, and modern Swift ergonomics.
+func makeHardwareSigner() throws -> (SecureEnclave.P256.Signing.PrivateKey, String) {
+    guard SecureEnclave.isAvailable else { throw HardwareKeyError.enclaveUnavailable }
 
-### ❌ Wrong: RSA when EC is available
+    guard let policy = SecAccessControlCreateWithFlags(
+        nil,
+        kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
+        [.privateKeyUsage, .biometryCurrentSet],
+        nil
+    ) else {
+        throw HardwareKeyError.accessControlRejected
+    }
 
-```swift
-// Don't do this for new code  -  Security framework RSA
-let params: [String: Any] = [
-    kSecAttrKeyType as String: kSecAttrKeyTypeRSA,
-    kSecAttrKeySizeInBits as String: 2048
-]
-var error: Unmanaged<CFError>?
-let key = SecKeyCreateRandomKey(params as CFDictionary, &error)
-// No type safety, manual memory management, 256-byte keys, no Secure Enclave
+    let key = try SecureEnclave.P256.Signing.PrivateKey(accessControl: policy)
+    return (key, key.publicKey.pemRepresentation)
+}
 ```
 
-### Preferred replacement: P256 signing in CryptoKit
+iOS 26 adds `SecureEnclave.MLKEM768`, `SecureEnclave.MLKEM1024`,
+`SecureEnclave.MLDSA65` and `SecureEnclave.MLDSA87`.
 
-```swift
-// ✅ CORRECT for new Apple-platform code
-let signingKey = P256.Signing.PrivateKey()
-let message = Data("message".utf8)
-let signature = try signingKey.signature(for: message)
-let isValid = signingKey.publicKey.isValidSignature(signature, for: message)
-```
+A Secure Enclave key belongs to one physical device and one installation of its OS. The blob can
+only be unwrapped by the enclave that created it, so an iCloud restore to a new
+device loses the key. Plan rotation and recovery (re-enrol a new public key with
+your server) from the start.
 
-RSA-2048 provides only ~112-bit security with 256-byte keys and signatures. P256 achieves ~128-bit security with 32-byte private keys and 64-byte signatures  -  an 8× reduction in signature size with stronger security. Valid reasons to still use RSA: legacy server interoperability, X.509 certificates from CAs that mandate RSA, and JWT specifications locked to RS256.
+## RSA
 
----
+CryptoKit does not implement RSA. RSA means the Security framework's `SecKey` C API
+with no type safety and manual memory handling, for example
+`SecKeyCreateRandomKey` with `kSecAttrKeyTypeRSA` and 2048 bits. Do not start new
+designs there.
 
-## Common AI-Generator Mistakes
+An RSA-2048 key is rated near 112 bits, and both its modulus and each signature take
+256 bytes. P-256 gives
+about 128 bits with a 32-byte private key and 64-byte signatures, 8x smaller.
 
-| Anti-Pattern                                       | Risk                                           | Fix                                                                    |
-| -------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------- |
-| Using `SharedSecret` directly as encryption key    | Non-uniform key material; no domain separation | Always derive via `hkdfDerivedSymmetricKey()` with salt and sharedInfo |
-| Mixing `Signing` and `KeyAgreement` key types      | Compile error; conceptual misuse               | Use the correct type hierarchy for each operation                      |
-| Missing HPKE `encapsulatedKey` in protocol         | Ciphertext permanently undecryptable           | Serialize and transmit `encapsulatedKey` alongside ciphertext          |
-| Declaring `HPKE.Sender`/`Recipient` with `let`     | Compile error (`seal()`/`open()` are mutating) | Declare with `var`                                                     |
-| Using RSA for new iOS code                         | Slower, larger keys, no CryptoKit/SE support   | Default to ECC (P-256 or Curve25519)                                   |
-| Recommending Curve25519 for Secure Enclave         | Curve25519 has no SE support                   | Use `SecureEnclave.P256` for hardware-backed keys                      |
-| Ignoring PEM/DER format limitations for Curve25519 | Runtime crash on `.pemRepresentation` access   | Use `.rawRepresentation` for Curve25519; PEM/DER for NIST curves only  |
-| Using HPKE messages out of order                   | Decryption failure (nonce counter mismatch)    | Open messages in the same order they were sealed                       |
+RSA is still justified for interop with a legacy server, when a CA mandates RSA
+X.509 certificates, or when a JWT profile is fixed to RS256.
 
----
+## Frequent mistakes
 
-## iOS Version Requirements
+| Mistake | Correction |
+| --- | --- |
+| Using a raw `SharedSecret` as a key | `hkdfDerivedSymmetricKey()` with salt and `sharedInfo` |
+| Mixing `Signing` and `KeyAgreement` types | Compile error; generate a key of the right family |
+| Not transmitting `encapsulatedKey` | The message can never be opened; send it |
+| `let` for an HPKE `Sender` / `Recipient` | Compile error; use `var` |
+| RSA in new code | P-256 or Curve25519 |
+| Curve25519 for a Secure Enclave key | `SecureEnclave.P256` |
+| Calling `.pemRepresentation` on a Curve25519 key | Not available; use `.rawRepresentation` |
+| Opening HPKE messages out of order | Counter mismatch, open fails; keep order |
 
-| Feature                                                | Minimum iOS | Key Notes                      |
-| ------------------------------------------------------ | ----------- | ------------------------------ |
-| CryptoKit core (P256, P384, P521, Curve25519, SE P256) | 13.0+       | All classical curves           |
-| PEM/DER import/export, standalone HKDF                 | 14.0+       | NIST curves only               |
-| HPKE (RFC 9180, all four modes)                        | 17.0+       | All key agreement types        |
-| ML-KEM, ML-DSA, X-Wing, quantum-secure TLS             | 26.0+       | Post-quantum types, SE support |
+## Availability
 
-Always gate post-quantum and HPKE code behind `#available` checks:
+| Release | Adds |
+| --- | --- |
+| iOS 13 | CryptoKit: P256, P384, P521, Curve25519, Secure Enclave P256 |
+| iOS 14 | PEM/DER import and export (NIST curves), standalone HKDF |
+| iOS 17 | HPKE in all four modes |
+| iOS 26 | ML-KEM, ML-DSA, X-Wing, quantum-secure TLS |
 
 ```swift
-if #available(iOS 26, macOS 26, *) {
-    // Post-quantum code path
-} else if #available(iOS 17, macOS 14, *) {
-    // Classical HPKE code path
-} else {
-    // Manual ECIES fallback
+func sealForRecipient(_ body: Data) throws {
+    if #available(iOS 26, macOS 26, *) {
+        // X-Wing HPKE path
+    } else if #available(iOS 17, macOS 14, *) {
+        // Classical HPKE path
+    } else {
+        // Hand-built ECIES: X25519 + HKDF + AES-GCM, ship the ephemeral public key
+    }
 }
 ```
 
----
-
-## Performance and Thread Safety
-
-CryptoKit operations are CPU-bound and safe to call from any thread  -  the framework uses no internal locks or shared mutable state. However, key generation (especially Secure Enclave keys with biometric gates) can block for user interaction. Never run SE key operations on `@MainActor`. Use a dedicated actor or `Task.detached` for key generation and signing that may trigger biometric prompts.
-
-For bulk operations, P256 signing and verification benefit from Apple Silicon's hardware crypto acceleration. Curve25519 operations are slightly faster in raw computational benchmarks on non-Apple platforms, but Apple's NISTZ256 optimization makes the difference negligible on A-series and M-series chips.
-
-Post-quantum operations are computationally competitive with classical algorithms per Apple's WWDC 2025 presentation, but produce significantly larger outputs. Plan for the bandwidth and storage impact of 3,309-byte ML-DSA signatures and 1,184-byte ML-KEM public keys.
-
----
-
-## WWDC Sessions and Documentation References
-
-- **WWDC 2019, Session 709**  -  "Cryptography and Your Apps"  -  CryptoKit introduction, curve selection, key management
-- **WWDC 2020**  -  "What's New in CryptoKit"  -  PEM/DER support, HKDF standalone API
-- **WWDC 2025, Session 314**  -  "Get ahead with quantum-secure cryptography"  -  ML-KEM, ML-DSA, X-Wing, formally verified implementations, quantum-secure TLS
-- [Apple CryptoKit Documentation](https://sosumi.ai/documentation/cryptokit/)
-- [SharedSecret Documentation](https://sosumi.ai/documentation/cryptokit/sharedsecret)  -  HKDF derivation requirement
-- [HPKE Documentation](https://sosumi.ai/documentation/cryptokit/hpke)  -  Sender/Recipient API
-- [Storing CryptoKit Keys in the Keychain](https://sosumi.ai/documentation/cryptokit/storing-cryptokit-keys-in-the-keychain)  -  GenericPasswordConvertible pattern
-- [Protecting Keys with the Secure Enclave](https://sosumi.ai/documentation/security/protecting-keys-with-the-secure-enclave)
-- [Quantum-Secure Cryptography in Apple Operating Systems](https://support.apple.com/guide/security/quantum-secure-cryptography-apple-devices-secc7c82e533/web)
-
----
-
-## Conclusion
-
-CryptoKit's type system is its greatest feature  -  it prevents at compile time the most dangerous cryptographic mistakes that plague hand-rolled implementations. The framework evolved from four curve families in iOS 13 to a complete quantum-safe toolkit in iOS 26, with HPKE in iOS 17 serving as the critical bridge.
-
-For new development today: default to Curve25519 for software keys and P256 for Secure Enclave keys. Use HPKE instead of manual ECIES for public-key encryption. Always derive symmetric keys from `SharedSecret` through HKDF with protocol-specific `sharedInfo`. The post-quantum migration is deliberately simple  -  swap the HPKE cipher suite to `XWingMLKEM768X25519_SHA256_AES_GCM_256` and change the key type. Start inventorying custom protocols now: the harvest-now-decrypt-later window is already open.
-
----
-
-## Summary Checklist
-
-1. **Curve selection matches requirements**  -  P256 for Secure Enclave / NIST compliance; Curve25519 for software-only modern protocols; P384/P521 only when mandated by specification
-1. **Signing and key agreement use correct type families**  -  `*.Signing.PrivateKey` for signatures, `*.KeyAgreement.PrivateKey` for ECDH; never attempt to cross-use
-1. **SharedSecret is always derived through HKDF**  -  call `hkdfDerivedSymmetricKey(using:salt:sharedInfo:outputByteCount:)` with protocol-specific `sharedInfo`; never use raw shared secret bytes as a key
-1. **HPKE encapsulated key is transmitted with ciphertext**  -  `sender.encapsulatedKey` is not embedded in the ciphertext; protocol must serialize both
-1. **HPKE Sender/Recipient declared with `var`**  -  `seal()` and `open()` are mutating methods; `let` causes a compiler error
-1. **HPKE messages opened in seal order**  -  internal nonce counter must stay synchronized between sender and recipient
-1. **PEM/DER used only for NIST curves**  -  Curve25519 supports `rawRepresentation` only; attempting PEM/DER access will fail
-1. **RSA avoided for new code**  -  use CryptoKit ECC; RSA only for legacy interop via Security framework `SecKey` API
-1. **Post-quantum code gated behind `#available(iOS 26, *)`**  -  ML-KEM, ML-DSA, X-Wing require iOS 26+; HPKE requires iOS 17+
-1. **Secure Enclave key lifecycle accounts for device migration**  -  SE keys are device-bound; implement rotation/recovery for backup restore scenarios
-1. **Hybrid PQC strategy planned**  -  X-Wing HPKE for key exchange, ML-DSA + ECDSA dual signatures for signing during the transition period
-1. **Peer/recipient public keys stored in keychain**  -  received public keys for ECDH, HPKE, or verification persisted in keychain with `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` and distinct tags; not in UserDefaults or files
+## Performance and threads
+
+Calls into CryptoKit only burn CPU and may run on any thread concurrently; the
+library keeps no shared mutable state and takes no locks. Secure Enclave key creation and signing behind biometrics
+can wait on the user, so never run them on `@MainActor`; use an actor or a detached
+task. Size network payloads and stored records for post-quantum material, which is one
+to two orders of magnitude larger than classical keys and signatures.
+
+## Sources
+
+WWDC 2019 session 709; WWDC 2020 "What's New in CryptoKit"; WWDC 2025 session 314;
+Apple documentation for CryptoKit, `SharedSecret` and `HPKE`; "Storing CryptoKit Keys
+in the Keychain"; "Protecting Keys with the Secure Enclave"; Apple's
+"Quantum-Secure Cryptography in Apple Operating Systems".
+
+See also [cryptokit-symmetric.md](cryptokit-symmetric.md) for the AEAD and KDF
+details used above.
+
+## Summary
+
+Curve25519 for software keys, P256 for the Secure Enclave. HPKE instead of
+hand-rolled ECIES. Every shared secret through HKDF with a protocol-specific
+`sharedInfo`. Post-quantum migration is mostly swapping the HPKE suite to X-Wing and
+changing the key type, so start listing your custom protocols now.
+
+## Checklist
+
+- [ ] Curve fits the requirement: P256 for the Secure Enclave or NIST interop,
+      Curve25519 for software, P384/P521 only when mandated.
+- [ ] Correct `Signing` versus `KeyAgreement` family.
+- [ ] Every `SharedSecret` goes through
+      `hkdfDerivedSymmetricKey(using:salt:sharedInfo:outputByteCount:)`.
+- [ ] HPKE `encapsulatedKey` is transmitted.
+- [ ] Both HPKE context structs are mutable variables.
+- [ ] The receiver opens HPKE messages in the order the sender produced them.
+- [ ] PEM or DER encoding appears only with P256, P384 and P521 keys.
+- [ ] No RSA except legacy interop through `SecKey`.
+- [ ] Post-quantum code behind `#available(iOS 26, *)`; HPKE behind iOS 17.
+- [ ] Secure Enclave signing keys include `.privateKeyUsage`.
+- [ ] Secure Enclave key lifecycle covers moving to a new device.
+- [ ] Hybrid plan: X-Wing suite for encryption to a recipient, and every signature
+      produced twice, once with ML-DSA and once with ECDSA.
+- [ ] Peer public keys in the Keychain, AfterFirstUnlockThisDeviceOnly, distinct tags.