@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swift-security/references/certificate-trust.md

@@ -1,339 +1,274 @@
-# Certificate Trust Evaluation & Pinning
+# Certificate Trust, Pinning and Client Certificates
 
-> **Scope**: SecCertificate, SecTrust evaluation, SecIdentity, certificate pinning strategies (leaf / intermediate CA / SPKI hash / NSPinnedDomains), custom trust policies, client certificate authentication (mTLS), ATS interaction, and operational pin management. iOS 12+ through iOS 18, macOS 10.14+ through macOS 15.
->
-> **Out of scope**: Network-layer encryption beyond TLS certificate handling, server-side certificate management, App Transport Security as a standalone topic (covered briefly where it intersects pinning).
+What is here: the Security types for certificates, trust, identities and policies;
+pinning, whether by leaf, by issuing CA, by public-key digest or declaratively through
+`NSPinnedDomains`; building your own trust policy; mutual TLS; the points where App
+Transport Security and trust evaluation overlap; and running a pin set in production.
+It applies from iOS 12 through iOS 18 and macOS 10.14 through 15.
 
----
+What is not here: transport concerns other than checking TLS certificates, managing
+certificates on your servers, and ATS as a configuration topic (the `ios-networking`
+skill owns that).
 
 ## Contents
 
-- [Core Security Types](#core-security-types)
-- [Trust Evaluation APIs](#trust-evaluation-apis)
-  - [SecTrustEvaluateAsyncWithError  -  recommended async API (iOS 13+)](#sectrustevaluateasyncwitherror-recommended-async-api-ios-13)
-  - [SecTrustEvaluateWithError  -  synchronous, still current (iOS 12+)](#sectrustevaluatewitherror-synchronous-still-current-ios-12)
-  - [SecTrustEvaluate  -  deprecated since iOS 13](#sectrustevaluate-deprecated-since-ios-13)
-  - [SecTrustResultType reference](#sectrustresulttype-reference)
-- [Custom Trust Policy Configuration](#custom-trust-policy-configuration)
-- [Four Pinning Strategies](#four-pinning-strategies)
-  - [Leaf certificate pinning  -  breaks on every renewal](#leaf-certificate-pinning-breaks-on-every-renewal)
-  - [Intermediate CA pinning  -  5-10 year validity window](#intermediate-ca-pinning-510-year-validity-window)
-  - [SPKI hash pinning  -  survives renewal with same key pair](#spki-hash-pinning-survives-renewal-with-same-key-pair)
-  - [NSPinnedDomains  -  declarative pinning, zero code (iOS 14+)](#nspinneddomains-declarative-pinning-zero-code-ios-14)
-  - [Pinning Strategy Decision Matrix](#pinning-strategy-decision-matrix)
-- [SecCertificate and SecIdentity](#seccertificate-and-secidentity)
-  - [Creating certificates from DER data](#creating-certificates-from-der-data)
-  - [Importing PKCS#12 for client certificate authentication](#importing-pkcs12-for-client-certificate-authentication)
-  - [Client certificate authentication in URLSession](#client-certificate-authentication-in-urlsession)
-  - [Certificate chain inspection (backward-compatible)](#certificate-chain-inspection-backward-compatible)
-- [Anti-Patterns AI Code Generators Produce](#anti-patterns-ai-code-generators-produce)
-- [Backup Pins, Rotation, and Graceful Degradation](#backup-pins-rotation-and-graceful-degradation)
-- [ATS Interaction Points](#ats-interaction-points)
-- [API Deprecation Timeline](#api-deprecation-timeline)
-- [Thread Safety and Performance](#thread-safety-and-performance)
-- [CI/CD Guardrails](#cicd-guardrails)
-- [Cross-References](#cross-references)
-- [WWDC and Reference Citations](#wwdc-and-reference-citations)
-- [Summary Checklist](#summary-checklist)
-
-## Core Security Types
-
-| Type             | Purpose                                                           | Key Operations                                                                                                                  |
-| ---------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `SecCertificate` | X.509 certificate (DER-encoded)                                   | `SecCertificateCreateWithData`, `SecCertificateCopyKey` (iOS 12+), `SecCertificateCopyData`, `SecCertificateCopySubjectSummary` |
-| `SecTrust`       | Trust evaluation context for a certificate chain against policies | `SecTrustCreateWithCertificates`, `SecTrustEvaluateWithError` (iOS 12+), `SecTrustEvaluateAsyncWithError` (iOS 13+)             |
-| `SecIdentity`    | Private key + certificate pair for client authentication          | Extracted via `SecPKCS12Import`; used with `URLCredential(identity:certificates:persistence:)`                                  |
-| `SecPolicy`      | Validation policy (SSL hostname check, revocation)                | `SecPolicyCreateSSL`, `SecPolicyCreateRevocation`                                                                               |
-
----
-
-## Trust Evaluation APIs
-
-Three trust evaluation functions exist. Only two are current.
-
-### SecTrustEvaluateAsyncWithError  -  recommended async API (iOS 13+)
+- [The four types](#the-four-types)
+- [Evaluating trust](#evaluating-trust)
+- [Custom policies and anchors](#custom-policies-and-anchors)
+- [Four ways to pin](#four-ways-to-pin)
+- [Certificates and identities](#certificates-and-identities)
+- [Mistakes to reject in review](#mistakes-to-reject-in-review)
+- [Backup pins and rotation](#backup-pins-and-rotation)
+- [Where ATS meets trust](#where-ats-meets-trust)
+- [API timeline](#api-timeline)
+- [Threads and performance](#threads-and-performance)
+- [CI guardrails](#ci-guardrails)
+- [Related and sources](#related-and-sources)
+- [Checklist](#checklist)
+
+## The four types
+
+| Type | Role | Calls you will use |
+| --- | --- | --- |
+| `SecCertificate` | One X.509 certificate, DER bytes | create from data, copy the data back, copy a subject summary, and from iOS 12 `SecCertificateCopyKey` |
+| `SecTrust` | Certificates plus the policies they are judged by | `SecTrustCreateWithCertificates`; evaluation with `SecTrustEvaluateWithError` (12+) or the async variant (13+) |
+| `SecIdentity` | Certificate with its private key, for client authentication | Comes out of `SecPKCS12Import`; goes into `URLCredential(identity:certificates:persistence:)` |
+| `SecPolicy` | Which rules apply | `SecPolicyCreateSSL`, `SecPolicyCreateRevocation` |
+
+## Evaluating trust
+
+`SecTrustEvaluateAsyncWithError` takes the trust object, a dispatch queue and a
+callback. The callback receives the trust, a success flag and an optional `CFError`;
+the function itself returns an `OSStatus` saying whether evaluation could start.
+
+When a cached verdict exists, the callback may run before the call returns. Because
+evaluation may fetch intermediates and query revocation servers, start it from a
+background queue:
 
 ```swift
-func SecTrustEvaluateAsyncWithError(
-    _ trust: SecTrust,
-    _ queue: dispatch_queue_t,
-    _ result: @escaping (SecTrust, Bool, CFError?) -> Void
-) -> OSStatus
-```
+import Foundation
+import Security
 
-The callback receives a Boolean result and optional error. The callback may fire synchronously if the trust object has a cached result. Always dispatch on a **background queue**  -  evaluation may perform network access for intermediate certificate fetching or revocation checks.
+struct TrustFailure: Error {
+    let status: OSStatus
+    let underlying: CFError?
+}
 
-```swift
-// ✅ CORRECT: Async trust evaluation with proper error handling
-func evaluateTrust(_ trust: SecTrust, completion: @escaping (Bool, Error?) -> Void) {
-    let queue = DispatchQueue.global(qos: .userInitiated)
-    queue.async {
-        let status = SecTrustEvaluateAsyncWithError(trust, queue) { _, result, error in
-            completion(result, error as Error?)
+func checkTrustOffMain(_ trust: SecTrust, then report: @escaping @Sendable (TrustFailure?) -> Void) {
+    let worker = DispatchQueue(label: "tls.trust", qos: .userInitiated)
+    nonisolated(unsafe) let handedOver = trust
+    worker.async {
+        let started = SecTrustEvaluateAsyncWithError(handedOver, worker) { _, ok, cfError in
+            report(ok ? nil : TrustFailure(status: errSecNotTrusted, underlying: cfError))
         }
-        if status != errSecSuccess {
-            completion(false, NSError(domain: NSOSStatusErrorDomain, code: Int(status)))
+        if started != errSecSuccess {
+            report(TrustFailure(status: started, underlying: nil))
         }
     }
 }
 ```
 
-Apple has **not** added native async/await wrappers to the Security framework through iOS 18. Wrap manually:
+`SecTrust` is not `Sendable`, so moving it onto the worker queue is marked
+`nonisolated(unsafe)`: the caller promises not to touch the trust while it is
+being evaluated. `report` is `@Sendable` because it runs on that queue.
+
+Apple has not added async/await versions of these calls as of iOS 18. A continuation
+bridges the gap:
 
 ```swift
-// ✅ CORRECT: Swift concurrency wrapper
-func evaluateTrust(_ trust: SecTrust) async throws -> Bool {
-    try await withCheckedThrowingContinuation { continuation in
-        let queue = DispatchQueue.global(qos: .userInitiated)
-        queue.async {
-            let status = SecTrustEvaluateAsyncWithError(trust, queue) { _, result, error in
-                if result {
-                    continuation.resume(returning: true)
-                } else {
-                    continuation.resume(throwing: error! as Error)
-                }
-            }
-            if status != errSecSuccess {
-                continuation.resume(throwing: NSError(
-                    domain: NSOSStatusErrorDomain, code: Int(status)))
-            }
+func verifiedTrust(_ trust: SecTrust) async throws {
+    let _: Void = try await withCheckedThrowingContinuation { cont in
+        checkTrustOffMain(trust) { failure in
+            if let failure { cont.resume(throwing: failure) } else { cont.resume() }
         }
     }
 }
 ```
 
-### SecTrustEvaluateWithError  -  synchronous, still current (iOS 12+)
-
-```swift
-func SecTrustEvaluateWithError(_ trust: SecTrust, _ error: UnsafeMutablePointer<CFError?>?) -> Bool
-```
-
-**Not deprecated.** Valid inside `URLSessionDelegate` callbacks (already off main thread). Apple's warning: do not call from the main run loop  -  it may require network access.
-
-### SecTrustEvaluate  -  deprecated since iOS 13
-
-```swift
-// ❌ DEPRECATED: Returns opaque SecTrustResultType without error context
-func SecTrustEvaluate(_ trust: SecTrust,
-                      _ result: UnsafeMutablePointer<SecTrustResultType>) -> OSStatus
-```
-
-Returns a `SecTrustResultType` enum requiring manual interpretation. Replaced by `SecTrustEvaluateWithError`. **AI generators frequently produce this pattern  -  reject on sight.**
-
-### SecTrustResultType reference
-
-For code that must inspect results after evaluation via `SecTrustGetTrustResult`:
-
-| Result                     | Meaning                                      | Action                            |
-| -------------------------- | -------------------------------------------- | --------------------------------- |
-| `.unspecified`             | Chain validates to implicitly trusted anchor | **Proceed**  -  most common success |
-| `.proceed`                 | User explicitly chose to trust this cert     | **Proceed**                       |
-| `.deny`                    | User explicitly marked cert as untrusted     | **Reject**  -  never override       |
-| `.recoverableTrustFailure` | Failed but recovery possible                 | Inspect, possibly reconfigure     |
-| `.fatalTrustFailure`       | Fundamental certificate defect               | **Reject**                        |
-| `.otherError`              | Non-trust error (revoked, OS error)          | **Reject**                        |
-| `.invalid`                 | No evaluation performed yet                  | Call evaluation first             |
+The blocking form, `SecTrustEvaluateWithError`, which returns a `Bool` and fills an
+optional `CFError` out-parameter, arrived in iOS 12 and remains supported. Calling it
+from a `URLSessionDelegate` challenge handler is fine because that handler is already
+off the main thread. Keep it away from the main run loop: it may go to the network.
 
-Modern `SecTrustEvaluateWithError` collapses this to a Boolean. Treat only `.unspecified` and `.proceed` as success.
+`SecTrustEvaluate(_:_:)`, the old call that returns a `SecTrustResultType`, has been
+deprecated since iOS 13. Reject code that uses it.
 
----
+If you need the detailed verdict, read it with `SecTrustGetTrustResult` after
+evaluating:
 
-## Custom Trust Policy Configuration
+| `SecTrustResultType` | Meaning | Action |
+| --- | --- | --- |
+| `.unspecified` | Chains to an implicitly trusted anchor; the usual success | Proceed |
+| `.proceed` | User explicitly trusted it | Proceed |
+| `.deny` | User explicitly distrusted it | Reject; never override |
+| `.recoverableTrustFailure` | Failed, but settings could change the result | Inspect, reconfigure or reject |
+| `.fatalTrustFailure` | Structurally invalid | Reject |
+| `.otherError` | Revoked, or an OS error | Reject |
+| `.invalid` | Not evaluated yet | Evaluate first |
 
-```swift
-// ✅ CORRECT: SSL policy with hostname verification
-let policy = SecPolicyCreateSSL(true, "api.example.com" as CFString)
-// true = server evaluation; hostname enables SNI matching
-
-var trust: SecTrust?
-SecTrustCreateWithCertificates(certificateChain as CFTypeRef, policy, &trust)
-```
+Only `.unspecified` and `.proceed` count as trusted.
 
-```swift
-// ✅ CORRECT: Custom anchor while preserving system trust store
-SecTrustSetAnchorCertificates(trust, [customRootCA] as CFArray)
-SecTrustSetAnchorCertificatesOnly(trust, false)  // false = ALSO trust system anchors
-```
+## Custom policies and anchors
 
 ```swift
-// ❌ INCORRECT: Missing SecTrustSetAnchorCertificatesOnly
-SecTrustSetAnchorCertificates(trust, [customRootCA] as CFArray)
-// Without SecTrustSetAnchorCertificatesOnly(trust, false), ALL system anchors
-// are silently disabled  -  only your custom CA is trusted!
+func makeTrust(chain: [SecCertificate], host: String,
+               privateRoot: SecCertificate) -> SecTrust? {
+    let policy = SecPolicyCreateSSL(true, host as CFString)
+    var trust: SecTrust?
+    guard SecTrustCreateWithCertificates(chain as CFArray, policy, &trust) == errSecSuccess,
+          let trust else { return nil }
+
+    SecTrustSetAnchorCertificates(trust, [privateRoot] as CFArray)
+    SecTrustSetAnchorCertificatesOnly(trust, false)
+    return trust
+}
 ```
 
-```swift
-// ❌ INCORRECT: nil hostname disables hostname verification entirely
-let policy = SecPolicyCreateSSL(true, nil)
-// Any valid certificate for ANY domain now passes  -  MITM vector
-```
+`SecPolicyCreateSSL(true, host)` evaluates a server certificate and checks it against
+the hostname. Two traps:
 
----
+- Setting anchor certificates without `SecTrustSetAnchorCertificatesOnly(trust, false)`
+  quietly turns off every system root. Pass `false` unless you really mean to trust
+  only your own CA.
+- `SecPolicyCreateSSL(true, nil)` skips hostname checking. Any valid certificate for any
+  domain passes, which is a man-in-the-middle opening.
 
-## Four Pinning Strategies
+## Four ways to pin
 
-### Leaf certificate pinning  -  breaks on every renewal
+### 1. Leaf certificate (do not ship)
 
-Commercial TLS certificates expire every 90 days (Let's Encrypt) to 398 days (CA/Browser Forum maximum). When the server renews, the certificate bytes change (new serial, validity dates, signature) and the pin breaks. Users are locked out until an App Store update ships.
+Server certificates last from 90 days (common with free ACME CAs) up to 398 days (the
+CA/Browser Forum maximum). Every renewal changes the bytes, the pin stops matching, and
+nobody can connect until a fixed build clears review and reaches their phone.
 
 ```swift
-// ❌ DANGEROUS: Leaf pinning that breaks on every certificate renewal
-guard let chain = SecTrustCopyCertificateChain(serverTrust) as? [SecCertificate],
-      let serverCert = chain.first else {
-    completionHandler(.cancelAuthenticationChallenge, nil)
-    return
-}
-let serverCertData = SecCertificateCopyData(serverCert) as Data
-let localCertData = // loaded from bundle .cer file
-
-if serverCertData == localCertData {
-    completionHandler(.useCredential, URLCredential(trust: serverTrust))
-} else {
-    // WILL fire when the certificate renews, locking out all users
-    completionHandler(.cancelAuthenticationChallenge, nil)
+// Anti-pattern: exact leaf comparison
+func leafMatches(_ trust: SecTrust, bundled: Data) -> Bool {
+    let certs = (SecTrustCopyCertificateChain(trust) as? [SecCertificate]) ?? []
+    return certs.first.map { SecCertificateCopyData($0) as Data } == bundled
 }
 ```
 
-**Verdict**: never use in production unless you control the full certificate lifecycle AND can update pins without App Store review.
+Only consider this if you own the entire certificate lifecycle and can push new pins
+without app review.
 
-### Intermediate CA pinning  -  5-10 year validity window
+### 2. Intermediate CA
 
-Pin an intermediate CA certificate. Any leaf issued by that CA passes the check. The server can freely renew its leaf certificate.
+Compare each certificate in the chain with a bundled intermediate. Intermediates are
+valid for 5-10 years, so leaf renewals pass. The trade-off: any certificate that CA
+issues for your hostname passes too, so a compromise of that CA is in scope.
 
 ```swift
-// ✅ CORRECT: Intermediate CA pinning (resilient to leaf renewal)
-guard let chain = SecTrustCopyCertificateChain(serverTrust) as? [SecCertificate] else {
-    completionHandler(.cancelAuthenticationChallenge, nil)
-    return
-}
-
-let pinnedIntermediateData = // load intermediate CA .cer from bundle
-
-for cert in chain {
-    let certData = SecCertificateCopyData(cert) as Data
-    if certData == pinnedIntermediateData {
-        completionHandler(.useCredential, URLCredential(trust: serverTrust))
-        return
-    }
+func chainContainsIntermediate(_ trust: SecTrust, pinned: Data) -> Bool {
+    let certs = (SecTrustCopyCertificateChain(trust) as? [SecCertificate]) ?? []
+    return certs.dropFirst().contains { SecCertificateCopyData($0) as Data == pinned }
 }
-completionHandler(.cancelAuthenticationChallenge, nil)
 ```
 
-**Tradeoff**: trusts any certificate from that CA, not just yours. If the CA is compromised, a same-CA certificate could impersonate your server.
+### 3. SPKI hash (recommended in code)
 
-### SPKI hash pinning  -  survives renewal with same key pair
+The hash of the SubjectPublicKeyInfo stays the same across renewals as long as the key
+pair does, which makes it the programmatic approach to choose.
 
-Hashes the SubjectPublicKeyInfo (SPKI) structure. When certificates renew **with the same key pair**, the SPKI stays identical. This is the **recommended programmatic approach**.
+One detail breaks most hand-written implementations: what
+`SecKeyCopyExternalRepresentation` gives back is only the key material, lacking the
+ASN.1 prefix that turns it into a SubjectPublicKeyInfo. Put the algorithm's prefix in
+front before hashing; pins produced with OpenSSL are computed over the full structure
+and will otherwise never match.
 
-**Critical correctness issue**: `SecKeyCopyExternalRepresentation` returns raw key bytes **without** the ASN.1 SPKI header. You must prepend the correct header before hashing. Omitting this produces incorrect hashes that won't match pins generated via OpenSSL.
+```swift
+import CryptoKit
 
-The code below uses current APIs with proper SPKI construction. Do not hash raw key bytes directly; they lack the ASN.1 SPKI header expected by common pin-generation workflows.
+final class PinnedSessionDelegate: NSObject, URLSessionDelegate {
+    private let acceptedPins: Set<String>
 
-```swift
-// ✅ CORRECT: SPKI hash pinning with ASN.1 header and modern APIs
-class SPKIPinningDelegate: NSObject, URLSessionDelegate {
-
-    // ASN.1 headers for reconstructing SPKI from raw key data
-    private static let rsa2048Header: [UInt8] = [
-        0x30, 0x82, 0x01, 0x22, 0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86,
-        0xf7, 0x0d, 0x01, 0x01, 0x01, 0x05, 0x00, 0x03, 0x82, 0x01, 0x0f, 0x00
-    ]
-    private static let ecP256Header: [UInt8] = [
-        0x30, 0x59, 0x30, 0x13, 0x06, 0x07, 0x2a, 0x86, 0x48, 0xce, 0x3d, 0x02,
-        0x01, 0x06, 0x08, 0x2a, 0x86, 0x48, 0xce, 0x3d, 0x03, 0x01, 0x07, 0x03,
-        0x42, 0x00
-    ]
-
-    private let pinnedHashes: Set<String>  // Base64(SHA256(SPKI))
-
-    init(pinnedHashes: Set<String>) {
-        self.pinnedHashes = pinnedHashes
+    init(acceptedPins: Set<String>) {
+        self.acceptedPins = acceptedPins
     }
 
-    func urlSession(_ session: URLSession,
-                    didReceive challenge: URLAuthenticationChallenge,
-                    completionHandler: @escaping (URLSession.AuthChallengeDisposition,
-                                                  URLCredential?) -> Void) {
-        guard challenge.protectionSpace.authenticationMethod
-                == NSURLAuthenticationMethodServerTrust,
-              let serverTrust = challenge.protectionSpace.serverTrust else {
-            completionHandler(.performDefaultHandling, nil)
-            return
+    func urlSession(
+        _ session: URLSession,
+        didReceive challenge: URLAuthenticationChallenge
+    ) async -> (URLSession.AuthChallengeDisposition, URLCredential?) {
+        let space = challenge.protectionSpace
+        guard space.authenticationMethod == NSURLAuthenticationMethodServerTrust,
+              let serverTrust = space.serverTrust else {
+            return (.performDefaultHandling, nil)
         }
-
-        // Step 1: ALWAYS validate the chain via system trust first
         guard SecTrustEvaluateWithError(serverTrust, nil) else {
-            completionHandler(.cancelAuthenticationChallenge, nil)
-            return
+            return (.cancelAuthenticationChallenge, nil)
         }
 
-        // Step 2: Walk chain and check SPKI hashes
-        guard let chain = SecTrustCopyCertificateChain(serverTrust)
-                as? [SecCertificate] else {
-            completionHandler(.cancelAuthenticationChallenge, nil)
-            return
+        let presented = (SecTrustCopyCertificateChain(serverTrust) as? [SecCertificate]) ?? []
+        let pinsSeen = presented.compactMap(SPKIPin.base64SHA256(of:))
+        guard pinsSeen.contains(where: acceptedPins.contains) else {
+            return (.cancelAuthenticationChallenge, nil)
         }
+        return (.useCredential, URLCredential(trust: serverTrust))
+    }
+}
 
-        for cert in chain {
-            if let hash = spkiHash(for: cert), pinnedHashes.contains(hash) {
-                completionHandler(.useCredential, URLCredential(trust: serverTrust))
-                return
-            }
+enum SPKIPin {
+    private static let rsa2048Prefix = bytes("30820122300d06092a864886f70d01010105000382010f00")
+    private static let p256Prefix = bytes("3059301306072a8648ce3d020106082a8648ce3d030107034200")
+
+    private static func bytes(_ hex: String) -> Data {
+        var out = Data()
+        var index = hex.startIndex
+        while index < hex.endIndex {
+            let next = hex.index(index, offsetBy: 2)
+            out.append(UInt8(hex[index..<next], radix: 16) ?? 0)
+            index = next
         }
-        completionHandler(.cancelAuthenticationChallenge, nil)
+        return out
     }
 
-    private func spkiHash(for certificate: SecCertificate) -> String? {
-        guard let publicKey = SecCertificateCopyKey(certificate),
-              let keyData = SecKeyCopyExternalRepresentation(publicKey, nil) as Data?,
-              let attrs = SecKeyCopyAttributes(publicKey) as? [CFString: Any],
-              let keyType = attrs[kSecAttrKeyType] as? String,
-              let keySize = attrs[kSecAttrKeySizeInBits] as? Int else { return nil }
-
-        let header: [UInt8]
-        switch (keyType, keySize) {
-        case (kSecAttrKeyTypeRSA as String, 2048): header = Self.rsa2048Header
-        case (kSecAttrKeyTypeRSA as String, 4096):
-            // Add RSA-4096 header for production use
-            return nil
-        case (kSecAttrKeyTypeECSECPrimeRandom as String, 256):
-            header = Self.ecP256Header
+    static func base64SHA256(of certificate: SecCertificate) -> String? {
+        guard let key = SecCertificateCopyKey(certificate),
+              let keyBytes = SecKeyCopyExternalRepresentation(key, nil) as Data?,
+              let info = SecKeyCopyAttributes(key) as? [String: Any] else { return nil }
+
+        let algorithm = info[kSecAttrKeyType as String] as? String
+        let size = info[kSecAttrKeySizeInBits as String] as? Int
+        let prefix: Data
+        switch (algorithm, size) {
+        case (String(kSecAttrKeyTypeRSA), 2048): prefix = rsa2048Prefix
+        case (String(kSecAttrKeyTypeECSECPrimeRandom), 256): prefix = p256Prefix
         default: return nil
         }
-
-        var spki = Data(header)
-        spki.append(keyData)
-
-        var hash = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
-        spki.withUnsafeBytes {
-            _ = CC_SHA256($0.baseAddress, CC_LONG(spki.count), &hash)
-        }
-        return Data(hash).base64EncodedString()
+        let spki = prefix + keyBytes
+        return Data(SHA256.hash(data: spki)).base64EncodedString()
     }
 }
 ```
 
-Generate expected SPKI hashes from the command line:
-
-```bash
-# From a PEM certificate file:
-openssl x509 -in cert.pem -noout -pubkey | \
-  openssl pkey -pubin -outform der | \
-  openssl dgst -sha256 -binary | openssl enc -base64
-
-# From a live server:
-openssl s_client -connect api.example.com:443 </dev/null 2>/dev/null | \
-  openssl x509 -pubkey -noout | \
-  openssl pkey -pubin -outform der | \
-  openssl dgst -sha256 -binary | openssl enc -base64
+The order matters: first the system evaluation must pass, then the chain is walked and
+Base64(SHA-256(header + key)) is compared for each certificate; any match accepts with
+`URLCredential(trust:)`, no match cancels. Challenges other than server trust get
+default handling. The RSA-2048 header is 24 bytes starting `30 82 01 22`, the P-256
+header 26 bytes starting `30 59 30 13`. Other key types (RSA-4096, P-384) need their own
+headers; the sample refuses them rather than guessing. Older code often hashes with
+CommonCrypto's `CC_SHA256`; CryptoKit's `SHA256` does the same job.
+
+Generating a pin from a certificate file:
+
+```sh
+openssl x509 -in server.pem -noout -pubkey \
+  | openssl pkey -pubin -outform der \
+  | openssl dgst -sha256 -binary \
+  | openssl enc -base64
 ```
 
-### NSPinnedDomains  -  declarative pinning, zero code (iOS 14+)
+From a live server, start the pipe with
+`echo | openssl s_client -servername api.example.com -connect api.example.com:443`
+and feed its output through `openssl x509 -noout -pubkey` before the steps above.
 
-Apple's recommended approach. Enforced automatically by `URLSession` via ATS. Uses SPKI hashes.
+### 4. NSPinnedDomains (iOS 14+)
+
+Apple's recommended, declarative approach. `URLSession` enforces it through ATS, and it
+is based on SPKI hashes.
 
 ```xml
-<!-- ✅ CORRECT: CA identity pinning with backup pin via NSPinnedDomains -->
 <key>NSAppTransportSecurity</key>
 <dict>
     <key>NSPinnedDomains</key>
@@ -346,12 +281,11 @@ Apple's recommended approach. Enforced automatically by `URLSession` via ATS. Us
             <array>
                 <dict>
                     <key>SPKI-SHA256-BASE64</key>
-                    <string>PrimaryCA_SPKI_Hash_Base64==</string>
+                    <string>r/mIkG3eEpVdm+u/ko/cwxzOMo1bk4TyHIlByibiA5E=</string>
                 </dict>
                 <dict>
-                    <!-- Backup CA from a different provider -->
                     <key>SPKI-SHA256-BASE64</key>
-                    <string>BackupCA_SPKI_Hash_Base64==</string>
+                    <string>YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg=</string>
                 </dict>
             </array>
         </dict>
@@ -359,253 +293,251 @@ Apple's recommended approach. Enforced automatically by `URLSession` via ATS. Us
 </dict>
 ```
 
-Available keys per pinned domain:
-
-- **`NSPinnedCAIdentities`**  -  matches any intermediate or root in the chain (logical OR within array)
-- **`NSPinnedLeafIdentities`**  -  matches the leaf certificate only
-- **`NSIncludesSubdomains`**  -  covers first-level subdomains when `true`
-
-If **both** `NSPinnedCAIdentities` and `NSPinnedLeafIdentities` are specified, ATS requires a match in **each** category (AND between categories, OR within each).
+The two entries above stand for a primary CA and a backup CA from a different
+provider.
 
-**Limitations**: works with `URLSession` and `WKWebView` (iOS 16+ after earlier bugs were fixed). Does not work with `SFSafariViewController`. Pins are visible in `Info.plist` and cannot be updated without an app update.
+- `NSPinnedCAIdentities` is checked against every issuer above the leaf, intermediates
+  and root alike; a single hit among the listed hashes satisfies it.
+- `NSPinnedLeafIdentities` matches only the leaf.
+- `NSIncludesSubdomains` extends the rule to first-level subdomains.
+- List both kinds and both must be satisfied: each list needs its own hit (the lists
+  combine with AND, entries inside one list with OR).
+- Works for `URLSession` and, after fixes, `WKWebView` from iOS 16. Does not apply to
+  `SFSafariViewController`. Pins are visible to anyone reading `Info.plist`, and
+  changing them needs an app update.
 
-### Pinning Strategy Decision Matrix
+### Which to use
 
-| Strategy         | Resilience                        | Specificity                | Update Frequency     | Best For                         |
-| ---------------- | --------------------------------- | -------------------------- | -------------------- | -------------------------------- |
-| Leaf certificate | ❌ Breaks every 90-398 days       | Highest  -  exact cert match | Every renewal        | Never in production              |
-| Intermediate CA  | ✅ 5-10 years                     | Medium  -  all certs from CA | Rarely               | Single-CA-provider apps          |
-| SPKI hash (code) | ✅ Survives renewal with same key | High  -  specific key        | Only on key rotation | Dynamic pinsets, custom logic    |
-| NSPinnedDomains  | ✅ Survives renewal with same key | High  -  SPKI-based          | Only on key rotation | **Default choice for most apps** |
+| Approach | When |
+| --- | --- |
+| Leaf | Never in production |
+| Intermediate CA | Apps that use one CA |
+| SPKI in code | Pin sets that change at runtime, or custom decision logic |
+| `NSPinnedDomains` | Default for most apps |
 
----
+SPKI-based options (in code or `NSPinnedDomains`) only need updating when the key
+itself rotates.
 
-## SecCertificate and SecIdentity
+## Certificates and identities
 
-### Creating certificates from DER data
+Loading a bundled DER certificate:
 
 ```swift
-// ✅ CORRECT: Load .cer from app bundle
-guard let certURL = Bundle.main.url(forResource: "server", withExtension: "cer"),
-      let certData = try? Data(contentsOf: certURL),
-      let certificate = SecCertificateCreateWithData(nil, certData as CFData) else {
-    fatalError("Failed to load certificate")
+struct BundledCertificate {
+    let certificate: SecCertificate
+    let subject: String?
+    let publicKey: SecKey?
+    let der: Data
 }
 
-let summary = SecCertificateCopySubjectSummary(certificate) as String?
-let publicKey = SecCertificateCopyKey(certificate)           // iOS 12+
-let derBytes  = SecCertificateCopyData(certificate) as Data  // Round-trip to DER
+func loadBundledCertificate(named name: String) -> BundledCertificate? {
+    guard let folder = Bundle.main.resourceURL,
+          let der = try? Data(contentsOf: folder.appendingPathComponent("\(name).cer")),
+          let cert = SecCertificateCreateWithData(nil, der as CFData) else { return nil }
+
+    return BundledCertificate(
+        certificate: cert,
+        subject: SecCertificateCopySubjectSummary(cert) as String?,
+        publicKey: SecCertificateCopyKey(cert),
+        der: SecCertificateCopyData(cert) as Data
+    )
+}
 ```
 
-`SecCertificateCreateWithData` accepts **DER-encoded** data only  -  not PEM. For PEM files, strip the `-----BEGIN CERTIFICATE-----` header/footer and Base64-decode.
+`SecCertificateCreateWithData` accepts DER only. For PEM, remove the
+`-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines and Base64-decode
+what remains.
 
-### Importing PKCS#12 for client certificate authentication
+Importing a client identity from PKCS#12:
 
 ```swift
-// ✅ CORRECT: Import .p12 and extract SecIdentity
-func importIdentity(from p12Data: Data, password: String) throws -> SecIdentity {
-    let options: [String: Any] = [kSecImportExportPassphrase as String: password]
-    var rawItems: CFArray?
-    let status = SecPKCS12Import(p12Data as CFData, options as CFDictionary, &rawItems)
-
-    guard status == errSecSuccess,
-          let items = rawItems as? [[String: Any]],
-          let firstItem = items.first,
-          let identity = firstItem[kSecImportItemIdentity as String] as? SecIdentity else {
-        throw NSError(domain: NSOSStatusErrorDomain, code: Int(status))
+enum IdentityImportError: Error { case status(OSStatus), empty }
+
+func importClientIdentity(p12: Data, passphrase: String) throws -> SecIdentity {
+    let options = [kSecImportExportPassphrase as String: passphrase] as CFDictionary
+    var items: CFArray?
+    let status = SecPKCS12Import(p12 as CFData, options, &items)
+    guard status == errSecSuccess else { throw IdentityImportError.status(status) }
+
+    guard let entries = items as? [[String: Any]],
+          let value = entries.first?[kSecImportItemIdentity as String] else {
+        throw IdentityImportError.empty
     }
-    return identity
+    let ref = value as CFTypeRef
+    guard CFGetTypeID(ref) == SecIdentityGetTypeID() else { throw IdentityImportError.empty }
+    return ref as! SecIdentity
 }
 ```
 
-Result dictionary keys from `SecPKCS12Import`:
+Conditional casts to Core Foundation types always succeed at compile time, so the
+type-ID check is what actually verifies the value before the cast.
 
-- **`kSecImportItemIdentity`** (`SecIdentity`)  -  private key + certificate pair
-- **`kSecImportItemCertChain`** (`[SecCertificate]`)  -  full certificate chain
-- **`kSecImportItemTrust`** (`SecTrust`)  -  pre-configured trust object
-- **`kSecImportItemKeyID`** (`Data`)  -  typically SHA-1 hash of public key
+Each import result dictionary holds:
 
-**Never bundle passwords with your app.** Prompt the user or read from the Keychain.
+| Key | Value |
+| --- | --- |
+| `kSecImportItemIdentity` | `SecIdentity` |
+| `kSecImportItemCertChain` | `[SecCertificate]` |
+| `kSecImportItemTrust` | `SecTrust` |
+| `kSecImportItemKeyID` | `Data`, usually the SHA-1 of the public key |
 
-### Client certificate authentication in URLSession
+Never ship the PKCS#12 passphrase in the app. Ask the user, or keep it in the
+Keychain.
+
+Mutual TLS in a session delegate:
 
 ```swift
-// ✅ CORRECT: Mutual TLS delegate handling both server trust and client cert
-class MutualTLSDelegate: NSObject, URLSessionDelegate {
-    private let identity: SecIdentity
-    private let certChain: [SecCertificate]?
-
-    init(identity: SecIdentity, certChain: [SecCertificate]? = nil) {
-        self.identity = identity
-        self.certChain = certChain
+final class MutualTLSDelegate: NSObject, URLSessionDelegate, @unchecked Sendable {
+    private let clientIdentity: SecIdentity
+    private let issuerChain: [SecCertificate]
+
+    init(clientIdentity: SecIdentity, issuerChain: [SecCertificate]) {
+        self.clientIdentity = clientIdentity
+        self.issuerChain = issuerChain
     }
 
-    func urlSession(_ session: URLSession,
-                    didReceive challenge: URLAuthenticationChallenge,
-                    completionHandler: @escaping (URLSession.AuthChallengeDisposition,
-                                                  URLCredential?) -> Void) {
-        switch challenge.protectionSpace.authenticationMethod {
-        case NSURLAuthenticationMethodClientCertificate:
-            let credential = URLCredential(
-                identity: identity,
-                certificates: certChain,
-                persistence: .forSession
-            )
-            completionHandler(.useCredential, credential)
-
-        case NSURLAuthenticationMethodServerTrust:
-            guard let trust = challenge.protectionSpace.serverTrust,
-                  SecTrustEvaluateWithError(trust, nil) else {
-                completionHandler(.cancelAuthenticationChallenge, nil)
-                return
+    func urlSession(
+        _ session: URLSession,
+        didReceive challenge: URLAuthenticationChallenge
+    ) async -> (URLSession.AuthChallengeDisposition, URLCredential?) {
+        let method = challenge.protectionSpace.authenticationMethod
+        if method == NSURLAuthenticationMethodClientCertificate {
+            let proof = URLCredential(identity: clientIdentity,
+                                      certificates: issuerChain,
+                                      persistence: .forSession)
+            return (.useCredential, proof)
+        }
+        if method == NSURLAuthenticationMethodServerTrust {
+            if let serverTrust = challenge.protectionSpace.serverTrust,
+               SecTrustEvaluateWithError(serverTrust, nil) {
+                return (.useCredential, URLCredential(trust: serverTrust))
             }
-            completionHandler(.useCredential, URLCredential(trust: trust))
-
-        default:
-            completionHandler(.performDefaultHandling, nil)
+            return (.cancelAuthenticationChallenge, nil)
         }
+        return (.performDefaultHandling, nil)
     }
 }
 ```
 
-Client certificate challenges are **session-wide** (`URLSessionDelegate`), not task-specific. Apps must manage certificates within their sandbox  -  they cannot access system-wide certificates installed via MDM.
+`URLSessionDelegate` requires `Sendable`, and `SecIdentity` is not marked
+`Sendable`. The class holds only `let` properties, so `@unchecked Sendable` states
+a guarantee the compiler cannot check.
+
+Client certificate challenges are delivered at the session level
+(`URLSessionDelegate`), not per task. Apps cannot use certificates installed system-wide
+by MDM; only identities in the app's own sandbox are available.
 
-### Certificate chain inspection (backward-compatible)
+Walking the chain across OS versions:
 
 ```swift
-// ✅ CORRECT: Backward-compatible chain inspection
-func certificateChain(from trust: SecTrust) -> [SecCertificate] {
-    if #available(iOS 15.0, macOS 12.0, *) {
-        return SecTrustCopyCertificateChain(trust) as? [SecCertificate] ?? []
-    } else {
-        return (0..<SecTrustGetCertificateCount(trust)).compactMap {
-            SecTrustGetCertificateAtIndex(trust, $0)
-        }
+func certificates(in trust: SecTrust) -> [SecCertificate] {
+    guard #unavailable(iOS 15, macOS 12) else {
+        return (SecTrustCopyCertificateChain(trust) as? [SecCertificate]) ?? []
     }
+    let total = SecTrustGetCertificateCount(trust)
+    return (0..<total).compactMap { SecTrustGetCertificateAtIndex(trust, $0) }
 }
 ```
 
----
-
-## Anti-Patterns AI Code Generators Produce
-
-| Anti-Pattern                                                                  | Risk                                            | Correct Replacement                                                   |
-| ----------------------------------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------- |
-| Using deprecated `SecTrustEvaluate`                                           | No error context, deprecated iOS 13             | `SecTrustEvaluateWithError` or `SecTrustEvaluateAsyncWithError`       |
-| Disabling ATS globally                                                        | Enables trivial MITM, triggers App Store review | `NSAllowsLocalNetworking` for dev; targeted exceptions for production |
-| `SecTrustSetAnchorCertificates` without `SetAnchorCertificatesOnly(_, false)` | Silently disables all system anchors            | Always pair both calls                                                |
-| `SecPolicyCreateSSL` with `nil` hostname                                      | Disables hostname verification  -  MITM vector    | Always pass the actual expected hostname                              |
-| Skipping system trust eval before pin checks                                  | Expired/revoked certs pass pin checks           | Always `SecTrustEvaluateWithError` first, then check pins             |
-| Using `SecTrustGetCertificateAtIndex`                                         | Deprecated iOS 15                               | `SecTrustCopyCertificateChain` (with backward-compat fallback)        |
-| Using `SecTrustCopyPublicKey`                                                 | Deprecated iOS 14                               | `SecCertificateCopyKey` or `SecTrustCopyKey`                          |
-| SPKI hashing without ASN.1 header                                             | Produces wrong hash, pins never match           | Prepend correct ASN.1 SPKI header before SHA-256                      |
-| Evaluating trust on `.main` queue                                             | UI freezes during network-dependent checks      | Always use background dispatch queue                                  |
-
-```xml
-<!-- ❌ DANGEROUS: Never ship this -->
-<key>NSAppTransportSecurity</key>
-<dict>
-    <key>NSAllowsArbitraryLoads</key>
-    <true/>
-</dict>
-
-<!-- ✅ CORRECT: Local networking only for development -->
-<key>NSAppTransportSecurity</key>
-<dict>
-    <key>NSAllowsLocalNetworking</key>
-    <true/>
-</dict>
-```
-
----
-
-## Backup Pins, Rotation, and Graceful Degradation
-
-**Always include at least two pins.** A single pin means any certificate revocation, CA compromise, or unplanned key rotation bricks your app's networking.
-
-**Backup strategy**: pre-generate a backup key pair, compute its SPKI hash, include it as a pin  -  without deploying the corresponding certificate. If the primary key is compromised, issue a certificate for the backup key server-side. The app already trusts it.
-
-**When all pins fail**: display a clear error that server credentials could not be verified, switch to offline/cached mode, **never allow the user to bypass the pin**, log for diagnostics. Recovery requires an App Store update (consumer apps) or MDM profile update (managed deployments).
-
-**OWASP's current nuanced position**: pinning should only be done when you control both client and server, can update the pinset securely, and have a clear rotation strategy. Certificate Transparency (enforced on Apple platforms since iOS 12.1.1) plus Apple's revocation infrastructure provides substantial protection without pinning's operational risk.
-
----
-
-## ATS Interaction Points
-
-ATS enforces TLS 1.2+, 2048-bit RSA or 256-bit ECC keys, SHA-256+ hashing, AES-128/256, and forward secrecy on all `URLSession` connections.
-
-**iOS 17 change**: ATS now requires HTTPS for connections to bare IP addresses (not just domain names).
-
-Keys that trigger additional App Store review: `NSAllowsArbitraryLoads`, `NSAllowsArbitraryLoadsForMedia`, `NSAllowsArbitraryLoadsInWebContent`, `NSExceptionAllowsInsecureHTTPLoads`, `NSExceptionMinimumTLSVersion`.
-
-Use `nscurl --ats-diagnostics https://your-server.com` on macOS to diagnose ATS compatibility.
-
----
-
-## API Deprecation Timeline
-
-| OS Version           | Year | Key Changes                                                                            |
-| -------------------- | ---- | -------------------------------------------------------------------------------------- |
-| iOS 12 / macOS 10.14 | 2018 | `SecTrustEvaluateWithError` introduced; Certificate Transparency enforced (iOS 12.1.1) |
-| iOS 13 / macOS 10.15 | 2019 | `SecTrustEvaluateAsyncWithError` introduced; `SecTrustEvaluate` deprecated             |
-| iOS 14 / macOS 11    | 2020 | **`NSPinnedDomains`** introduced; `SecTrustCopyKey` replaces `SecTrustCopyPublicKey`   |
-| iOS 15 / macOS 12    | 2021 | **`SecTrustCopyCertificateChain`** replaces `SecTrustGetCertificateAtIndex`/`Count`    |
-| iOS 17 / macOS 14    | 2023 | ATS enforced for IP addresses; EAP-TLS 1.3 support                                     |
-| iOS 18 / macOS 15    | 2024 | Swift 6 strict concurrency affects callback-based Security code; no new SecTrust APIs  |
-
----
-
-## Thread Safety and Performance
-
-- SecTrust objects are thread-safe only **across different instances**. Never access the same `SecTrust` from multiple threads.
-- Different `SecTrust` objects can be evaluated concurrently on different threads.
-- On iOS, all Certificate/Key/Trust Services functions are thread-safe and reentrant.
-- On macOS, trust evaluation can **block on user interaction** (keychain unlock dialogs)  -  always evaluate on background threads.
-- `SecTrust`, `SecCertificate`, and `SecKey` are **not** marked `Sendable`. With Swift 6 strict concurrency, use `@unchecked Sendable` wrappers or explicit actor isolation.
-
----
-
-## CI/CD Guardrails
-
-- **Fail builds** if `NSAllowsArbitraryLoads` is `true` in production `Info.plist`.
-- **Validate** that `SecPolicyCreateSSL` is never called with a `nil` hostname in production code paths.
-- **Enforce** that any `NSPinnedDomains` entry contains at least two SPKI hashes (backup pin requirement).
-- **Scan** for deprecated APIs: `SecTrustEvaluate(`, `SecTrustGetCertificateAtIndex(`, `SecTrustCopyPublicKey(`.
-- **Test** pinning with certificate rotation in staging before production deployment.
-
----
-
-## Cross-References
-
-- `keychain-item-classes.md`  -  `kSecClassCertificate` and `kSecClassIdentity` storage, PKCS#12 import patterns
-- `keychain-fundamentals.md`  -  SecItem CRUD patterns for certificate and identity persistence
-- `cryptokit-public-key.md`  -  PEM/DER key interoperability, curve selection for client certificates
-- `compliance-owasp-mapping.md`  -  M5 (Insecure Communication) trust evaluation requirements
-
----
-
-## WWDC and Reference Citations
-
-- **WWDC 2017 Session 709**  -  "Your Apps and Evolving Network Security Standards" (ATS, CT, pinning guidance)
-- **Apple Developer Documentation**  -  "Evaluating a Trust and Parsing the Result", `SecTrustEvaluateAsyncWithError`, `NSPinnedDomains`
-- **Apple Platform Security Guide**  -  Revocation infrastructure, Certificate Transparency
-- **Apple News Article**  -  "Identity Pinning: How to configure server certificates for your app"
-- **OWASP Pinning Cheat Sheet**  -  Strategy recommendations, backup pin guidance
-- **OWASP MASTG**  -  Certificate pinning test cases
-
----
-
-## Summary Checklist
-
-1. **Trust evaluation uses modern API**  -  `SecTrustEvaluateWithError` (sync) or `SecTrustEvaluateAsyncWithError` (async); no deprecated `SecTrustEvaluate`
-2. **Trust evaluation runs off main thread**  -  background dispatch queue for async; URLSession delegate callbacks already off-main for sync
-3. **Pinning strategy avoids leaf certificates**  -  use SPKI hash pinning, intermediate CA pinning, or `NSPinnedDomains`; never pin raw leaf certificate bytes in production
-4. **At least two pins configured**  -  primary + backup from different CA or pre-generated backup key pair
-5. **System trust evaluated before pin checks**  -  always call `SecTrustEvaluateWithError` first, then compare SPKI hashes; never skip chain validation
-6. **SPKI hashing includes ASN.1 header**  -  prepend correct algorithm-specific header before SHA-256 hashing raw key bytes from `SecKeyCopyExternalRepresentation`
-7. **Custom anchors preserve system trust**  -  `SecTrustSetAnchorCertificates` paired with `SecTrustSetAnchorCertificatesOnly(_, false)` unless intentionally restricting
-8. **SSL policy binds hostname**  -  `SecPolicyCreateSSL` always receives actual expected hostname, never `nil`
-9. **ATS not globally disabled**  -  no `NSAllowsArbitraryLoads: true` in production; use targeted exceptions (`NSAllowsLocalNetworking`, per-domain exceptions)
-10. **Chain inspection uses current APIs**  -  `SecTrustCopyCertificateChain` (iOS 15+) with fallback to `SecTrustGetCertificateAtIndex` for older targets; `SecCertificateCopyKey` not `SecTrustCopyPublicKey`
-11. **Client certificate passwords not bundled**  -  PKCS#12 passwords prompted at runtime or stored in Keychain, never hardcoded or embedded in app bundle
+Storing certificates and identities in the Keychain is covered in
+[keychain-item-classes.md](keychain-item-classes.md).
+
+## Mistakes to reject in review
+
+| Mistake | Fix |
+| --- | --- |
+| Result-code `SecTrustEvaluate`, gone since iOS 13 | The error-returning sync call, or its async sibling |
+| `NSAllowsArbitraryLoads: true` globally; opens MITM and draws App Review questions | `NSAllowsLocalNetworking` for development, narrow per-domain exceptions in production |
+| Custom anchors without `SecTrustSetAnchorCertificatesOnly(_, false)` | Always pair them |
+| `SecPolicyCreateSSL` with a nil hostname | Pass the real hostname |
+| Pin check without system evaluation, so expired or revoked certificates pass | Evaluate first, then pin |
+| Index-based chain access, retired in iOS 15 | Copy the whole chain as an array; keep the index path only for older systems |
+| Copying the public key from the trust the pre-iOS 14 way | Take it from the certificate, or use `SecTrustCopyKey` |
+| SPKI hash computed without the ASN.1 header | Prepend the header; otherwise nothing matches |
+| Trust evaluation on the main queue | Background queue; the UI freezes otherwise |
+
+## Backup pins and rotation
+
+- Always pin at least two keys. With a single pin, a revocation, a CA compromise or an
+  unplanned key change takes networking down.
+- Backup strategy: generate a spare key pair ahead of time and pin its SPKI hash
+  without deploying any certificate for it. If the primary is compromised, get a
+  certificate issued for the spare key.
+- If every pin fails: show a clear verification error, fall back to offline or cached
+  content, never offer a bypass, and log the event. Recovery is an App Store update or
+  an updated MDM configuration profile.
+- OWASP's guidance is that pinning pays off only for teams that own the server end as
+  well as the app, have a safe channel for shipping new pins, and have rehearsed key
+  rotation. Certificate Transparency (enforced since
+  iOS 12.1.1) together with Apple's revocation checking protects well without the
+  operational risk of pinning.
+
+## Where ATS meets trust
+
+- ATS requires, for every `URLSession` connection: TLS 1.2 or later, RSA keys of at
+  least 2048 bits or ECC of at least 256 bits, SHA-256 or stronger certificate
+  signatures, AES-128 or AES-256, and forward secrecy.
+- From iOS 17, ATS also requires HTTPS when connecting to a bare IP address.
+- Keys that draw App Review scrutiny: `NSAllowsArbitraryLoads`,
+  `NSAllowsArbitraryLoadsForMedia`, `NSAllowsArbitraryLoadsInWebContent`,
+  `NSExceptionAllowsInsecureHTTPLoads`, `NSExceptionMinimumTLSVersion`.
+- Diagnose on a Mac with `nscurl --ats-diagnostics https://api.example.com`.
+
+## API timeline
+
+| Release | Change |
+| --- | --- |
+| iOS 12 / macOS 10.14 | `SecTrustEvaluateWithError`; Certificate Transparency enforced (12.1.1) |
+| iOS 13 / macOS 10.15 | `SecTrustEvaluateAsyncWithError`; `SecTrustEvaluate` deprecated |
+| iOS 14 / macOS 11 | `NSPinnedDomains`; `SecTrustCopyKey` replaces `SecTrustCopyPublicKey` |
+| iOS 15 / macOS 12 | `SecTrustCopyCertificateChain` replaces `SecTrustGetCertificateAtIndex` and `SecTrustGetCertificateCount` |
+| iOS 17 / macOS 14 | Connections to literal IPs fall under ATS; TLS 1.3 for EAP |
+| iOS 18 / macOS 15 | Trust API unchanged; the Swift 6 language mode makes the closure-based Security calls harder to adopt |
+
+## Threads and performance
+
+- Do not use one `SecTrust` from several threads at once. Separate instances can be
+  evaluated in parallel.
+- On iOS the whole family of certificate, key and trust functions may be called from
+  any thread, including reentrantly.
+- On macOS, evaluation can wait on user interaction such as a keychain unlock dialog;
+  always evaluate in the background.
+- None of the trust, certificate or key reference types conforms to `Sendable`. In
+  Swift 6 mode, confine them to an actor or wrap them in an `@unchecked Sendable` box whose use you control.
+
+## CI guardrails
+
+- Fail the build when a production `Info.plist` sets `NSAllowsArbitraryLoads` to true.
+- Block any SSL policy created without a hostname outside test targets.
+- Require at least two SPKI hashes for every `NSPinnedDomains` entry.
+- Flag `SecTrustEvaluate(`, `SecTrustGetCertificateAtIndex(` and
+  `SecTrustCopyPublicKey(`.
+- Exercise pinning through a certificate rotation in staging.
+
+## Related and sources
+
+[keychain-item-classes.md](keychain-item-classes.md) for storing certificates,
+identities and PKCS#12 material; [keychain-fundamentals.md](keychain-fundamentals.md);
+[cryptokit-public-key.md](cryptokit-public-key.md) for PEM/DER and curve choice for
+client keys. OWASP M5 (insecure communication) and MASVS-NETWORK are mapped in
+[compliance-owasp-mapping.md](compliance-owasp-mapping.md).
+
+Sources: WWDC17 session 701 on network security standards; Apple's documentation
+pages on trust evaluation and result parsing, on `SecTrustEvaluateAsyncWithError` and
+on `NSPinnedDomains`; the Apple Platform Security Guide; the Apple developer news post
+on identity pinning; the OWASP pinning cheat sheet; OWASP MASTG.
+
+## Checklist
+
+- [ ] Only current evaluation APIs.
+- [ ] Evaluation runs off the main thread.
+- [ ] No leaf pinning; SPKI, intermediate CA or `NSPinnedDomains`.
+- [ ] At least two pins (a second CA or a pre-generated backup key).
+- [ ] System trust evaluated before pins are checked.
+- [ ] SPKI hashes include the ASN.1 header.
+- [ ] Custom anchors keep system roots unless restriction is intended.
+- [ ] SSL policies always carry the hostname.
+- [ ] ATS not disabled globally; only targeted exceptions.
+- [ ] `SecTrustCopyCertificateChain` (iOS 15+) with a fallback; `SecCertificateCopyKey`
+      instead of `SecTrustCopyPublicKey`.
+- [ ] No PKCS#12 passphrases in the bundle.