@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swift-security/references/compliance-owasp-mapping.md

@@ -1,573 +1,366 @@
-# Compliance & OWASP Mapping Reference
+# OWASP Mobile Compliance for Apple Platforms
 
-> Scope: Maps Apple-platform client security patterns to OWASP Mobile Top 10 (2024), MASVS, and MASTG controls for audit and remediation workflows.
+This file connects everyday iOS security code with three OWASP documents as they stand for 2024 to 2026: the 2024 Mobile Top 10, the MASVS at version 2.1.0, and the MASTG. It concentrates on the four categories this skill owns: M1, M3, M9 and M10.
 
-**Most AI code generators still cite the 2016 OWASP Mobile Top 10 numbering  -  "M2: Insecure Data Storage," "M5: Insufficient Cryptography"  -  which was completely replaced in 2024.** This reference maps current iOS security practices to the OWASP Mobile Top 10 (2024), MASVS v2.1.0, and MASTG test cases for the 2024-2026 compliance window. It covers the four categories most relevant to Keychain & Security work: M1 (Improper Credential Usage), M3 (Insecure Authentication/Authorization), M9 (Insecure Data Storage), and M10 (Insufficient Cryptography). Cybernews analysis of 156,080 iOS apps (March 2025) found 71% leak at least one hardcoded secret  -  CISA/FBI jointly classified hardcoded credentials as a "dangerous" bad practice (CWE-798) in January 2025.
+Generated code and older audit templates still quote the 2016 list, for example calling data storage "M2" or cryptography "M5". The 2024 list replaced that numbering completely.
 
----
+The stakes are well documented. A March 2025 scan of 156,080 iOS apps found that 71% leaked at least one hardcoded secret, and the January 2025 joint CISA and FBI guidance on bad product-security practices calls hardcoded credentials (CWE-798) dangerous.
 
-## Contents
-
-- [What Changed: 2016 → 2024 OWASP Mobile Top 10](#what-changed-2016-2024-owasp-mobile-top-10)
-- [Master Traceability Matrix](#master-traceability-matrix)
-- [M1  -  Improper Credential Usage](#m1-improper-credential-usage)
-  - [MASTG Test Cases](#mastg-test-cases)
-  - [Compliant: Keychain credential storage](#compliant-keychain-credential-storage)
-  - [Anti-pattern: common AI-generated credential storage](#anti-pattern-common-ai-generated-credential-storage)
-- [M3  -  Insecure Authentication/Authorization](#m3-insecure-authenticationauthorization)
-  - [MASTG Test Cases](#mastg-test-cases)
-  - [The LAContext Vulnerability](#the-lacontext-vulnerability)
-  - [`.biometryCurrentSet` vs `.biometryAny`](#biometrycurrentset-vs-biometryany)
-  - [Compliant: hardware-bound biometric authentication](#compliant-hardware-bound-biometric-authentication)
-  - [Anti-pattern: LAContext-only authentication](#anti-pattern-lacontext-only-authentication)
-- [M9  -  Insecure Data Storage](#m9-insecure-data-storage)
-  - [iOS Storage Security Properties](#ios-storage-security-properties)
-  - [MASTG Test Cases](#mastg-test-cases)
-  - [NSFileProtection Classes](#nsfileprotection-classes)
-  - [Compliant: file storage with Data Protection](#compliant-file-storage-with-data-protection)
-  - [Anti-pattern: insecure data storage](#anti-pattern-insecure-data-storage)
-- [M10  -  Insufficient Cryptography](#m10-insufficient-cryptography)
-  - [Deprecated vs. Approved Algorithms](#deprecated-vs-approved-algorithms)
-  - [MASTG Test Cases](#mastg-test-cases)
-  - [Compliant: CryptoKit encryption](#compliant-cryptokit-encryption)
-  - [Anti-pattern: insecure cryptography](#anti-pattern-insecure-cryptography)
-- [kSecAttrAccessible Selection Guide](#ksecattraccessible-selection-guide)
-- [Enterprise Audit Workflow](#enterprise-audit-workflow)
-  - [How Security Teams Evaluate iOS Apps](#how-security-teams-evaluate-ios-apps)
-  - [Top 10 Audit Findings](#top-10-audit-findings)
-  - [Evidence Kit (5 Artifacts)](#evidence-kit-5-artifacts)
-  - [Jailbreak-Era Testing (2025-2026)](#jailbreak-era-testing-20252026)
-- [Post-Quantum Cryptography Roadmap](#post-quantum-cryptography-roadmap)
-- [Cross-Reference Index](#cross-reference-index)
-- [Conclusion](#conclusion)
-- [Summary Checklist](#summary-checklist)
-
-## What Changed: 2016 → 2024 OWASP Mobile Top 10
-
-The 2024 edition is a complete overhaul. Four categories are entirely new, two pairs were merged, and everything was renumbered. Any code comment or documentation citing the 2016 numbering is outdated.
-
-| 2024 Category                                 | Status     | 2016 Predecessor   |
-| --------------------------------------------- | ---------- | ------------------ |
-| **M1: Improper Credential Usage**             | New        | None               |
-| **M2: Inadequate Supply Chain Security**      | New        | None               |
-| **M3: Insecure Authentication/Authorization** | Merged     | 2016 M4 + M6       |
-| **M4: Insufficient Input/Output Validation**  | New        | None               |
-| **M5: Insecure Communication**                | Renumbered | 2016 M3            |
-| **M6: Inadequate Privacy Controls**           | New        | None               |
-| **M7: Insufficient Binary Protections**       | Merged     | 2016 M8 + M9       |
-| **M8: Security Misconfiguration**             | Expanded   | 2016 M10 (partial) |
-| **M9: Insecure Data Storage**                 | Renumbered | 2016 M2            |
-| **M10: Insufficient Cryptography**            | Renumbered | 2016 M5            |
-
-**MASVS v2.1.0** (January 18, 2024) reorganized into 8 control groups with concise, testable controls. The old L1/L2/R verification levels became **MAS Testing Profiles** within the MASTG, aligned with NIST OSCAL. Legacy MSTG-\* test IDs (e.g., MSTG-STORAGE-1) were deprecated in favor of new MASTG-TEST-02xx/03xx identifiers with granular, tool-specific test procedures.
-
----
-
-## Master Traceability Matrix
-
-This matrix links each OWASP 2024 category to its MASVS controls, MASTG test cases, iOS APIs, and required audit evidence.
-
-| OWASP 2024                        | MASVS v2 Controls                             | Key MASTG Tests (New IDs)                                        | iOS APIs / Flags                                                                        | Required Evidence                                                   |
-| --------------------------------- | --------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| **M1** Improper Credential Usage  | MASVS-STORAGE-1, MASVS-AUTH-1, MASVS-CRYPTO-2 | 0213, 0214, 0299, 0300, 0302                                     | Keychain + `SecAccessControl`; App Attest                                               | Static scan (no literals); keychain dump with ACL; attestation logs |
-| **M3** Insecure Auth/AuthZ        | MASVS-AUTH-1, MASVS-AUTH-2, MASVS-AUTH-3      | 0266, 0267, 0268, 0269, 0270, 0271                               | `SecAccessControlCreateWithFlags` + `.biometryCurrentSet`; `ASWebAuthenticationSession` | Auth flow diagrams; biometric bypass test results; token TTL policy |
-| **M9** Insecure Data Storage      | MASVS-STORAGE-1, MASVS-STORAGE-2              | 0296, 0297, 0299, 0300, 0301, 0302, 0303, 0215, 0298, 0313, 0314 | Keychain accessibility flags; `NSFileProtectionComplete`; `isExcludedFromBackup`        | `xattr` listings; backup extraction; keychain dump                  |
-| **M10** Insufficient Cryptography | MASVS-CRYPTO-1, MASVS-CRYPTO-2                | 0209, 0210, 0211, 0213, 0214, 0311, 0317                         | CryptoKit `AES.GCM`/`ChaChaPoly`; `SecRandomCopyBytes`; Secure Enclave keys             | Crypto inventory; algorithm audit; unit tests                       |
-
-> **Cross-reference note:** MASVS-STORAGE-1 and MASTG-TEST-0299/0302 appear under both M1 and M9. This is intentional  -  keychain configuration simultaneously addresses credential storage and data-at-rest protection. See `keychain-access-control.md` for detailed accessibility flag guidance.
-
----
-
-## M1  -  Improper Credential Usage
-
-**Scope:** Hardcoded credentials in source/config, insecure credential transmission, insecure on-device storage, weak auth protocols. Attack vectors: EASY. Impact: SEVERE. Entirely new in 2024  -  no 2016 predecessor.
-
-**Cybernews 2025 data:** 815,000+ hardcoded secrets across 156,080 iOS apps (average 5.2 per app), including 19 Stripe secret keys, 836 unprotected cloud endpoints exposing 406TB, and 2,218 misconfigured Firebase endpoints leaking 19.8M records. Secrets found in plaintext IPA files without decompilation.
-
-### MASTG Test Cases
-
-| Test ID         | Legacy ID      | Verifies                                              | Profile |
-| --------------- | -------------- | ----------------------------------------------------- | ------- |
-| MASTG-TEST-0213 | MSTG-CRYPTO-1  | No hardcoded cryptographic keys in source/binary      | L1, L2  |
-| MASTG-TEST-0214 | MSTG-CRYPTO-5  | No cryptographic keys in bundle files (plist, config) | L1, L2  |
-| MASTG-TEST-0299 | MSTG-STORAGE-1 | Files use appropriate Data Protection classes         | L1      |
-| MASTG-TEST-0300 | MSTG-STORAGE-1 | Static: references to APIs storing unencrypted data   | L2      |
-| MASTG-TEST-0302 | MSTG-STORAGE-2 | Sensitive data unencrypted in private storage         | L2      |
-
-**Testing procedure:** Use radare2 for static analysis  -  search for `SecKeyCreateWithData` with hardcoded key data or CryptoKit key initialization with inline bytes. Use objection (`ios keychain dump`, `ios nsuserdefaults get`) and filesystem grep at runtime. Check `.xcconfig`, `Info.plist`, and embedded resources for API keys.
-
-**App Attest (iOS 14+):** Closes the secret provisioning gap by verifying device integrity before the server issues credentials. This avoids hardcoded secrets entirely  -  the server provisions secrets only to attested, genuine app instances. See `credential-storage-patterns.md` for implementation details.
-
-### Compliant: Keychain credential storage
-
-```swift
-import Security
-
-/// Stores a credential securely in the iOS Keychain.
-/// Compliance: OWASP M1 (Improper Credential Usage), MASVS-STORAGE-1
-/// Test cases: MASTG-TEST-0213, MASTG-TEST-0299
-/// iOS 8.0+ (SecAccessControlCreateWithFlags), iOS 11.3+ (.biometryCurrentSet)
-func storeCredential(account: String, secret: Data, service: String) throws {
-    // ✅ CORRECT  -  secrets are persisted in Keychain with explicit access control
-    // Delete existing item first to avoid errSecDuplicateItem
-    let deleteQuery: [String: Any] = [
-        kSecClass as String: kSecClassGenericPassword,
-        kSecAttrAccount as String: account,
-        kSecAttrService as String: service
-    ]
-    SecItemDelete(deleteQuery as CFDictionary)
-
-    var error: Unmanaged<CFError>?
-    guard let accessControl = SecAccessControlCreateWithFlags(
-        kCFAllocatorDefault,
-        kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
-        .biometryCurrentSet,
-        &error
-    ) else {
-        throw error!.takeRetainedValue() as Error
-    }
-
-    let query: [String: Any] = [
-        kSecClass as String: kSecClassGenericPassword,
-        kSecAttrAccount as String: account,
-        kSecAttrService as String: service,
-        kSecAttrAccessControl as String: accessControl,
-        kSecValueData as String: secret
-    ]
-
-    let status = SecItemAdd(query as CFDictionary, nil)
-    guard status == errSecSuccess else {
-        throw NSError(domain: NSOSStatusErrorDomain, code: Int(status))
-    }
-}
-```
-
-### Anti-pattern: common AI-generated credential storage
-
-```swift
-// ❌ WRONG  -  UserDefaults writes to UNENCRYPTED plist at:
-//   <AppSandbox>/Library/Preferences/<BundleID>.plist
-// Extractable via iTunes backup, iMazing, or objection
-UserDefaults.standard.set(apiToken, forKey: "auth_token")
+Related: [keychain-access-control.md](keychain-access-control.md), [credential-storage-patterns.md](credential-storage-patterns.md), [biometric-authentication.md](biometric-authentication.md), [cryptokit-symmetric.md](cryptokit-symmetric.md), [cryptokit-public-key.md](cryptokit-public-key.md), [common-anti-patterns.md](common-anti-patterns.md).
 
-// ❌ WRONG  -  Hardcoded API key in source (found in 71% of iOS apps)
-let stripeKey = "sk_live_EXAMPLE_KEY_DO_NOT_USE"
-
-// ❌ WRONG  -  Secret in Info.plist (plaintext in IPA archive)
-// <key>API_SECRET</key><string>my-secret-key-12345</string>
-
-// ❌ WRONG  -  NSKeyedArchiver to Documents directory (no encryption)
-let data = try NSKeyedArchiver.archivedData(
-    withRootObject: credentials, requiringSecureCoding: true)
-try data.write(to: documentsURL.appendingPathComponent("creds.dat"))
-```
-
-**Why these fail audits:** objection `ios nsuserdefaults get` reveals UserDefaults instantly. MobSF flags hardcoded key patterns. Backup extraction exposes Documents directory. All fail MASTG-TEST-0213 and MASTG-TEST-0302.
-
----
+## Contents
 
-## M3  -  Insecure Authentication/Authorization
+- [2016 to 2024: what moved](#2016-to-2024-what-moved)
+- [Traceability matrix](#traceability-matrix)
+- [M1 Improper Credential Usage](#m1-improper-credential-usage)
+- [M3 Insecure Authentication/Authorization](#m3-insecure-authenticationauthorization)
+- [M9 Insecure Data Storage](#m9-insecure-data-storage)
+- [M10 Insufficient Cryptography](#m10-insufficient-cryptography)
+- [Choosing kSecAttrAccessible](#choosing-ksecattraccessible)
+- [Running an enterprise audit](#running-an-enterprise-audit)
+- [Post-quantum roadmap](#post-quantum-roadmap)
+- [Cross-reference index](#cross-reference-index)
+- [Takeaways](#takeaways)
+- [Checklist](#checklist)
 
-**Scope:** Merges 2016 M4 + M6. Covers remote server-side auth, local biometric auth, and client-only authorization. Attack vectors: EASY. Impact: SEVERE. Critical iOS risk: LAContext-only biometric auth is bypassable via Frida in under 10 seconds.
+## 2016 to 2024: what moved
 
-### MASTG Test Cases
+| 2024 category | Origin |
+| --- | --- |
+| M1 Improper Credential Usage | Added in 2024 |
+| M2 Inadequate Supply Chain Security | Added in 2024 |
+| M3 Insecure Authentication/Authorization | Merges 2016 M4 and M6 |
+| M4 Insufficient Input/Output Validation | Added in 2024 |
+| M5 Insecure Communication | Was 2016 M3 |
+| M6 Inadequate Privacy Controls | Added in 2024 |
+| M7 Insufficient Binary Protections | Merges 2016 M8 and M9 |
+| M8 Security Misconfiguration | Broadens part of 2016 M10 |
+| M9 Insecure Data Storage | Was 2016 M2 |
+| M10 Insufficient Cryptography | Was 2016 M5 |
 
-| Test ID         | Legacy ID   | Verifies                                                      | Profile |
-| --------------- | ----------- | ------------------------------------------------------------- | ------- |
-| MASTG-TEST-0266 | MSTG-AUTH-8 | Static: references to `LAContext.evaluatePolicy`              | L2      |
-| MASTG-TEST-0267 | MSTG-AUTH-8 | Dynamic: runtime event-based biometric auth (bypassable)      | L2      |
-| MASTG-TEST-0268 | MSTG-AUTH-8 | Static: APIs allowing fallback to non-biometric auth          | L2      |
-| MASTG-TEST-0269 | MSTG-AUTH-8 | Dynamic: runtime fallback to non-biometric auth               | L2      |
-| MASTG-TEST-0270 | MSTG-AUTH-8 | Static: `.biometryCurrentSet` for enrollment change detection | L2      |
-| MASTG-TEST-0271 | MSTG-AUTH-8 | Dynamic: enrollment change detection enforced at runtime      | L2      |
+MASVS v2.1.0, published 18 January 2024, has eight control groups. The old L1, L2 and R verification levels moved into the MASTG as MAS Testing Profiles aligned with NIST OSCAL, and the legacy `MSTG-*` test identifiers are deprecated in favour of `MASTG-TEST-02xx` and `MASTG-TEST-03xx`.
 
-### The LAContext Vulnerability
+## Traceability matrix
 
-`LAContext.evaluatePolicy` performs a software-only biometric check returning a Boolean in the completion handler. This Boolean executes in user space and is hookable by Frida to always return `true`. The Secure Enclave performs the biometric match, but the result is a plain callback with no cryptographic proof of authentication.
+| Category | Apple APIs | Evidence | MASTG tests | MASVS controls |
+| --- | --- | --- | --- | --- |
+| M1 | Keychain with `SecAccessControl`, App Attest | Static scan with no secret literals, keychain dump showing the ACL, attestation logs | 0213, 0214, 0299, 0300, 0302 | STORAGE-1, AUTH-1, CRYPTO-2 |
+| M3 | `SecAccessControlCreateWithFlags` with `.biometryCurrentSet`, `ASWebAuthenticationSession` | Auth flow diagrams, biometric bypass results, token lifetime policy | 0266 to 0271 | AUTH-1, AUTH-2, AUTH-3 |
+| M9 | Keychain accessibility classes, `NSFileProtectionComplete`, `isExcludedFromBackup` | `xattr` listings, backup extraction, keychain dump | 0215, 0296, 0297, 0298, 0299, 0300, 0301, 0302, 0303, 0313, 0314 | STORAGE-1, STORAGE-2 |
+| M10 | `AES.GCM`, `ChaChaPoly`, `SecRandomCopyBytes`, Secure Enclave keys | Crypto inventory, algorithm audit, unit tests | 0209, 0210, 0211, 0213, 0214, 0311, 0317 | CRYPTO-1, CRYPTO-2 |
 
-**Frida bypass (< 10 lines):**
+Some identifiers are listed twice deliberately. MASVS-STORAGE-1 plus tests 0299 and 0302 belong to M1 as well as M9, because a credential sitting in plaintext is a credential problem and a storage problem at once.
 
-```javascript
-// Forces LAContext.evaluatePolicy to always succeed
-if (ObjC.available) {
-  var hook = ObjC.classes.LAContext["- evaluatePolicy:localizedReason:reply:"];
-  Interceptor.attach(hook.implementation, {
-    onEnter: function (args) {
-      var block = new ObjC.Block(args[4]);
-      const appCallback = block.implementation;
-      block.implementation = function (error, value) {
-        return appCallback(1, null); // Force success=true
-      };
-    },
-  });
-}
-```
+## M1 Improper Credential Usage
 
-**objection one-liner:** `ios ui biometrics_bypass`  -  hooks `evaluatePolicy` to return `true`.
+Covers credentials hardcoded in source or configuration, sent insecurely, stored insecurely on the device, or used with weak authentication protocols. Exploitability: easy. Impact: severe. There is no 2016 predecessor.
 
-The correct pattern ties secrets to Keychain items protected by `SecAccessControlCreateWithFlags`. The Secure Enclave holds the decryption key and will not release it without valid biometric authentication. There is no Boolean to hook  -  failed biometrics means the data is cryptographically inaccessible.
+The same 2025 scan counted more than 815,000 secrets (an average above five per app). Among them were 19 live payment-provider secret keys, 836 unprotected cloud storage endpoints exposing about 406 TB, and 2,218 misconfigured backend-as-a-service database endpoints leaking 19.8 million records. All of it was read straight out of IPA files.
 
-### `.biometryCurrentSet` vs `.biometryAny`
+| Profile | MASTG test | What it checks | Legacy ID |
+| --- | --- | --- | --- |
+| L1, L2 | 0213 | Keys embedded in source or the binary | MSTG-CRYPTO-1 |
+| L1, L2 | 0214 | Keys in bundled resource files | MSTG-CRYPTO-5 |
+| L1 | 0299 | Which protection class each item uses | MSTG-STORAGE-1 |
+| L2 | 0300 | Code that calls plaintext storage APIs | MSTG-STORAGE-1 |
+| L2 | 0302 | Secrets found in clear in the private container | MSTG-STORAGE-2 |
 
-| Flag                  | Behavior                                              | Security                                             | iOS   |
-| --------------------- | ----------------------------------------------------- | ---------------------------------------------------- | ----- |
-| `.biometryCurrentSet` | Item invalidated if new biometric enrolled            | **Recommended**  -  prevents enrollment-change attacks | 11.3+ |
-| `.biometryAny`        | Accessible with any enrolled biometric, even new ones | Lower  -  attacker can add their own fingerprint       | 11.3+ |
-| `.userPresence`       | Biometry OR passcode (system chooses)                 | Allows passcode fallback                             | 8.0+  |
-| `.devicePasscode`     | Passcode only                                         | No biometric option                                  | 9.0+  |
+How testers look: radare2 over the binary for `SecKeyCreateWithData` fed with constant bytes or CryptoKit keys built from inline data; `objection` with `ios keychain dump` and `ios nsuserdefaults get`; a grep of the extracted file system; and a read through `.xcconfig` files, `Info.plist` and every embedded resource.
 
-For high-security items, always use `.biometryCurrentSet`. If an attacker adds their fingerprint to a stolen device, `.biometryAny` items become accessible; `.biometryCurrentSet` items are permanently invalidated. See `biometric-authentication.md` for full implementation patterns.
+App Attest (iOS 14 and later) closes the provisioning gap: the server hands secrets only to instances it has attested as genuine (see the `device-integrity` skill).
 
-### Compliant: hardware-bound biometric authentication
+Compliant storage of a credential:
 
 ```swift
-import LocalAuthentication
 import Security
 
-/// Hardware-bound biometric auth using Keychain + Secure Enclave.
-/// Compliance: OWASP M3 (Insecure Auth), MASVS-AUTH-2
-/// Test cases: MASTG-TEST-0266, MASTG-TEST-0270
-/// iOS 11.3+ (.biometryCurrentSet)
-/// Canonical pattern with full error handling: biometric-authentication.md section The Secure Pattern  -  Hardware-Bound Secrets
-
-// STEP 1: Store secret with biometric protection
-func storeBiometricProtectedSecret(account: String, secret: Data) throws {
-    // ✅ CORRECT  -  Secure Enclave gates secret release through keychain ACLs
-    var error: Unmanaged<CFError>?
-    guard let accessControl = SecAccessControlCreateWithFlags(
-        kCFAllocatorDefault,
-        kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
-        .biometryCurrentSet,
-        &error
-    ) else {
-        throw error!.takeRetainedValue() as Error
+// MASTG-TEST-0299, 0300 | MASVS-AUTH-1, MASVS-STORAGE-1 | OWASP M1, M9
+// SecAccessControlCreateWithFlags: iOS 8.0+, .biometryCurrentSet: iOS 11.3+
+func storeSigningSecret(_ secret: Data, account: String) throws {
+    guard let acl = SecAccessControlCreateWithFlags(nil,
+            kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly, .biometryCurrentSet, nil) else {
+        throw KeychainFailure(errSecParam)
     }
-
-    let query: [String: Any] = [
-        kSecClass as String: kSecClassGenericPassword,
-        kSecAttrAccount as String: account,
-        kSecAttrService as String: "com.app.biometric-auth",
-        kSecAttrAccessControl as String: accessControl,
-        kSecValueData as String: secret
-    ]
-
-    let status = SecItemAdd(query as CFDictionary, nil)
-    guard status == errSecSuccess else {
-        throw NSError(domain: NSOSStatusErrorDomain, code: Int(status))
+    let identity: [CFString: Any] = [kSecClass: kSecClassGenericPassword,
+                                     kSecAttrService: "com.example.treasury",
+                                     kSecAttrAccount: account]
+    var insert = identity
+    insert[kSecValueData] = secret
+    insert[kSecAttrAccessControl] = acl
+    var status = SecItemAdd(insert as CFDictionary, nil)
+    if status == errSecDuplicateItem {
+        status = SecItemUpdate(identity as CFDictionary, [kSecValueData: secret] as CFDictionary)
     }
-}
-
-// STEP 2: Retrieve  -  Secure Enclave enforces biometric check
-func retrieveBiometricProtectedSecret(account: String) throws -> Data? {
-    let context = LAContext()
-    context.localizedReason = "Authenticate to access your account"
-
-    let query: [String: Any] = [
-        kSecClass as String: kSecClassGenericPassword,
-        kSecAttrAccount as String: account,
-        kSecAttrService as String: "com.app.biometric-auth",
-        kSecUseAuthenticationContext as String: context,
-        kSecReturnData as String: true
-    ]
-
-    var result: AnyObject?
-    let status = SecItemCopyMatching(query as CFDictionary, &result)
-    guard status == errSecSuccess else { return nil }
-    return result as? Data
+    guard status == errSecSuccess else { throw KeychainFailure(status) }
 }
 ```
 
-### Anti-pattern: LAContext-only authentication
-
-```swift
-// ❌ WRONG  -  #2 most common iOS audit finding
-// Bypassable: objection -g com.app explore -> ios ui biometrics_bypass
-let context = LAContext()
-context.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics,
-                       localizedReason: "Log in") { success, error in
-    if success {
-        // ❌ This Boolean is hookable  -  no cryptographic proof
-        self.showMainScreen()  // Attacker gains full access
-    }
-}
-```
+`KeychainFailure` is a small error type wrapping the `OSStatus`. Add first and update on `errSecDuplicateItem`. Deleting and re-adding is reserved for changing the access control of an existing item.
 
----
+Findings that fail MASTG-TEST-0213 and 0302:
 
-## M9  -  Insecure Data Storage
+- A token in `UserDefaults`, which lands in `<AppSandbox>/Library/Preferences/<BundleID>.plist`.
+- A live payment secret (`sk_live_...`) as a Swift literal.
+- A secret stored as an `Info.plist` value.
+- Credentials written with `NSKeyedArchiver` into `Documents`, which backups include.
 
-**Scope:** All vulnerabilities in how apps store sensitive data: weak/no encryption, accessible locations, insufficient access controls, unintentional leakage (logs, caches, backups). Was M2 in 2016  -  renumbered to M9 (priority shift, not diminished importance).
+`objection` and MobSF find all four within minutes, and a plain backup extraction exposes everything in `Documents`.
 
-### iOS Storage Security Properties
+## M3 Insecure Authentication/Authorization
 
-| Storage Location                           | Encrypted          | In Backups     | Accessible w/o Jailbreak | Verdict                         |
-| ------------------------------------------ | ------------------ | -------------- | ------------------------ | ------------------------------- |
-| Keychain (`WhenPasscodeSetThisDeviceOnly`) | ✅ AES-256-GCM     | ❌             | ❌                       | ✅ Use for secrets              |
-| Keychain (`AfterFirstUnlock`)              | ✅                 | ✅ (encrypted) | ❌                       | ⚠️ Acceptable for L1            |
-| `NSFileProtectionComplete` files           | ✅ (when locked)   | ✅             | ❌                       | ✅ Use for sensitive files      |
-| UserDefaults                               | ❌ Plaintext plist | ✅             | ✅ (via backup)          | ❌ Never for secrets            |
-| Documents/ (default protection)            | ✅ (Class C)       | ✅             | ✅ (via backup)          | ❌ Not without extra encryption |
-| SQLite/CoreData (no SQLCipher)             | ❌                 | ✅             | ✅ (via backup)          | ❌ Not for secrets              |
-| NSLog output                               | ❌                 | N/A            | ✅ (Console.app)         | ❌ Never log secrets            |
+Merges 2016 M4 and M6: remote authentication, local biometric authentication, and authorization decided only on the client. Exploitability: easy. Impact: severe. A biometric check done with `LAContext` alone falls to Frida in under ten seconds.
 
-**Keychain persistence note:** Keychain items survive app uninstall and persist across install/uninstall cycles (confirmed since iOS 10.3). Only factory reset clears them. Exception: `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly` items are deleted when the passcode is removed.
+| MASTG test | Type | Checks |
+| --- | --- | --- |
+| 0266 | Static | References to `evaluatePolicy` used as the gate |
+| 0267 | Dynamic | Event-based authentication that can be bypassed |
+| 0268 | Static | APIs that fall back to non-biometric authentication |
+| 0269 | Dynamic | Fallback behaviour at runtime |
+| 0270 | Static | Use of `.biometryCurrentSet` |
+| 0271 | Dynamic | Enforcement after an enrolment change |
 
-### MASTG Test Cases
+All six replace legacy MSTG-AUTH-8 and belong to the L2 profile.
 
-| Test ID         | Legacy ID      | Verifies                                          | Profile |
-| --------------- | -------------- | ------------------------------------------------- | ------- |
-| MASTG-TEST-0299 | MSTG-STORAGE-1 | Data Protection classes for private storage files | L1      |
-| MASTG-TEST-0300 | MSTG-STORAGE-1 | Static: references to unencrypted storage APIs    | L2      |
-| MASTG-TEST-0301 | MSTG-STORAGE-1 | Dynamic: runtime use of unencrypted storage       | L2      |
-| MASTG-TEST-0302 | MSTG-STORAGE-2 | Sensitive data unencrypted in private storage     | L2      |
-| MASTG-TEST-0296 | MSTG-STORAGE-3 | Sensitive data in logs                            | L1, L2  |
-| MASTG-TEST-0297 | MSTG-STORAGE-3 | Insertion of sensitive data into log statements   | L1, L2  |
-| MASTG-TEST-0215 | MSTG-STORAGE-8 | Sensitive data not excluded from backup           | L1, L2  |
-| MASTG-TEST-0313 | MSTG-STORAGE-5 | APIs preventing keyboard caching                  | L1, L2  |
+The match itself happens in the Secure Enclave, but `evaluatePolicy` returns a plain `Bool` to user space with no cryptographic proof attached, so a Frida script of fewer than ten lines, or `objection`'s `ios ui biometrics_bypass`, changes the answer.
 
-### NSFileProtection Classes
+| Flag | Behaviour | Recommendation | Available from |
+| --- | --- | --- | --- |
+| `.biometryCurrentSet` | Invalidated when enrolment changes | Recommended | iOS 11.3 |
+| `.biometryAny` | Any enrolled biometric, including ones added later | Weaker | iOS 11.3 |
+| `.userPresence` | Biometrics or device passcode | General use | iOS 8.0 |
+| `.devicePasscode` | Passcode only | Passcode-only flows | iOS 9.0 |
 
-| Class               | Constant                                               | Accessible When                                   | Default? |
-| ------------------- | ------------------------------------------------------ | ------------------------------------------------- | -------- |
-| A: Complete         | `NSFileProtectionComplete`                             | Only when unlocked; key discarded ~10s after lock | No       |
-| B: Unless Open      | `NSFileProtectionCompleteUnlessOpen`                   | Already-open files remain accessible when locked  | No       |
-| C: Until First Auth | `NSFileProtectionCompleteUntilFirstUserAuthentication` | After first unlock, even when locked              | **Yes**  |
-| D: None             | `NSFileProtectionNone`                                 | Always; protected only by device UID              | No       |
+Use `.biometryCurrentSet` for anything valuable. With `.biometryAny`, a thief who knows the passcode can enrol their own finger or face and then unlock the item.
 
-### Compliant: file storage with Data Protection
+Compliant pattern: store as in the M1 example, then read with an `LAContext` passed through `kSecUseAuthenticationContext`. A short compliance snippet may simply return nil on any failure; the full read with status handling is in [biometric-authentication.md](biometric-authentication.md).
 
 ```swift
-import Foundation
-
-/// Writes sensitive data with Complete file protection.
-/// Compliance: OWASP M9 (Insecure Data Storage), MASVS-STORAGE-1
-/// Test cases: MASTG-TEST-0299
-/// iOS 9.0+ (.completeFileProtection option)
-func writeProtectedFile(data: Data, to url: URL) throws {
-    try data.write(to: url, options: [.atomic, .completeFileProtection])
-}
+import LocalAuthentication
 
-/// Excludes a file from device backups.
-/// Compliance: MASVS-STORAGE-2, MASTG-TEST-0215
-/// iOS 5.1+
-func excludeFromBackup(url: URL) throws {
-    var resourceURL = url
-    var resourceValues = URLResourceValues()
-    resourceValues.isExcludedFromBackup = true
-    try resourceURL.setResourceValues(resourceValues)
+// OWASP M3 | MASVS-AUTH-2 | MASTG-TEST-0266, 0270
+func readSigningSecret(account: String, reason: String) -> Data? {
+    let context = LAContext()
+    context.localizedReason = reason
+    let lookup: [CFString: Any] = [kSecClass: kSecClassGenericPassword,
+                                   kSecAttrService: "com.example.treasury",
+                                   kSecAttrAccount: account,
+                                   kSecReturnData: true,
+                                   kSecUseAuthenticationContext: context]
+    var out: CFTypeRef?
+    return SecItemCopyMatching(lookup as CFDictionary, &out) == errSecSuccess ? out as? Data : nil
 }
 ```
 
-### Anti-pattern: insecure data storage
-
-```swift
-// ❌ WRONG  -  Unencrypted plist
-UserDefaults.standard.set("Bearer eyJhbGciOiJSUzI1NiIs...", forKey: "authToken")
-
-// ❌ WRONG  -  Default file protection (Class C) for sensitive file
-try sensitiveData.write(to: documentsURL.appendingPathComponent("profile.dat"))
-
-// ❌ WRONG  -  Logging sensitive data (Console.app / idevicesyslog)
-NSLog("User token: %@", authToken)
-print("Password entered: \(password)")
-
-// ❌ WRONG  -  Not excluding sensitive files from backup
-// Files in Documents/ are in iTunes/Finder backups by default
-// Extractable with iMazing on non-jailbroken devices
-```
-
----
+The anti-pattern, showing the main screen when `evaluatePolicy` succeeds, is the second most common finding in iOS audits.
 
-## M10  -  Insufficient Cryptography
+## M9 Insecure Data Storage
 
-**Scope:** Weak algorithms, insufficient key lengths, poor key management, insecure RNG, deprecated hashes. Attack vectors: AVERAGE. Impact: SEVERE. Was M5 in 2016.
+Covers missing or weak encryption, data in reachable locations, weak access control, and leaks through logs, caches and backups. It was M2 in 2016.
 
-### Deprecated vs. Approved Algorithms
+| Storage | Protection | Verdict |
+| --- | --- | --- |
+| Keychain, `WhenPasscodeSetThisDeviceOnly` | Encrypted, never in backups | Use for secrets |
+| Keychain, `AfterFirstUnlock` | Encrypted, included in encrypted backups | Acceptable at L1 |
+| File with `NSFileProtectionComplete` | Encrypted while locked | Use for sensitive files |
+| `UserDefaults` | Plaintext | Never for secrets |
+| `Documents` with the default class | Class C | Not without extra encryption |
+| SQLite or Core Data without SQLCipher | Plaintext database | Not for secrets |
+| `NSLog` output | Visible in Console.app | Never log secrets |
 
-| Category       | ❌ Deprecated/Broken              | ✅ Approved (CryptoKit, iOS 13+)                               |
-| -------------- | --------------------------------- | -------------------------------------------------------------- |
-| Hashing        | MD5, SHA-1 (for security)         | SHA256, SHA384, SHA512; SHA3 (iOS 26+)                         |
-| Symmetric      | DES, 3DES, RC4, Blowfish, AES-ECB | AES.GCM (AES-256-GCM), ChaChaPoly                              |
-| Asymmetric     | RSA < 2048 bits                   | P256, P384, P521, Curve25519, Ed25519                          |
-| Key derivation | Simple SHA hash of password       | HKDF; Argon2/bcrypt/scrypt server-side                         |
-| RNG            | `rand()`, `random()`, `srand()`   | `SecRandomCopyBytes` (iOS 2+), CryptoKit auto-nonces (iOS 13+) |
-| Post-quantum   | All classical PKC (by 2030)       | ML-KEM, ML-DSA, X-Wing (iOS 26+)                               |
+Keychain items outlive the app: that has been the confirmed behaviour since iOS 10.3, and only erasing the device clears them. One exception: items with `WhenPasscodeSetThisDeviceOnly` are deleted when the user removes the device passcode.
 
-**`arc4random()` nuance:** On modern Apple platforms, `arc4random()` uses a CSPRNG internally (not broken RC4). It is technically secure on iOS. However, `SecRandomCopyBytes` remains recommended for explicit cryptographic use  -  its security guarantees are documented and cross-platform portable. See `cryptokit-symmetric.md` for detailed algorithm guidance.
+| Profile | MASTG test | What it checks | Legacy ID |
+| --- | --- | --- | --- |
+| L1 | 0299 | Protection class per item | MSTG-STORAGE-1 |
+| L2 | 0300, 0301 | Plaintext storage APIs, statically and at runtime | MSTG-STORAGE-1 |
+| L2 | 0302 | Secrets left readable in the private container | MSTG-STORAGE-2 |
+| L1, L2 | 0296, 0297 | Secrets written to logs | MSTG-STORAGE-3 |
+| L1, L2 | 0215 | Sensitive files that backups still include | MSTG-STORAGE-8 |
+| L1, L2 | 0313 | Keyboard cache | MSTG-STORAGE-5 |
 
-**AES-GCM nonce reuse is catastrophic:** A single reuse with the same key destroys both confidentiality (XOR of ciphertexts reveals XOR of plaintexts) and authentication (leaks GHASH key `H`, enabling arbitrary forgery). CryptoKit mitigates this by auto-generating random nonces when `AES.GCM.seal()` is called without an explicit nonce.
+File protection classes:
 
-### MASTG Test Cases
+| Class | Constant | Behaviour |
+| --- | --- | --- |
+| A | `NSFileProtectionComplete` | Readable only while unlocked; the key is discarded about 10 seconds after locking |
+| B | `NSFileProtectionCompleteUnlessOpen` | Files already open stay readable after locking |
+| C | `NSFileProtectionCompleteUntilFirstUserAuthentication` | Default; readable from first unlock until reboot |
+| D | `NSFileProtectionNone` | Protected only by the device UID key |
 
-| Test ID         | Legacy ID     | Verifies                                        | Profile |
-| --------------- | ------------- | ----------------------------------------------- | ------- |
-| MASTG-TEST-0209 | MSTG-CRYPTO-2 | Key size meets minimum requirements             | L1, L2  |
-| MASTG-TEST-0210 | MSTG-CRYPTO-2 | No broken symmetric algorithms (DES, 3DES, RC4) | L1, L2  |
-| MASTG-TEST-0211 | MSTG-CRYPTO-3 | No broken hashes (MD5, SHA-1 for security)      | L1, L2  |
-| MASTG-TEST-0317 | MSTG-CRYPTO-3 | No broken encryption modes (ECB)                | L1, L2  |
-| MASTG-TEST-0311 | MSTG-CRYPTO-6 | CSPRNG used (not `rand`/`random`)               | L1, L2  |
-| MASTG-TEST-0213 | MSTG-CRYPTO-1 | No hardcoded cryptographic keys in code         | L1, L2  |
-| MASTG-TEST-0214 | MSTG-CRYPTO-5 | No hardcoded cryptographic keys in files        | L1, L2  |
-
-**iOS-specific testing:** Use radare2 to find references to `kCCAlgorithmDES`, `kCCAlgorithm3DES`, `kCCAlgorithmRC4`, `kCCOptionECBMode` in CommonCrypto calls. Search for `CC_MD5`, `CC_SHA1` or CryptoKit `Insecure.MD5`/`Insecure.SHA1`. MASTG demos: MASTG-DEMO-0015 (CommonCrypto broken hash), MASTG-DEMO-0016 (CryptoKit broken hash), MASTG-DEMO-0018 (broken encryption).
-
-### Compliant: CryptoKit encryption
-
-Canonical full round-trip patterns are in `cryptokit-symmetric.md` and anti-pattern #6 in `common-anti-patterns.md`. This compliance snippet stays minimal to avoid duplicating canonical crypto guidance.
+Compliant file handling:
 
 ```swift
-import CryptoKit
-
-enum CryptoError: Error { case invalidCiphertext }
-
-/// Compliance: OWASP M10 (Insufficient Cryptography), MASVS-CRYPTO-1.
-/// Test cases: MASTG-TEST-0210, MASTG-TEST-0317. iOS 13.0+.
-func sealForStorage(_ plaintext: Data, using key: SymmetricKey) throws -> Data {
-    let sealedBox = try AES.GCM.seal(plaintext, using: key)
-    guard let combined = sealedBox.combined else { throw CryptoError.invalidCiphertext }
-    return combined
+// OWASP M9 | MASVS-STORAGE-1 | MASTG-TEST-0299, 0215
+func persistStatement(_ pdf: Data, to url: URL) throws {
+    try pdf.write(to: url, options: [.completeFileProtection, .atomic])
+    var flags = URLResourceValues()
+    flags.isExcludedFromBackup = true
+    var target = url
+    try target.setResourceValues(flags)
 }
-
-// Compliance: MASVS-CRYPTO-2, MASTG-TEST-0213
-let encryptionKey = SymmetricKey(size: .bits256) // 256-bit from CSPRNG
 ```
 
-### Anti-pattern: insecure cryptography
+`Data.WritingOptions.completeFileProtection` is available from iOS 9.0 and `isExcludedFromBackup` from iOS 5.1.
 
-```swift
-// ❌ WRONG  -  MD5 (collisions trivially constructable)  -  fails MASTG-TEST-0211
-var digest = [UInt8](repeating: 0, count: Int(CC_MD5_DIGEST_LENGTH))
-CC_MD5(data.bytes, CC_LONG(data.count), &digest)
-
-// ❌ WRONG  -  ECB mode  -  fails MASTG-TEST-0317
-CCCrypt(CCOperation(kCCEncrypt), CCAlgorithm(kCCAlgorithmAES),
-        CCOptions(kCCOptionECBMode), key, keyLength, nil, plaintext, ...)
+Anti-patterns: a bearer token in `UserDefaults`; a sensitive file left at the default class C; `NSLog` or `print` of a token or password; sensitive files in `Documents` that end up in backups, where desktop backup tools extract them.
 
-// ❌ WRONG  -  Insecure RNG  -  fails MASTG-TEST-0311
-let seed = srand(UInt32(time(nil)))  // Predictable seed
+## M10 Insufficient Cryptography
 
-// ❌ WRONG  -  Hardcoded key  -  fails MASTG-TEST-0213
-let key = SymmetricKey(data: "my-secret-key-1234567890123456".data(using: .utf8)!)
+Covers weak algorithms, short keys, poor key management, weak randomness and deprecated hashes. Exploitability: average. Impact: severe. It was M5 in 2016.
 
-// ❌ WRONG  -  Static nonce (catastrophic if reused)
-let nonce = try AES.GCM.Nonce(data: Data(repeating: 0, count: 12))
-let sealed = try AES.GCM.seal(data, using: key, nonce: nonce)
-```
+| Area | Deprecated | Use instead |
+| --- | --- | --- |
+| Hashing | MD5, SHA-1 | SHA-256, SHA-384, SHA-512; SHA-3 from iOS 26 |
+| Symmetric | Blowfish, RC4, DES and 3DES, or AES in ECB mode | AES-256-GCM, ChaChaPoly |
+| Asymmetric | RSA below 2048 bits | NIST curves (P-256 up to P-521), Curve25519, Ed25519 |
+| Key derivation | A plain SHA hash of a password | HKDF for keys; Argon2, bcrypt or scrypt on the server for passwords |
+| Randomness | `srand()` seeding, `rand()`, `random()` | `SecRandomCopyBytes` (iOS 2 and later), CryptoKit's automatic nonces (iOS 13 and later) |
+| Post-quantum | Classical public-key crypto alone, deprecated by NIST from 2030 | From iOS 26: ML-KEM, ML-DSA and the X-Wing hybrid |
 
----
+On `arc4random`: on current Apple platforms it is backed by the system cryptographic generator, not RC4, so it is not a finding by itself. What auditors flag is too little entropy (a 32-bit result, a six-digit code) or modulo bias from `% n`. For keys, nonces, salts and tokens, `SecRandomCopyBytes` remains the recommendation because it is documented for cryptographic use, reports failure and makes the intent obvious; [common-anti-patterns.md](common-anti-patterns.md) entry 10 applies the same rule.
 
-## kSecAttrAccessible Selection Guide
+Reusing an AES-GCM nonce destroys confidentiality for the affected messages and leaks the GHASH key H, which enables forgeries. CryptoKit's automatic nonce removes the risk as long as code does not supply its own.
 
-> Complete selection criteria and data protection tier mapping: `keychain-access-control.md` section The "When" Layer: Seven Accessibility Constants. The guidance below is a compliance-focused quick-reference for audit contexts.
+| What it checks | MASTG test | Legacy ID |
+| --- | --- | --- |
+| Key lengths | 0209 | MSTG-CRYPTO-2 |
+| DES, 3DES and RC4 absent | 0210 | MSTG-CRYPTO-2 |
+| Broken hash functions absent | 0211 | MSTG-CRYPTO-3 |
+| ECB mode absent | 0317 | MSTG-CRYPTO-3 |
+| Randomness from a CSPRNG | 0311 | MSTG-CRYPTO-6 |
+| Keys absent from code | 0213 | MSTG-CRYPTO-1 |
+| Keys absent from files | 0214 | MSTG-CRYPTO-5 |
 
-Keychain accessibility is the single most important iOS security decision  -  it simultaneously addresses M1, M3, M9, and M10 requirements.
+All belong to both L1 and L2.
 
-| Constant                                           | Backup | iCloud | Passcode Required       | Use For                                               |
-| -------------------------------------------------- | ------ | ------ | ----------------------- | ----------------------------------------------------- |
-| `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly`  | ❌     | ❌     | ✅ (deleted if removed) | **Highest-sensitivity: auth tokens, encryption keys** |
-| `kSecAttrAccessibleWhenUnlockedThisDeviceOnly`     | ❌     | ❌     | ❌                      | Sensitive data, device-specific                       |
-| `kSecAttrAccessibleWhenUnlocked` (default)         | ✅     | ✅     | ❌                      | General credentials needing sync                      |
-| `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` | ❌     | ❌     | ❌                      | Background-accessible, device-specific                |
-| `kSecAttrAccessibleAfterFirstUnlock`               | ✅     | ✅     | ❌                      | Background tasks (e.g., push notification keys)       |
-| `kSecAttrAccessibleAlways`                         | ✅     | ✅     | ❌                      | **❌ DEPRECATED (iOS 12)  -  never use**                |
+Testing on iOS: radare2 searches for `kCCAlgorithmDES`, `kCCAlgorithm3DES`, `kCCAlgorithmRC4` and `kCCOptionECBMode`, plus `CC_MD5`, `CC_SHA1`, `Insecure.MD5` and `Insecure.SHA1`. MASTG-DEMO-0015 (CommonCrypto hashing), MASTG-DEMO-0016 (CryptoKit hashing) and MASTG-DEMO-0018 (broken encryption) show the expected findings.
 
-**Critical:** `kSecAttrAccessible` and `kSecAttrAccessControl` are mutually exclusive. When using `SecAccessControlCreateWithFlags`, the accessibility level is the function's first parameter  -  do not also set `kSecAttrAccessible` in the query dictionary, or you get `errSecParam (-50)`. See `keychain-access-control.md`.
+```swift
+import CryptoKit
 
-`kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly` is the strictest common choice for high-security credentials because items become unavailable when the passcode is removed. `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` is a safer general default when passcode-removal data loss would surprise users. Choose based on the threat model and recovery plan.
+// MASTG-TEST-0210, 0213, 0317 | MASVS-CRYPTO-1 and -2 | OWASP M10
+let statementKey = SymmetricKey(size: .bits256)
 
----
+func sealStatement(_ plaintext: Data) throws -> Data {
+    let sealed = try AES.GCM.seal(plaintext, using: statementKey)
+    guard let packed = sealed.combined else { throw CryptoKitError.incorrectParameterSize }
+    return packed
+}
+```
 
-## Enterprise Audit Workflow
+The key itself is stored in the keychain, never compiled in.
 
-### How Security Teams Evaluate iOS Apps
+Anti-patterns: `CC_MD5`; `CCCrypt` with `kCCOptionECBMode`; a generator seeded with `srand(time(nil))`; `SymmetricKey(data:)` built from a string literal; a static all-zero nonce.
 
-Auditors evaluate against MAS Testing Profiles: **L1 (standard)** for low-risk apps, **L2 (defense-in-depth)** for apps handling financial, health, or highly sensitive data  -  requiring Keychain-managed encryption, hardware-bound biometrics, and certificate pinning.
+## Choosing kSecAttrAccessible
 
-**Audit tool workflow:** (1) Static analysis  -  MobSF for automated scanning; radare2 for targeted API analysis. (2) Dynamic analysis  -  objection for keychain dumping (`ios keychain dump`), file protection verification, UserDefaults inspection (`ios nsuserdefaults get`), biometric bypass (`ios ui biometrics_bypass`). (3) Network  -  Burp Suite with objection SSL pinning bypass. (4) Binary  -  class-dump/dsdump for method enumeration.
+One accessibility decision touches M1, M3, M9 and M10 at once.
 
-**Key filesystem paths auditors target:** `<Sandbox>/Library/Preferences/<BundleID>.plist` (UserDefaults), `<Sandbox>/Documents/` (databases), `<Sandbox>/Library/Caches/` (web cache), `<Sandbox>/Library/SplashBoard/Snapshots/` (screenshot cache), `<Sandbox>/tmp/` (temporary files with uncleared data).
+| Class | Backup | iCloud Keychain | Condition | Typical use |
+| --- | --- | --- | --- | --- |
+| `WhenPasscodeSetThisDeviceOnly` | No | No | Passcode must be set; item deleted if it is removed | The most sensitive values, such as session tokens and data keys |
+| `WhenUnlockedThisDeviceOnly` | No | No | Device unlocked | Sensitive, device-specific data |
+| `WhenUnlocked` (default) | Yes | Eligible | Device unlocked | General credentials that should sync |
+| `AfterFirstUnlockThisDeviceOnly` | No | No | After first unlock | Background access, device-specific |
+| `AfterFirstUnlock` | Yes | Eligible | After first unlock | Background work such as push-related keys |
+| `Always` | | | Deprecated in iOS 12 | Never |
 
-### Top 10 Audit Findings
+`ThisDeviceOnly` and synchronization exclude each other. Such an item never migrates to another device and never syncs; adding one with `kSecAttrSynchronizable: true` fails with `errSecParam` rather than quietly staying local.
 
-| Rank | Finding                         | OWASP  | MASVS        | MASTG Tests | Severity |
-| ---- | ------------------------------- | ------ | ------------ | ----------- | -------- |
-| 1    | Secrets in UserDefaults/plists  | M1, M9 | STORAGE-1    | 0299, 0302  | Critical |
-| 2    | LAContext-only biometric auth   | M3     | AUTH-2       | 0266, 0267  | High     |
-| 3    | Missing certificate pinning     | M5     | NETWORK-2    | 0244        | High     |
-| 4    | Hardcoded API keys in binary    | M1     | CRYPTO-2     | 0213, 0214  | Critical |
-| 5    | Deprecated crypto (MD5, DES)    | M10    | CRYPTO-1     | 0210, 0211  | High     |
-| 6    | Insecure keychain accessibility | M9     | STORAGE-1    | 0299        | Medium   |
-| 7    | Sensitive data in logs          | M9     | STORAGE-2    | 0296, 0297  | Medium   |
-| 8    | Missing jailbreak detection     | M7     | RESILIENCE-1 |  -            | Low      |
-| 9    | Unencrypted SQLite/Realm        | M9     | STORAGE-1    | 0302        | High     |
-| 10   | ATS exceptions allowing HTTP    | M5     | NETWORK-1    |  -            | Medium   |
+`kSecAttrAccessible` and `kSecAttrAccessControl` are also mutually exclusive in one dictionary. The accessibility value goes into `SecAccessControlCreateWithFlags` as its protection argument, and supplying both attributes returns `errSecParam` (-50).
 
-### Evidence Kit (5 Artifacts)
+Between the two strictest foreground classes, decide by threat model and recovery plan. `WhenPasscodeSetThisDeviceOnly` is stricter; `WhenUnlockedThisDeviceOnly` is the safer default when losing the item on passcode removal would surprise users and there is no way to restore it.
 
-| Artifact               | Proves                                        | OWASP/MASVS |
-| ---------------------- | --------------------------------------------- | ----------- |
-| Static analysis report | No hardcoded secrets or weak crypto           | M1, M10     |
-| Filesystem/xattr log   | `NSFileProtectionComplete` applied            | M9          |
-| Keychain dump          | `ThisDeviceOnly` + `SecAccessControl` present | M1, M9      |
-| Backup extraction      | No sensitive data migrated                    | M9          |
-| Code snippets          | Correct APIs and flags used                   | All         |
+## Running an enterprise audit
 
-### Jailbreak-Era Testing (2025-2026)
+MAS Testing Profiles: L1 is the baseline for low-risk apps. L2 adds defence in depth for financial, health and other highly sensitive apps, and there auditors expect encryption keys held in the keychain, biometrics tied to hardware, and pinned certificates.
 
-As of iOS 26, zero jailbreakable devices exist for current versions. Auditors use non-jailbreak techniques: objection with Frida Gadget injection into repackaged IPAs, Corellium virtual devices, or iMazing for backup extraction. This makes automated static analysis (MobSF, semgrep) and Frida Gadget-based dynamic testing the primary assessment paths.
+Tooling:
 
----
+| Phase | Tools |
+| --- | --- |
+| Static | MobSF, radare2 |
+| Dynamic | `objection`: `ios keychain dump`, file protection checks, `ios nsuserdefaults get`, `ios ui biometrics_bypass` |
+| Network | An intercepting HTTPS proxy, with `objection`'s SSL-pinning bypass to test pinning |
+| Binary | class-dump, dsdump |
 
-## Post-Quantum Cryptography Roadmap
+Paths auditors always open:
 
-Apple announced PQC support at WWDC 2025 (Session 314: "Get ahead with quantum-secure cryptography"). The threat model: "harvest now, decrypt later"  -  adversaries collecting encrypted traffic today for future quantum decryption.
+- `<Sandbox>/Library/Preferences/<BundleID>.plist`
+- `<Sandbox>/Documents/`
+- `<Sandbox>/Library/Caches/`
+- `<Sandbox>/Library/SplashBoard/Snapshots/`
+- `<Sandbox>/tmp/`
 
-| Date                     | Milestone                                                                             |
-| ------------------------ | ------------------------------------------------------------------------------------- |
-| February 2024 (iOS 17.4) | iMessage PQ3  -  first quantum-secure messaging at scale                                |
-| August 2024              | NIST finalizes FIPS 203/204/205                                                       |
-| January 2025             | CISA adds insecure crypto algorithms to bad practices list                            |
-| June 2025 (WWDC)         | CryptoKit PQC APIs announced for iOS 26                                               |
-| September 2025 (iOS 26)  | ML-KEM-768/1024, ML-DSA-65/87, X-Wing KEM in CryptoKit; quantum-secure TLS by default |
-| 2030 (NIST target)       | Classical public-key crypto deprecated                                                |
-| 2035 (CNSA 2.0)          | Classical algorithms disallowed for National Security Systems                         |
+Most frequent findings:
 
-Apple uses hybrid cryptography  -  combining post-quantum and classical algorithms so updates never reduce security below the classical baseline. Build crypto agility now: abstract cryptographic interfaces behind protocols to allow configuration-level switches when PQC adoption becomes mandatory. See `cryptokit-public-key.md` for ML-KEM/ML-DSA implementation details.
+| # | Severity | Finding | MASTG | OWASP | MASVS |
+| --- | --- | --- | --- | --- | --- |
+| 1 | Critical | Secrets in `UserDefaults` or plists | 0299, 0302 | M1, M9 | STORAGE-1 |
+| 2 | High | Biometrics via `LAContext` only | 0266, 0267 | M3 | AUTH-2 |
+| 3 | High | No certificate pinning | 0244 | M5 | NETWORK-2 |
+| 4 | Critical | Hardcoded keys | 0213, 0214 | M1 | CRYPTO-2 |
+| 5 | High | Deprecated crypto | 0210, 0211 | M10 | CRYPTO-1 |
+| 6 | Medium | Weak keychain accessibility | 0299 | M9 | STORAGE-1 |
+| 7 | Medium | Sensitive data in logs | 0296, 0297 | M9 | STORAGE-2 |
+| 8 | Low | No jailbreak detection | none listed | M7 | RESILIENCE-1 |
+| 9 | High | Unencrypted SQLite or other embedded database | 0302 | M9 | STORAGE-1 |
+| 10 | Medium | ATS exceptions allowing HTTP | none listed | M5 | NETWORK-1 |
 
----
+Evidence to hand over:
 
-## Cross-Reference Index
+| Artefact | Covers |
+| --- | --- |
+| Static analysis report | M1, M10 |
+| File system or `xattr` listing proving `NSFileProtectionComplete` | M9 |
+| Keychain dump showing `ThisDeviceOnly` classes and `SecAccessControl` | M1, M9 |
+| Backup extraction containing no sensitive data | M9 |
+| Code excerpts showing the APIs and flags in use | All |
 
-| iOS Practice                                              | M1  | M3  | M9  | M10              | Primary Reference                |
-| --------------------------------------------------------- | --- | --- | --- | ---------------- | -------------------------------- |
-| Keychain + `WhenPasscodeSetThisDeviceOnly`                | ✅  |  -    | ✅  | ✅ (key storage) | `keychain-access-control.md`     |
-| `SecAccessControlCreateWithFlags` + `.biometryCurrentSet` | ✅  | ✅  | ✅  |  -                 | `biometric-authentication.md`    |
-| CryptoKit AES.GCM with auto-nonce                         |  -    |  -    | ✅  | ✅               | `cryptokit-symmetric.md`         |
-| `NSFileProtectionComplete`                                |  -    |  -    | ✅  |  -                 | `keychain-access-control.md`     |
-| `SecRandomCopyBytes` for key/token generation             | ✅  | ✅  |  -    | ✅               | `cryptokit-symmetric.md`         |
-| App Attest for credential provisioning                    | ✅  | ✅  |  -    |  -                 | `credential-storage-patterns.md` |
-| ML-KEM/ML-DSA (iOS 26+)                                   |  -    |  -    |  -    | ✅               | `cryptokit-public-key.md`        |
+Current iOS 26 releases have no public jailbreak. Dynamic testing therefore relies on Frida Gadget injected into a re-signed IPA together with `objection`, on virtualized iOS devices, or on backup extraction. Static analysis with MobSF or semgrep plus Gadget-based dynamic testing is now the primary approach.
 
----
+## Post-quantum roadmap
 
-## Conclusion
+WWDC 2025 session 314 introduced CryptoKit's post-quantum APIs. The driving threat is "harvest now, decrypt later": traffic recorded today is decrypted once a large quantum computer exists.
 
-Three patterns emerge from this mapping. First, the Keychain is the universal compliance mechanism on iOS  -  a single correctly configured `SecItemAdd` with `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly` and `.biometryCurrentSet` simultaneously satisfies M1, M3, and M9. Second, any reference to "M2: Insecure Data Storage" or "M5: Insufficient Cryptography" flags outdated 2016 guidance. Third, the MASTG transition to new test IDs (MASTG-TEST-02xx/03xx) means legacy MSTG-\* references in code comments should be updated.
+| Date | Event |
+| --- | --- |
+| February 2024 | iOS 17.4 ships PQ3 for iMessage |
+| August 2024 | NIST finalises FIPS 203, 204 and 205 |
+| January 2025 | CISA lists insecure cryptography as a bad practice |
+| June 2025 | CryptoKit post-quantum APIs announced |
+| September 2025 | iOS 26 ships ML-KEM-768 and ML-KEM-1024, ML-DSA-65 and ML-DSA-87, X-Wing, and post-quantum TLS by default |
+| 2030 | NIST deprecates classical public-key algorithms |
+| 2035 | CNSA 2.0 disallows classical algorithms for National Security Systems |
 
-For 2025-2026, the most consequential change is post-quantum cryptography reaching production iOS. With NIST targeting 2030 for classical PKC deprecation and Apple shipping ML-KEM/ML-DSA in iOS 26 with quantum-secure TLS enabled by default, compliance programs should evaluate hybrid cryptographic strategies now.
+Apple deploys hybrid schemes, so security never falls below today's classical level even if a new algorithm is weakened. Apps should build crypto agility the same way: keep algorithm choices behind a protocol so ML-KEM or ML-DSA can replace a classical primitive without touching callers.
 
----
+## Cross-reference index
 
-## Summary Checklist
+| Control | Categories | Details in |
+| --- | --- | --- |
+| Keychain with `WhenPasscodeSetThisDeviceOnly` | M1, M9, and M10 for stored keys | [keychain-access-control.md](keychain-access-control.md) |
+| `SecAccessControlCreateWithFlags` with `.biometryCurrentSet` | M1, M3, M9 | [biometric-authentication.md](biometric-authentication.md) |
+| `AES.GCM` with automatic nonces | M9, M10 | [cryptokit-symmetric.md](cryptokit-symmetric.md) |
+| `NSFileProtectionComplete` | M9 | This file |
+| `SecRandomCopyBytes` | M1, M3, M10 | [common-anti-patterns.md](common-anti-patterns.md) |
+| App Attest before provisioning secrets | M1, M3 | [credential-storage-patterns.md](credential-storage-patterns.md) |
+| ML-KEM, ML-DSA | M10 | [cryptokit-public-key.md](cryptokit-public-key.md) |
 
-1. **OWASP 2024 numbering**  -  All references use 2024 numbering (M1/M3/M9/M10), not 2016 (M2/M5/M4+M6)
-2. **MASTG test IDs**  -  References use new MASTG-TEST-02xx/03xx IDs (not legacy MSTG-\* only)
-3. **Keychain-only credential storage**  -  Credentials stored in Keychain with `ThisDeviceOnly` accessibility, never in UserDefaults/plists/files
-4. **Keychain-bound biometrics**  -  Authentication uses `SecAccessControlCreateWithFlags` + `.biometryCurrentSet`, not LAContext-only
-5. **No dual access control**  -  `kSecAttrAccessible` and `kSecAttrAccessControl` are never set simultaneously in the same query
-6. **CryptoKit algorithms**  -  All cryptographic operations use CryptoKit (iOS 13+) or SecKey  -  no CommonCrypto deprecated algorithms (MD5, DES, 3DES, RC4, ECB)
-7. **Automatic nonces**  -  AES-GCM encryption relies on CryptoKit auto-nonces; no manual nonce construction without a documented rotation strategy
-8. **File protection**  -  Sensitive files use `NSFileProtectionComplete` and are excluded from backup via `isExcludedFromBackup`
-9. **No sensitive logging**  -  No sensitive data appears in `NSLog`/`print` statements or keyboard caches (`.autocorrectionType = .no`, `.isSecureTextEntry = true`)
-10. **Compliance annotations**  -  Code comments include OWASP category, MASVS control, and MASTG test case IDs
-11. **Post-quantum readiness**  -  Cryptographic interfaces are abstracted behind protocols enabling future ML-KEM/ML-DSA adoption
+## Takeaways
+
+A single well-formed keychain write, with `WhenPasscodeSetThisDeviceOnly` and `.biometryCurrentSet`, satisfies M1, M3 and M9 together. Guidance that files storage under M2 or cryptography under M5 was written for the 2016 list, and code comments citing `MSTG-*` identifiers should move to `MASTG-TEST` identifiers. With NIST's 2030 date and post-quantum TLS on by default in iOS 26, compliance programmes should assess hybrid post-quantum strategies now.
+
+## Checklist
+
+- [ ] Findings and comments use 2024 category numbers only.
+- [ ] Test references use `MASTG-TEST-02xx` and `03xx` identifiers.
+- [ ] Credentials live only in the keychain, with a `ThisDeviceOnly` class unless they are meant to sync.
+- [ ] Biometrics unlock keychain items protected with `.biometryCurrentSet`.
+- [ ] No dictionary sets both `kSecAttrAccessible` and `kSecAttrAccessControl`.
+- [ ] Cryptography uses CryptoKit or `SecKey`; no MD5, DES, 3DES, RC4 or ECB.
+- [ ] Nonces come from CryptoKit; any manual nonce has a documented uniqueness scheme.
+- [ ] Sensitive files use `NSFileProtectionComplete` and `isExcludedFromBackup`.
+- [ ] No sensitive values in logs; secure fields set `.autocorrectionType = .no` and `.isSecureTextEntry = true` to keep them out of the keyboard cache.
+- [ ] Comments on security-relevant code name the MASTG test, the MASVS control and the OWASP category they satisfy.
+- [ ] Crypto sits behind protocols so ML-KEM and ML-DSA can be adopted without rewriting callers.