SecureVault — Zero-Knowledge iOS Password Manager & Cryptographic Vault

A native iOS zero-knowledge credential vault built with SwiftUI, Apple CryptoKit (AES-256-GCM), Hardware Keychain, Face ID / Touch ID Biometrics, and k-Anonymity breach detection.

---

Table of Contents

• Overview
• Threat Model & Security Architecture
• Cryptographic Primitives
• Key Features
• k-Anonymity Breach Detection
• Tech Stack
• Project Structure
• Getting Started
• Author & License

---

Overview

SecureVault is an offline-first, privacy-focused iOS credential manager. Designed around zero-knowledge principles, the application guarantees that sensitive credentials never leave the physical device and are never written to disk in plaintext. All secrets are encrypted at rest using authenticated symmetric ciphers and guarded behind hardware-level biometric authentication.

Core Guarantees

• Zero-Knowledge Architecture: No telemetry, no remote servers, and no analytics SDKs. All data remains exclusively on-device.
• Authenticated Encryption at Rest: Every record is encrypted via AES-256-GCM before database insertion.
• Hardware-Backed Key Derivation: Master cryptographic keys are stored securely inside Apple's Keychain with restricted device-only accessibility.

---

Threat Model & Security Architecture

flowchart TD
    subgraph AuthLayer["Authentication & Key Management"]
        Biometrics["Face ID / Touch ID
(LocalAuthentication)"]
        Passcode["Master Passcode
(AppLockManager)"]
        Keychain["Apple Keychain Services
(kSecAttrAccessibleWhenUnlockedThisDeviceOnly)"]
        SymmetricKey["256-Bit Symmetric Key
(CryptoKit.SymmetricKey)"]
    end

    subgraph CryptoEngine["Cryptographic Layer (EncryptionManager.swift)"]
        Plaintext["Plaintext Secret
(Password / Notes)"]
        AESGCM["AES-256-GCM Seal
(CryptoKit.AES.GCM)"]
        SealedBox["Combined Ciphertext
(Nonce + Ciphertext + Tag)"]
    end

    subgraph StorageLayer["Persistence Layer (CoreDataManager.swift)"]
        CoreDataDB["Encrypted CoreData SQLite Store
(PasswordEntity / CategoryEntity)"]
    end

    subgraph AuditLayer["Privacy-Preserving Audit (k-Anonymity)"]
        SHA1Engine["Local SHA-1 Hash Generator"]
        RangeAPI["HaveIBeenPwned Range API
(Sends ONLY 5-char prefix)"]
    end

    Biometrics & Passcode -->|Unlocks Key| Keychain
    Keychain --> SymmetricKey
    Plaintext --> AESGCM
    SymmetricKey --> AESGCM
    AESGCM --> SealedBox
    SealedBox --> CoreDataDB
    Plaintext -.->|Audit Check| SHA1Engine
    SHA1Engine -.->|Prefix Request| RangeAPI

Loading

---

Cryptographic Primitives

Component	Implementation	Security Standard
Symmetric Cipher	CryptoKit.AES.GCM	256-bit Key, Authenticated Galois/Counter Mode (AEAD)
Key Storage	Apple Keychain Services	kSecClassGenericPassword with device-only binding
Authentication	LocalAuthentication	Biometric Face ID / Touch ID hardware policy
Integrity Verification	128-bit Authentication Tag	Embedded in AES.GCM.SealedBox to prevent tampering
Breach Audit	k-Anonymity SHA-1 Prefixing	Zero-exposure remote hash lookup via HTTPS

---

Key Features

1. Hardware-Backed AES-256-GCM Encryption

• Symmetric keys are generated dynamically via cryptographic random number generators (SymmetricKey(size: .bits256)).
• Data integrity and confidentiality are verified simultaneously; any unauthorized database modification causes decryption failure via AEAD tag validation.

2. Multi-Tier Biometric Lockout & Auto-Lock

• Seamless biometric gating with instant fallback to master numeric passcode.
• Background lifecycle monitor (AppLockManager) that automatically purges decrypted keys from memory and locks the interface whenever the application transitions to the background or reaches inactivity timeouts.

3. Real-Time Password Strength & Entropy Analysis

• Live evaluation of password complexity based on character diversity (lowercase, uppercase, numbers, symbols) and length thresholds.
• Visual strength categorizer (Very Weak, Weak, Moderate, Strong).

4. Categorized Local Vault Management

• Structured classification supporting Work, Personal, Social, Banking, and Custom categories.
• Core Data cascade deletion rules ensuring clean relational cleanup of orphaned records.

---

k-Anonymity Breach Detection

To check whether a stored credential has appeared in known public data breaches without leaking the password, SecureVault implements mathematical k-Anonymity:

1. The password is locally hashed using SHA-1: $$ ext{Hash} = ext{SHA1}( ext{Password}) = exttt{5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8}$$
2. The hash is split into a 5-character prefix and a 35-character suffix:
   • Prefix: 5BAA6
   • Suffix: 1E4C9B93F3F0682250B6CF8331B7EE68FD8
3. SecureVault queries the HaveIBeenPwned Range API with only the prefix: GET https://api.pwnedpasswords.com/range/5BAA6
4. The server returns a list of hundreds of candidate hash suffixes that share that prefix.
5. SecureVault locally checks if the user's suffix exists in the list. The remote server never learns the user's password or full hash.

---

Tech Stack

• Language: Swift 5.9+
• UI Framework: SwiftUI
• Cryptography: Apple CryptoKit (AES-256-GCM, SymmetricKey, Insecure.SHA1)
• Key Storage: Apple Keychain Services (Security.framework)
• Biometrics: LocalAuthentication (LAContext)
• Persistence: Core Data (NSPersistentContainer)
• Target Platform: iOS 16.0+ (iPhone)

---

Project Structure

SecureVault/
├── SecureVaultApp.swift             # App Lifecycle & Environment Setup
├── PersistenceController.swift      # CoreData Stack & Container Provider
├── Models/                          # Domain Data Models
│   ├── Password.swift               # In-Memory Password Model
│   ├── PasswordEntity+CoreDataClass.swift
│   └── CategoryEntity+CoreDataClass.swift
├── ViewModels/                      # MVVM State Providers
│   ├── AuthenticationViewModel.swift# Biometric & Passcode State
│   ├── PasswordListViewModel.swift  # Vault Records & Filter Logic
│   └── CategoryViewModel.swift      # Category Management ViewModel
├── Managers/                        # Cryptographic & Security Services
│   ├── EncryptionManager.swift      # AES-256-GCM Seal & Open Engine
│   ├── KeychainManager.swift        # Keychain Key Read/Write Provider
│   ├── AuthenticationManager.swift  # LocalAuthentication Face ID Bridge
│   ├── AppLockManager.swift         # Auto-Lock & Session Inactivity Timer
│   └── CoreDataManager.swift        # Encrypted CoreData CRUD Operations
├── Utilities/                       # Security & UI Helpers
│   ├── PwnedPasswordChecker.swift   # k-Anonymity Breach Verification Engine
│   ├── PasswordStrengthChecker.swift# Entropy & Regex Analyzer
│   ├── EmailBreachChecker.swift     # Email Exposure Verification
│   ├── CategoryStyle.swift          # Category Colors & SF Symbols
│   └── DataSeeder.swift             # Mock Data for Previews
├── Views/                           # SwiftUI Presentation Views
│   ├── RootView.swift               # Dynamic Lock/Unlock Presentation Switcher
│   ├── AuthenticationView.swift     # Biometric & Passcode Challenge Interface
│   ├── PasswordListView.swift       # Filterable Credential Vault Dashboard
│   ├── PasswordDetailView.swift     # Decrypted Credential Inspector
│   ├── AddPasswordView.swift        # Credential Creation Interface
│   ├── EditPasswordView.swift       # Credential Modification Interface
│   ├── CategoryManagerView.swift    # Category Configuration Interface
│   └── SettingsView.swift           # Auto-Lock & Passcode Settings
├── SecureVaultTests/                # Unit Tests (Crypto & Models)
└── SecureVaultUITests/              # UI Automation Tests

---

Getting Started

Prerequisites

• macOS Ventura (13.0+) or macOS Sonoma (14.0+)
• Xcode 15.0+ or Xcode 16.0+
• iOS 16.0+ Simulator or Physical iPhone (Face ID requires physical device or simulated biometrics)

Installation

1. Clone the repository:

   git clone https://github.com/a360n/SecureVault.git
   cd SecureVault

2. Open in Xcode:

   open SecureVault.xcodeproj

3. Build & Run:

   • Select an iPhone simulator (e.g., iPhone 15 Pro).
   • Press Cmd + R to compile and run.
   • For Face ID testing on simulator: Use Features -> Face ID -> Enrolled and Matching Face.

---

Author

Ali Nasser (Ali Al-Khazali)

• Portfolio: www.ali-nasser.dev
• GitHub: @a360n
• LinkedIn: Ali Nasser

---

License

This project is licensed under the MIT License — see the LICENSE file for details.