Files

4.8 KiB

Security Architecture

iOS Health Sync implements defense-in-depth security for health data transfer.

Threat Model

  • Network eavesdropping - Mitigated by TLS encryption
  • MITM attacks - Mitigated by certificate pinning (TOFU)
  • Token theft - Mitigated by Keychain storage
  • SSRF attacks - Mitigated by local network host validation
  • Replay attacks - Mitigated by time-limited pairing codes

TLS Certificate Management

iOS Server (CertificateService.swift)

Self-signed ECDSA P-256 certificate generated on first run:

struct TLSIdentity {
    let identity: SecIdentity
    let certificateData: Data
    let fingerprint: String  // SHA256 hex
}

// Keychain storage
private static let keyTag = "org.mvneves.healthsync.tlskey"
private static let certLabel = "HealthSync Local TLS"

Key generation priority:

  1. Secure Enclave (if available) - hardware-backed
  2. Software keychain - kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly

Certificate fields:

  • Subject: CN=HealthSync Local
  • Validity: 365 days from generation
  • Algorithm: ECDSA with SHA256

macOS Client (Certificate Pinning)

SHA256 fingerprint pinning via URLSessionDelegate:

final class PinnedSessionDelegate: NSObject, URLSessionDelegate {
    private let expectedFingerprint: String

    func urlSession(_ session: URLSession,
                    didReceive challenge: URLAuthenticationChallenge,
                    completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void) {
        guard let trust = challenge.protectionSpace.serverTrust,
              let certificate = (SecTrustCopyCertificateChain(trust) as? [SecCertificate])?.first else {
            completionHandler(.cancelAuthenticationChallenge, nil)
            return
        }

        let data = SecCertificateCopyData(certificate) as Data
        let fingerprint = SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined()

        if fingerprint == expectedFingerprint {
            completionHandler(.useCredential, URLCredential(trust: trust))
        } else {
            completionHandler(.cancelAuthenticationChallenge, nil)
        }
    }
}

Token Storage

iOS Server (SwiftData)

Tokens are hashed (SHA256) and stored in SwiftData, NOT Keychain:

// PairedDevice model (SwiftData)
@Model
final class PairedDevice {
    var tokenHash: String      // SHA256 of token (never plaintext)
    var expiresAt: Date
    var isActive: Bool
    var lastSeenAt: Date?
}

// Token hashing in PairingService
private static func hashToken(_ token: String) -> String {
    let digest = SHA256.hash(data: Data(token.utf8))
    return digest.map { String(format: "%02x", $0) }.joined()
}

Note: Keychain is used for TLS private key storage (CertificateService), not tokens.

macOS CLI (Keychain)

enum KeychainStore {
    private static let service = "org.mvneves.healthsync.cli"

    static func saveToken(_ token: String, for host: String) throws {
        let account = "token-\(host)"
        let addQuery: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrService as String: service,
            kSecAttrAccount as String: account,
            kSecValueData as String: tokenData,
            kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlocked
        ]
        // ...
    }
}

Local Network Validation

Prevents SSRF by restricting hosts to local network:

func isLocalNetworkHost(_ host: String) -> Bool {
    // Allow: localhost, *.local domains
    // Allow: 192.168.*, 10.*, 172.16-31.*
    // Allow: ::1, fe80::*
    // Reject: all others
}

Pairing Security

QR Code Payload

{
  "version": "1",
  "host": "192.168.1.42",
  "port": 8443,
  "code": "random-one-time-code",
  "expiresAt": "2026-01-07T12:05:00Z",
  "certificateFingerprint": "sha256-hex"
}

Validations performed:

  1. Version check (forward compatibility)
  2. Host must be local network
  3. Code must not be expired (5 min TTL)
  4. Fingerprint stored for future connections

Token Exchange

POST /api/v1/pair
{
  "code": "one-time-code",
  "clientName": "MacBook Pro"
}

Response:
{
  "token": "bearer-token",
  "expiresAt": "2026-01-14T00:00:00Z"
}

Audit Logging

All health data access is logged via AuditService:

actor AuditService {
    private static let retentionDays: Int = 90

    func record(eventType: String, details: [String: String]) async {
        // Persisted to SwiftData
        // Auto-purged after 90 days
    }
}

Logged events:

  • health.read - Data fetch requests
  • health.types - Type enumeration
  • pairing.request - New pairing attempts
  • pairing.success - Successful pairings

Privacy rules:

  • No PII in logs
  • Request IDs for correlation
  • os.Logger with privacy annotations