@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/cryptokit/references/cryptokit-patterns.md

@@ -1,602 +1,413 @@
-# CryptoKit Extended Patterns
+# CryptoKit patterns
 
-Advanced patterns, key serialization, Keychain integration, legacy
-interop, and additional CryptoKit features beyond the core SKILL.md.
+Detail that sits behind the main skill: how keys are serialized and stored,
+less common primitives, sizes, compliance and migration.
 
 ## Contents
 
-- [Key Serialization](#key-serialization)
-- [Keychain Storage](#keychain-storage)
-- [AES Key Wrapping](#aes-key-wrapping)
-- [HKDF Key Derivation](#hkdf-key-derivation)
-- [HPKE (Hybrid Public Key Encryption)](#hpke-hybrid-public-key-encryption)
-- [Post-Quantum APIs](#post-quantum-apis)
-- [Insecure Module](#insecure-module)
-- [SealedBox Anatomy](#sealedbox-anatomy)
-- [Signing with Digest](#signing-with-digest)
-- [Encryption Export Compliance](#encryption-export-compliance)
-- [Performance Considerations](#performance-considerations)
-- [CommonCrypto Migration](#commoncrypto-migration)
-
-## Key Serialization
-
-NIST curve keys (P256, P384, P521) support multiple serialization formats.
-Curve25519 keys use raw representation only.
-
-### NIST key export and import
-
-```swift
-let privateKey = P256.Signing.PrivateKey()
-
-// DER (binary, compact)
-let der = privateKey.derRepresentation
-let fromDER = try P256.Signing.PrivateKey(derRepresentation: der)
-
-// PEM (text, base64-encoded DER with header/footer)
-let pem = privateKey.pemRepresentation
-let fromPEM = try P256.Signing.PrivateKey(pemRepresentation: pem)
-
-// X9.63 (used by SecKey / Keychain interop)
-let x963 = privateKey.x963Representation
-let fromX963 = try P256.Signing.PrivateKey(x963Representation: x963)
-
-// Raw (scalar bytes only)
-let raw = privateKey.rawRepresentation
-let fromRaw = try P256.Signing.PrivateKey(rawRepresentation: raw)
-```
-
-### Public key serialization
-
-Public keys support the same formats plus compact and compressed
-representations:
+- [Key serialization](#key-serialization)
+- [Keychain storage](#keychain-storage)
+- [AES key wrap](#aes-key-wrap)
+- [HKDF on its own](#hkdf-on-its-own)
+- [HPKE details](#hpke-details)
+- [Post-quantum usage](#post-quantum-usage)
+- [The Insecure namespace](#the-insecure-namespace)
+- [Sealed box layout](#sealed-box-layout)
+- [Signing a digest](#signing-a-digest)
+- [Export compliance](#export-compliance)
+- [Performance](#performance)
+- [Moving from CommonCrypto](#moving-from-commoncrypto)
+
+## Key serialization
+
+| Key | Property / initializer | Use |
+|---|---|---|
+| NIST private (P256/P384/P521) | `derRepresentation` / `init(derRepresentation:)` | exchange with non-Apple systems |
+| | `pemRepresentation` / `init(pemRepresentation:)` | text formats, config files |
+| | `x963Representation` / `init(x963Representation:)` | `SecKey` and Keychain interop |
+| | `rawRepresentation` / `init(rawRepresentation:)` | the private scalar only |
+| NIST public | all of the above, plus `compactRepresentation` (optional, can be `nil`) and `compressedRepresentation` | |
+| Curve25519 private and public | `rawRepresentation` / `init(rawRepresentation:)` only | |
+| ECDSA signature | `derRepresentation` (interop), `rawRepresentation` (r followed by s) | |
 
 ```swift
-let publicKey = privateKey.publicKey
-
-let der = publicKey.derRepresentation
-let pem = publicKey.pemRepresentation
-let x963 = publicKey.x963Representation
-let raw = publicKey.rawRepresentation
-let compact = publicKey.compactRepresentation   // Optional; may be nil
-let compressed = publicKey.compressedRepresentation
+import CryptoKit
+import Foundation
+
+func roundTrip() throws {
+    let issuer = P384.Signing.PrivateKey()
+    let asPEM = issuer.publicKey.pemRepresentation
+    let reloaded = try P384.Signing.PublicKey(pemRepresentation: asPEM)
+
+    let sig = try issuer.signature(for: Data("ticket-42".utf8))
+    let wire = sig.derRepresentation
+    let back = try P384.Signing.ECDSASignature(derRepresentation: wire)
+    let compact = try P384.Signing.ECDSASignature(rawRepresentation: sig.rawRepresentation)
+    _ = (reloaded.isValidSignature(back, for: Data("ticket-42".utf8)), compact)
+}
 ```
 
-### Curve25519 key serialization
-
-```swift
-let key = Curve25519.Signing.PrivateKey()
+Rule: DER when the other end is not CryptoKit; raw when both ends are CryptoKit
+and size matters.
 
-// Only raw representation available
-let raw = key.rawRepresentation
-let restored = try Curve25519.Signing.PrivateKey(rawRepresentation: raw)
+## Keychain storage
 
-let pubRaw = key.publicKey.rawRepresentation
-let restoredPub = try Curve25519.Signing.PublicKey(rawRepresentation: pubRaw)
-```
+Two strategies, chosen by whether the key has an X9.63 form that `SecKey`
+understands.
 
-### ECDSA signature serialization
+### NIST keys as SecKey items
 
 ```swift
-let signature = try privateKey.signature(for: data)
-
-// DER-encoded (standard interop format)
-let derSig = signature.derRepresentation
-
-// Raw (r || s concatenation)
-let rawSig = signature.rawRepresentation
-
-// Restore
-let fromDER = try P256.Signing.ECDSASignature(derRepresentation: derSig)
-let fromRaw = try P256.Signing.ECDSASignature(rawRepresentation: rawSig)
-```
-
-Use DER for interoperability with non-Apple systems. Use raw for compact
-storage where both sides are CryptoKit.
-
-## Keychain Storage
-
-CryptoKit key types divide into two storage strategies based on whether
-they have a SecKey-compatible representation.
-
-### NIST keys via SecKey
-
-P256, P384, and P521 private keys can be stored as native Keychain
-elliptic-curve keys using their X9.63 representation.
+import CryptoKit
+import Foundation
+import Security
 
-```swift
-protocol SecKeyConvertible: CustomStringConvertible {
-    init<Bytes>(x963Representation: Bytes) throws where Bytes: ContiguousBytes
+protocol SecKeyStorable {
+    init<Bytes: ContiguousBytes>(x963Representation: Bytes) throws
     var x963Representation: Data { get }
 }
 
-extension P256.Signing.PrivateKey: SecKeyConvertible {}
-extension P256.KeyAgreement.PrivateKey: SecKeyConvertible {}
-extension P384.Signing.PrivateKey: SecKeyConvertible {}
-extension P384.KeyAgreement.PrivateKey: SecKeyConvertible {}
-extension P521.Signing.PrivateKey: SecKeyConvertible {}
-extension P521.KeyAgreement.PrivateKey: SecKeyConvertible {}
-```
-
-Store:
+extension P256.Signing.PrivateKey: SecKeyStorable {}
+extension P256.KeyAgreement.PrivateKey: SecKeyStorable {}
+extension P384.Signing.PrivateKey: SecKeyStorable {}
+extension P384.KeyAgreement.PrivateKey: SecKeyStorable {}
+extension P521.Signing.PrivateKey: SecKeyStorable {}
+extension P521.KeyAgreement.PrivateKey: SecKeyStorable {}
 
-```swift
-func storeKey<T: SecKeyConvertible>(_ key: T, label: String) throws {
-    let attributes: [String: Any] = [
-        kSecAttrKeyType as String: kSecAttrKeyTypeECSECPrimeRandom,
-        kSecAttrKeyClass as String: kSecAttrKeyClassPrivate
-    ]
-
-    guard let secKey = SecKeyCreateWithData(
-        key.x963Representation as CFData,
-        attributes as CFDictionary,
-        nil
-    ) else {
-        throw KeyStoreError.unableToCreateSecKey
-    }
+enum VaultError: Error {
+    case conversion(String)
+    case status(OSStatus)
+}
 
-    let query: [String: Any] = [
-        kSecClass as String: kSecClassKey,
-        kSecAttrApplicationLabel as String: label,
-        kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlocked,
-        kSecUseDataProtectionKeychain as String: true,
-        kSecValueRef as String: secKey
-    ]
-
-    let status = SecItemAdd(query as CFDictionary, nil)
-    guard status == errSecSuccess else {
-        throw KeyStoreError.saveFailed(status)
+func storeECKey<K: SecKeyStorable>(_ key: K, label: String) throws {
+    let attributes = [
+        kSecAttrKeyType: kSecAttrKeyTypeECSECPrimeRandom,
+        kSecAttrKeyClass: kSecAttrKeyClassPrivate
+    ] as [String: Any]
+    var cfError: Unmanaged<CFError>?
+    guard let keyRef = SecKeyCreateWithData(key.x963Representation as CFData, attributes as CFDictionary, &cfError) else {
+        throw VaultError.conversion(cfError.map { String(describing: $0.takeRetainedValue()) } ?? "unknown")
     }
+    let item = [
+        kSecClass: kSecClassKey,
+        kSecAttrApplicationLabel: label,
+        kSecAttrAccessible: kSecAttrAccessibleWhenUnlocked,
+        kSecUseDataProtectionKeychain: true,
+        kSecValueRef: keyRef
+    ] as [String: Any]
+    let status = SecItemAdd(item as CFDictionary, nil)
+    guard status == errSecSuccess else { throw VaultError.status(status) }
 }
-```
 
-Retrieve:
-
-```swift
-func readKey<T: SecKeyConvertible>(label: String) throws -> T? {
-    let query: [String: Any] = [
-        kSecClass as String: kSecClassKey,
-        kSecAttrApplicationLabel as String: label,
-        kSecAttrKeyType as String: kSecAttrKeyTypeECSECPrimeRandom,
-        kSecUseDataProtectionKeychain as String: true,
-        kSecReturnRef as String: true
-    ]
-
-    var item: CFTypeRef?
-    switch SecItemCopyMatching(query as CFDictionary, &item) {
+func loadECKey<K: SecKeyStorable>(label: String) throws -> K? {
+    let lookup = [
+        kSecClass: kSecClassKey,
+        kSecAttrApplicationLabel: label,
+        kSecAttrKeyType: kSecAttrKeyTypeECSECPrimeRandom,
+        kSecUseDataProtectionKeychain: true,
+        kSecReturnRef: true
+    ] as [String: Any]
+    var found: CFTypeRef?
+    switch SecItemCopyMatching(lookup as CFDictionary, &found) {
     case errSecSuccess:
-        let secKey = item as! SecKey
-        var error: Unmanaged<CFError>?
-        guard let data = SecKeyCopyExternalRepresentation(secKey, &error) as Data? else {
-            throw KeyStoreError.exportFailed
+        guard let ref = found, CFGetTypeID(ref) == SecKeyGetTypeID() else { return nil }
+        var failure: Unmanaged<CFError>?
+        guard let bytes = SecKeyCopyExternalRepresentation(ref as! SecKey, &failure) as Data? else {
+            throw VaultError.conversion("export failed")
         }
-        return try T(x963Representation: data)
+        return try K(x963Representation: bytes)
     case errSecItemNotFound:
         return nil
-    case let status:
-        throw KeyStoreError.readFailed(status)
+    case let other:
+        throw VaultError.status(other)
     }
 }
 ```
 
-### Non-NIST keys via generic password
+The P256, P384 and P521 signing and key-agreement private keys all have the
+X9.63 initializer and property, so they conform to the helper protocol with an
+empty extension. Reading asks for `kSecReturnRef`, exports the `SecKey` with
+`SecKeyCopyExternalRepresentation` and rebuilds the CryptoKit key; a missing
+item returns `nil` and every other status throws.
 
-Curve25519 keys and SymmetricKey lack X9.63 representations. Store them
-as generic password Keychain items using their raw data.
+### Everything else as generic passwords
 
-```swift
-protocol GenericPasswordConvertible: CustomStringConvertible {
-    init<D>(genericKeyRepresentation data: D) throws where D: ContiguousBytes
-    var genericKeyRepresentation: SymmetricKey { get }
-}
+Curve25519 keys and `SymmetricKey` have no X9.63 form. Store their raw bytes as
+`kSecClassGenericPassword` items.
 
-extension Curve25519.Signing.PrivateKey: GenericPasswordConvertible {
-    init<D>(genericKeyRepresentation data: D) throws where D: ContiguousBytes {
-        try self.init(rawRepresentation: data)
-    }
+```swift
+import CryptoKit
+import Foundation
+import Security
 
-    var genericKeyRepresentation: SymmetricKey {
-        rawRepresentation.withUnsafeBytes { SymmetricKey(data: $0) }
-    }
+protocol RawKeyStorable {
+    init<Bytes: ContiguousBytes>(rawKeyBytes: Bytes) throws
+    var rawKeyBytes: SymmetricKey { get }
 }
 
-extension Curve25519.KeyAgreement.PrivateKey: GenericPasswordConvertible {
-    init<D>(genericKeyRepresentation data: D) throws where D: ContiguousBytes {
-        try self.init(rawRepresentation: data)
-    }
-
-    var genericKeyRepresentation: SymmetricKey {
-        rawRepresentation.withUnsafeBytes { SymmetricKey(data: $0) }
-    }
+extension Curve25519.Signing.PrivateKey: RawKeyStorable {
+    init<Bytes: ContiguousBytes>(rawKeyBytes: Bytes) throws { try self.init(rawRepresentation: rawKeyBytes) }
+    var rawKeyBytes: SymmetricKey { SymmetricKey(data: rawRepresentation) }
 }
 
-extension SymmetricKey: GenericPasswordConvertible {
-    init<D>(genericKeyRepresentation data: D) throws where D: ContiguousBytes {
-        self.init(data: data)
-    }
-
-    var genericKeyRepresentation: SymmetricKey { self }
+extension Curve25519.KeyAgreement.PrivateKey: RawKeyStorable {
+    init<Bytes: ContiguousBytes>(rawKeyBytes: Bytes) throws { try self.init(rawRepresentation: rawKeyBytes) }
+    var rawKeyBytes: SymmetricKey { SymmetricKey(data: rawRepresentation) }
 }
-```
 
-Store:
-
-```swift
-func storeKey<T: GenericPasswordConvertible>(
-    _ key: T, account: String
-) throws {
-    try key.genericKeyRepresentation.withUnsafeBytes { keyBytes in
-        let query: [String: Any] = [
-            kSecClass as String: kSecClassGenericPassword,
-            kSecAttrAccount as String: account,
-            kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlocked,
-            kSecUseDataProtectionKeychain as String: true,
-            kSecValueData as String: Data(keyBytes)
-        ]
-
-        let status = SecItemAdd(query as CFDictionary, nil)
-        guard status == errSecSuccess else {
-            throw KeyStoreError.saveFailed(status)
-        }
-    }
+extension SymmetricKey: RawKeyStorable {
+    init<Bytes: ContiguousBytes>(rawKeyBytes: Bytes) throws { self.init(data: rawKeyBytes) }
+    var rawKeyBytes: SymmetricKey { self }
 }
-```
-
-### Secure Enclave keys in Keychain
-
-Secure Enclave keys export an encrypted `dataRepresentation` that only
-the same device's Secure Enclave can restore. Store this blob as a generic
-password:
 
-```swift
-extension SecureEnclave.P256.Signing.PrivateKey: GenericPasswordConvertible {
-    init<D>(genericKeyRepresentation data: D) throws where D: ContiguousBytes {
-        try self.init(dataRepresentation: data.withUnsafeBytes { Data($0) })
-    }
-
-    var genericKeyRepresentation: SymmetricKey {
-        SymmetricKey(data: dataRepresentation)
-    }
+func storeRawKey<K: RawKeyStorable>(_ key: K, account: String) throws {
+    let bytes = key.rawKeyBytes.withUnsafeBytes { Data($0) }
+    let item = [
+        kSecClass: kSecClassGenericPassword,
+        kSecAttrAccount: account,
+        kSecAttrAccessible: kSecAttrAccessibleWhenUnlocked,
+        kSecUseDataProtectionKeychain: true,
+        kSecValueData: bytes
+    ] as [String: Any]
+    let status = SecItemAdd(item as CFDictionary, nil)
+    if status != errSecSuccess { throw NSError(domain: NSOSStatusErrorDomain, code: Int(status)) }
 }
 ```
 
-## AES Key Wrapping
+Secure Enclave keys follow the same generic-password route: store the encrypted
+`dataRepresentation` as the password data and rebuild the key with
+`init(dataRepresentation:)` after reading it back.
 
-CryptoKit supports AES Key Wrap (RFC 3394) for securely wrapping one
-symmetric key with another.
-
-```swift
-let kek = SymmetricKey(size: .bits256)  // Key Encryption Key
-let dek = SymmetricKey(size: .bits256)  // Data Encryption Key
+## AES key wrap
 
-// Wrap
-let wrappedData = try AES.KeyWrap.wrap(dek, using: kek)
-
-// Unwrap
-let unwrapped = try AES.KeyWrap.unwrap(wrappedData, using: kek)
-```
-
-Use key wrapping when transmitting or storing keys encrypted under
-a master key.
-
-## HKDF Key Derivation
-
-HKDF (RFC 5869) derives cryptographic keys from input key material.
-Available as a standalone operation outside of `SharedSecret`.
+RFC 3394 key wrapping encrypts one key (the data key) under another (the key
+encryption key). Use it to store or send keys protected by a master key.
 
 ```swift
-let inputKey = SymmetricKey(size: .bits256)
-
-// Derive with salt and info
-let derived = HKDF<SHA256>.deriveKey(
-    inputKeyMaterial: inputKey,
-    salt: Data("salt".utf8),
-    info: Data("my-app-encryption-v1".utf8),
-    outputByteCount: 32
-)
-```
-
-### Extract-then-expand (two-step)
+import CryptoKit
+import Foundation
 
-For protocols that need explicit control:
+func wrapFileKey(_ fileKey: SymmetricKey, under master: SymmetricKey) throws -> Data {
+    try AES.KeyWrap.wrap(fileKey, using: master)
+}
 
-```swift
-// Extract: produce a pseudorandom key
-let prk = HKDF<SHA256>.extract(
-    inputKeyMaterial: inputKey,
-    salt: Data("salt".utf8)
-)
-
-// Expand: derive output key material
-let okm = HKDF<SHA256>.expand(
-    pseudoRandomKey: prk,
-    info: Data("context".utf8),
-    outputByteCount: 32
-)
+func unwrapFileKey(_ wrapped: Data, under master: SymmetricKey) throws -> SymmetricKey {
+    try AES.KeyWrap.unwrap(wrapped, using: master)
+}
 ```
 
-## HPKE (Hybrid Public Key Encryption)
-
-HPKE (RFC 9180) combines key encapsulation with authenticated encryption
-for public-key encryption workflows. It is available on iOS 17+; the X-Wing
-post-quantum hybrid ciphersuite requires iOS 26+.
-
-### Sending an encrypted message
-
-```swift
-let recipientKey = P256.KeyAgreement.PrivateKey()
-
-var sender = try HPKE.Sender(
-    recipientKey: recipientKey.publicKey,
-    ciphersuite: .P256_SHA256_AES_GCM_256,
-    info: Data("my-protocol-v1".utf8)
-)
-
-let ciphertext = try sender.seal(Data("secret message".utf8))
-let encapsulatedKey = sender.encapsulatedKey
-// Send ciphertext + encapsulatedKey to recipient
-```
+## HKDF on its own
 
-### Receiving
+HKDF (RFC 5869) is also available directly, for key material that did not come
+from ECDH.
 
 ```swift
-var recipient = try HPKE.Recipient(
-    privateKey: recipientKey,
-    ciphersuite: .P256_SHA256_AES_GCM_256,
-    info: Data("my-protocol-v1".utf8),
-    encapsulatedKey: encapsulatedKey
-)
-
-let plaintext = try recipient.open(ciphertext)
+import CryptoKit
+import Foundation
+
+func deriveSubkeys(from material: SymmetricKey) -> (SymmetricKey, SymmetricKey) {
+    let direct = HKDF<SHA256>.deriveKey(
+        inputKeyMaterial: material,
+        salt: Data("vault-salt".utf8),
+        info: Data("vault index key".utf8),
+        outputByteCount: 32
+    )
+    let pseudoKey = HKDF<SHA256>.extract(inputKeyMaterial: material, salt: Data("vault-salt".utf8))
+    let expanded = HKDF<SHA256>.expand(pseudoRandomKey: pseudoKey, info: Data("vault blob key".utf8), outputByteCount: 32)
+    return (direct, expanded)
+}
 ```
 
-### Available ciphersuites
-
-| Ciphersuite | KEM | KDF | AEAD | Availability |
-|---|---|---|---|---|
-| `.P256_SHA256_AES_GCM_256` | P256 | HKDF-SHA256 | AES-GCM-256 | iOS 17+ |
-| `.P384_SHA384_AES_GCM_256` | P384 | HKDF-SHA384 | AES-GCM-256 | iOS 17+ |
-| `.P521_SHA512_AES_GCM_256` | P521 | HKDF-SHA512 | AES-GCM-256 | iOS 17+ |
-| `.Curve25519_SHA256_ChachaPoly` | X25519 | HKDF-SHA256 | ChaCha20Poly1305 | iOS 17+ |
-| `.XWingMLKEM768X25519_SHA256_AES_GCM_256` | X-Wing hybrid | HKDF-SHA256 | AES-GCM-256 | iOS 26+ |
+`deriveKey` does both steps at once; `extract` then `expand` gives the
+pseudorandom key in between.
 
-## Post-Quantum APIs
+## HPKE details
 
-iOS 26+ adds ML-KEM key encapsulation, ML-DSA signatures, and the X-Wing
-hybrid HPKE KEM. Guard these APIs with availability checks unless the
-deployment target is iOS 26+.
-
-### ML-KEM encapsulation
+HPKE is RFC 9180. It is available from iOS 17; the X-Wing hybrid suite needs
+iOS 26.
 
 ```swift
-if #available(iOS 26.0, *) {
-    let privateKey = try MLKEM768.PrivateKey()
-    let result = try privateKey.publicKey.encapsulate()
+import CryptoKit
+import Foundation
 
-    let sharedKey = result.sharedSecret
-    let encapsulated = result.encapsulated
-    let recovered = try privateKey.decapsulate(encapsulated)
+func sendToServer(_ report: Data, serverKey: P256.KeyAgreement.PublicKey) throws -> (ciphertext: Data, encapsulated: Data) {
+    var hpkeSender = try HPKE.Sender(recipientKey: serverKey, ciphersuite: .P256_SHA256_AES_GCM_256,
+                                     info: Data("crash-report v1".utf8))
+    return (try hpkeSender.seal(report), hpkeSender.encapsulatedKey)
 }
-```
-
-`encapsulated` is what the sender transmits. `sharedSecret` and the decapsulated
-result are `SymmetricKey` values.
 
-### ML-DSA signatures
-
-```swift
-if #available(iOS 26.0, *) {
-    let privateKey = try MLDSA65.PrivateKey()
-    let signature = try privateKey.signature(for: message)
-    let isValid = privateKey.publicKey.isValidSignature(signature, for: message)
+func receiveOnServer(_ ciphertext: Data, encapsulated: Data, key: P256.KeyAgreement.PrivateKey) throws -> Data {
+    var hpkeRecipient = try HPKE.Recipient(privateKey: key, ciphersuite: .P256_SHA256_AES_GCM_256,
+                                           info: Data("crash-report v1".utf8), encapsulatedKey: encapsulated)
+    return try hpkeRecipient.open(ciphertext)
 }
 ```
 
-Secure Enclave variants exist for `SecureEnclave.MLKEM768`,
-`SecureEnclave.MLKEM1024`, `SecureEnclave.MLDSA65`, and
-`SecureEnclave.MLDSA87` on supported hardware.
-
-Sources: [CryptoKit](https://sosumi.ai/documentation/cryptokit),
-[HPKE](https://sosumi.ai/documentation/cryptokit/hpke), and
-[quantum-secure workflows](https://sosumi.ai/documentation/cryptokit/enhancing-your-app-s-privacy-and-security-with-quantum-secure-workflows).
+| Ciphersuite | Minimum iOS | Key encapsulation | Key derivation | Authenticated cipher |
+|---|---|---|---|---|
+| `.P256_SHA256_AES_GCM_256` | 17 | NIST P-256 | SHA-256 HKDF | 256-bit AES-GCM |
+| `.P384_SHA384_AES_GCM_256` | 17 | NIST P-384 | SHA-384 HKDF | 256-bit AES-GCM |
+| `.P521_SHA512_AES_GCM_256` | 17 | NIST P-521 | SHA-512 HKDF | 256-bit AES-GCM |
+| `.Curve25519_SHA256_ChachaPoly` | 17 | X25519 | SHA-256 HKDF | ChaCha20-Poly1305 |
+| `.XWingMLKEM768X25519_SHA256_AES_GCM_256` | 26 | X-Wing hybrid (ML-KEM-768 with X25519) | SHA-256 HKDF | 256-bit AES-GCM |
 
-## Insecure Module
+## Post-quantum usage
 
-The `Insecure` enum provides MD5 and SHA1 for legacy compatibility ONLY.
+Guard ML-KEM, ML-DSA and X-Wing with an iOS 26 availability check unless the
+deployment target is 26 or later.
 
 ```swift
 import CryptoKit
+import Foundation
+
+@available(iOS 26.0, *)
+func kemHandshake() throws -> Bool {
+    let receiverKey = try MLKEM768.PrivateKey()
+    let result = try receiverKey.publicKey.encapsulate()
+    let transmitted = result.encapsulated
+    let recovered = try receiverKey.decapsulate(transmitted)
+    return recovered == result.sharedSecret
+}
 
-// Legacy checksum verification
-let md5 = Insecure.MD5.hash(data: fileData)
-let sha1 = Insecure.SHA1.hash(data: fileData)
+@available(iOS 26.0, *)
+func quantumSafeSignature(_ firmware: Data) throws -> Bool {
+    let signer = try MLDSA65.PrivateKey()
+    let sig = try signer.signature(for: firmware)
+    return signer.publicKey.isValidSignature(sig, for: firmware)
+}
 ```
 
-Valid uses:
-- Verifying checksums from legacy systems
-- Computing ETags or content hashes for caching
-- Protocol interop requiring MD5/SHA1
-
-Invalid uses:
-- Password hashing
-- Data integrity for security
-- Digital signatures
-- HMAC for authentication
+- The sender runs `encapsulate()` on the receiver's public key and transmits
+  `encapsulated`. The receiver calls `decapsulate(_:)`.
+- Both the sender's `sharedSecret` and the receiver's decapsulated value are a
+  `SymmetricKey`, and they are equal.
+- The Secure Enclave variants listed in the main skill exist on supported
+  hardware.
 
-The `Insecure` namespace makes insecure usage explicit at the call site.
+## The Insecure namespace
 
-## SealedBox Anatomy
+`Insecure.MD5` and `Insecure.SHA1` live in the `Insecure` enum so that every
+use is visibly flagged at the call site.
 
-Both AES-GCM and ChaChaPoly produce a sealed box with three components:
-
-| Component | AES-GCM | ChaChaPoly |
-|---|---|---|
-| Nonce | 12 bytes | 12 bytes |
-| Ciphertext | Same length as plaintext | Same length as plaintext |
-| Tag | 16 bytes | 16 bytes |
-
-### Combined representation
+| Fine | Never |
+|---|---|
+| verifying a legacy checksum | hashing passwords |
+| cache keys, ETags, content hashes | integrity that security depends on |
+| a protocol that requires MD5 or SHA-1 | digital signatures |
+| | HMAC authentication |
 
 ```swift
-let sealedBox = try AES.GCM.seal(plaintext, using: key)
-
-// Combined: nonce (12) + ciphertext (N) + tag (16)
-let combined = sealedBox.combined  // Optional for AES-GCM, non-optional for ChaChaPoly
-
-// Individual components
-let nonce = sealedBox.nonce
-let ciphertext = sealedBox.ciphertext
-let tag = sealedBox.tag
-```
-
-### Reconstructing from components
-
-When receiving nonce, ciphertext, and tag separately:
+import CryptoKit
+import Foundation
 
-```swift
-let box = try AES.GCM.SealedBox(
-    nonce: AES.GCM.Nonce(data: nonceData),
-    ciphertext: ciphertextData,
-    tag: tagData
-)
-let plaintext = try AES.GCM.open(box, using: key)
+func legacyETag(for body: Data) -> String {
+    Insecure.MD5.hash(data: body).reduce(into: "") { $0 += String(format: "%02x", $1) }
+}
 ```
 
-### Reconstructing from combined
+## Sealed box layout
 
-```swift
-let box = try AES.GCM.SealedBox(combined: combinedData)
-let plaintext = try AES.GCM.open(box, using: key)
-```
+For both AES-GCM and ChaChaPoly:
 
-## Signing with Digest
+| Part | Size |
+|---|---|
+| nonce | 12 bytes |
+| ciphertext | same length as the plaintext |
+| tag | 16 bytes |
 
-For P256/P384/P521, sign a pre-computed digest instead of raw data:
+`combined` is nonce, then ciphertext, then tag. The parts are also exposed as
+`.nonce`, `.ciphertext` and `.tag`.
 
 ```swift
-let digest = SHA256.hash(data: data)
-let signature = try privateKey.signature(for: digest)
-let isValid = publicKey.isValidSignature(signature, for: digest)
-```
-
-This avoids hashing the data twice when the digest is already available.
-
-## Encryption Export Compliance
-
-Apps that use encryption must declare compliance in App Store Connect.
-
-### ITSAppUsesNonExemptEncryption
-
-Set in Info.plist:
+import CryptoKit
+import Foundation
 
-```xml
-<key>ITSAppUsesNonExemptEncryption</key>
-<false/>
+func reassemble(nonce: Data, body: Data, tag: Data, key: SymmetricKey) throws -> Data {
+    let sealed = try AES.GCM.SealedBox(nonce: AES.GCM.Nonce(data: nonce), ciphertext: body, tag: tag)
+    return try AES.GCM.open(sealed, using: key)
+}
 ```
 
-Set to `false` if the app uses ONLY:
-- Apple-provided encryption (HTTPS via URLSession, CryptoKit for
-  data protection on-device only)
-- Standard authentication (OAuth, SAML, biometrics)
-
-Set to `true` if the app:
-- Implements custom encryption protocols
-- Communicates with non-standard encrypted services
-- Encrypts data sent to third-party servers
-
-When `true`, an export compliance review or proper classification is
-required. See Apple's [Complying with Encryption Export Regulations](https://sosumi.ai/documentation/security/complying-with-encryption-export-regulations)
-documentation.
-
-## Performance Considerations
-
-### AES-GCM vs ChaChaPoly
-
-On Apple silicon devices, AES-GCM is hardware-accelerated and generally
-faster. ChaChaPoly performs better on devices without AES hardware
-acceleration (rare on modern Apple hardware). For most iOS apps, prefer
-AES-GCM.
+When the parts arrive already concatenated, use `SealedBox(combined:)` instead.
 
-### Hashing large data
+## Signing a digest
 
-Use incremental hashing for large files to avoid loading everything
-into memory:
+The NIST curves can sign and verify a digest you already computed, which avoids
+hashing the data twice.
 
 ```swift
-func hashFile(at url: URL) throws -> SHA256.Digest {
-    let handle = try FileHandle(forReadingFrom: url)
-    var hasher = SHA256()
-
-    while autoreleasepool(invoking: {
-        let chunk = handle.readData(ofLength: 1024 * 1024)  // 1 MB
-        guard !chunk.isEmpty else { return false }
-        hasher.update(data: chunk)
-        return true
-    }) {}
+import CryptoKit
+import Foundation
 
-    return hasher.finalize()
+func signPrehashed(_ file: Data, key: P521.Signing.PrivateKey) throws -> Bool {
+    let digest = SHA512.hash(data: file)
+    let signature = try key.signature(for: digest)
+    return key.publicKey.isValidSignature(signature, for: digest)
 }
 ```
 
-### Key generation costs
+## Export compliance
 
-| Operation | Relative Cost |
-|---|---|
-| `SymmetricKey(size:)` | Very fast (CSPRNG) |
-| `P256.Signing.PrivateKey()` | Fast |
-| `P384.Signing.PrivateKey()` | Moderate |
-| `P521.Signing.PrivateKey()` | Slower |
-| `SecureEnclave.P256.*.PrivateKey()` | Slowest (hardware round-trip) |
+Apps that use encryption declare it in App Store Connect and set the Boolean
+Info.plist key `ITSAppUsesNonExemptEncryption`.
 
-Generate keys once and store them. Do not regenerate per-operation.
+- `false` when the app only uses encryption that Apple's platforms provide (HTTPS
+  through `URLSession`, CryptoKit protecting data on the device) plus standard
+  authentication such as OAuth, SAML or biometrics.
+- `true` when it implements its own encryption protocol, offers a non-standard
+  encrypted service, or encrypts data it sends to third-party servers. In that
+  case the app needs an export classification (or a compliance review) first.
+  Apple's guide on this lives at
+  <https://developer.apple.com/documentation/security/complying-with-encryption-export-regulations>.
 
-## CommonCrypto Migration
+## Performance
 
-### Hashing
+- AES-GCM runs in hardware on Apple silicon and is usually faster.
+  ChaChaPoly only wins where AES acceleration is missing, which is rare on
+  current Apple devices. Default to AES-GCM.
+- Hash big files in pieces instead of loading them whole:
 
 ```swift
-// CommonCrypto (old)
-import CommonCrypto
-var digest = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
-data.withUnsafeBytes { CC_SHA256($0.baseAddress, CC_LONG(data.count), &digest) }
-
-// CryptoKit (new)
 import CryptoKit
-let digest = SHA256.hash(data: data)
-```
+import Foundation
 
-### HMAC
-
-```swift
-// CommonCrypto (old)
-var hmac = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
-keyData.withUnsafeBytes { keyPtr in
-    data.withUnsafeBytes { dataPtr in
-        CCHmac(CCHmacAlgorithm(kCCHmacAlgSHA256),
-               keyPtr.baseAddress, keyData.count,
-               dataPtr.baseAddress, data.count,
-               &hmac)
+func sha256OfFile(_ fileURL: URL) throws -> SHA256.Digest {
+    let reader = try FileHandle(forReadingFrom: fileURL)
+    defer { try? reader.close() }
+    var hasher = SHA256()
+    var finished = false
+    while !finished {
+        try autoreleasepool {
+            if let piece = try reader.read(upToCount: 1 << 20), !piece.isEmpty {
+                hasher.update(data: piece)
+            } else {
+                finished = true
+            }
+        }
     }
+    return hasher.finalize()
 }
-
-// CryptoKit (new)
-let mac = HMAC<SHA256>.authenticationCode(for: data, using: key)
 ```
 
-### AES encryption
+- Relative cost of key generation, cheapest first: `SymmetricKey(size:)`
+  (straight from the system random generator), P256, P384, P521, and
+  `SecureEnclave.P256.*.PrivateKey()` (a trip to the hardware).
+- Generate a key once and keep it; never create one per operation.
 
-```swift
-// CommonCrypto (old) -- error-prone, manual IV/padding management
-// ~30 lines of CCCrypt with buffer allocation
-
-// CryptoKit (new) -- authenticated encryption in one call
-let sealedBox = try AES.GCM.seal(data, using: key)
-let decrypted = try AES.GCM.open(sealedBox, using: key)
-```
+## Moving from CommonCrypto
 
-CryptoKit advantages over CommonCrypto:
-- Authenticated encryption by default (no unauthenticated CBC mode)
-- Type-safe keys and nonces
-- Automatic nonce generation
-- No manual buffer management
-- Constant-time comparisons built in
-- Sendable types for concurrency safety
+| CommonCrypto | CryptoKit |
+|---|---|
+| `CC_SHA256` into a manually sized buffer | `SHA256.hash(data:)` |
+| `CCHmac(kCCHmacAlgSHA256, ...)` | `HMAC<SHA256>.authenticationCode(for:using:)` |
+| `CCCrypt` with AES, a hand-managed IV and padding (dozens of lines) | `AES.GCM.seal` / `AES.GCM.open` |
+
+What changes for the better:
+
+- Encryption is authenticated by default; there is no unauthenticated CBC mode
+  to reach for by accident.
+- Keys and nonces have their own types.
+- Nonces are generated for you.
+- No manual buffer sizing or pointer handling.
+- Comparisons of MACs and signatures are constant-time.
+- The types are `Sendable`.