User Data Restoration

How GetTrusted Restores User Data.

Overview

We do not backup or restore enterprise data, we filter it out as managed personas and managed contacts can be recovered and should only be recovered through enterprise onboarding/recovery.

GetTrusted's Restore Flow enables automatic recovery of encrypted backups when a user recovers their identity on a new device. The system uses the same Backup Encryption Key (BEK) that was deterministically derived during identity recovery to decrypt and restore all user data (contacts, personas, trust attestations) with zero server-side decryption.

Key Security Features:

• Automatic BEK Availability: BEK already derived and stored during identity recovery

• Hardware-Backed BEK Storage: BEK retrieved from iOS Keychain/Android KeyStore

• Zero-Knowledge Server: Backend retrieves encrypted blobs from S3, never sees plaintext

• Master ID Verification: Backup Master ID must match recovered identity

• Nuclear Table Clearing: Complete database wipe before restoration (clean slate)

• Device ID Injection: New device's device_id injected into restored records

• GZIP Decompression: Automatic decompression of compressed backup data

• AES-256-GCM Decryption: Authenticated decryption with nonce-based security

Process Overview

Alice recovers her identity on a new phone using her passphrase and QR recovery data. The SDK automatically downloads and restores her encrypted backup from AWS S3, giving her immediate access to all contacts, personas, and trust attestations.

Alice's Perspective (User Recovering on New Device)

1

Identity recovery + BEK derivation

Alice recovers identity using passphrase + QR recovery data. The SDK derives the same BEK during identity recovery using HKDF-SHA256(master_id, SHA256(passphrase), "personal_bek_v1") and stores the BEK in the hardware keychain (gettrusted_bek_personal).

2

Check for backup and download

SDK checks for backup via backend API. SDK downloads the encrypted blob from S3 (zero-knowledge retrieval).

3

BEK retrieval and decryption

SDK retrieves BEK from secure storage (no user interaction). SDK decrypts and decompresses backup data (AES-256-GCM decryption + GZIP decompression).

4

Master ID verification

SDK verifies the Backup Master ID matches the recovered identity. If mismatch, abort with MasterIdMismatch error.

5

Nuclear table clearing

SDK clears existing tables (DELETE FROM contacts, personas, trust_attestations) to provide a clean slate for restoration.

6

Device ID injection & restore

SDK injects the new device_id into all restored records and regenerates created_at/updated_at timestamps. Restored records are inserted into the local database.

7

Restoration summary & completion

App shows restoration summary (contacts, personas, attestations). Alice sees all data restored and ready to use immediately.

Backend Perspective (GetTrusted API + AWS Services)

1

Receive and authenticate restore request

Restore request arrives with user_id. Backend validates the JWT token (device signature verification) and extracts the user fingerprint from the Master ID.

2

Query backup metadata

Backend queries Firestore metadata for backup existence and metadata (fingerprint, s3Key, size, exportedAt).

3

Download blob from S3

Backend downloads the encrypted blob from S3 (GET object Key: backups/{fingerprint}/backup.bin). The backend never decrypts the blob (zero-knowledge).

4

Return encrypted blob to device

Backend returns the encrypted blob and metadata to the mobile device. Mobile SDK handles decryption; backend never sees plaintext.

Process Flow Diagram

sequenceDiagram
    participant New Device
    participant Secure Enclave
    participant GetTrusted Backend
    participant AWS S3
    participant Firestore
    participant SQLite Database

    Note over New Device,SQLite Database: Phase 1: Identity Recovery (Prerequisite)
    New Device->>New Device: User enters passphrase + QR recovery data
    New Device->>Secure Enclave: Derive Master ID from recovery data
    Secure Enclave-->>New Device: Master ID (32 bytes)
    New Device->>New Device: Derive BEK from Master ID + passphrase<br/>HKDF-SHA256(master_id, SHA256(passphrase), "personal_bek_v1")
    New Device->>Secure Enclave: Store BEK in keychain<br/>(gettrusted_bek_personal)
    Secure Enclave-->>New Device: BEK stored successfully
    Note right of New Device: Identity recovery complete<br/>BEK now available for backup restore

    Note over New Device,SQLite Database: Phase 2: Check for Backup Existence
    New Device->>GetTrusted Backend: POST /api/v1/backup/cloud/restore<br/>{user_id}<br/>JWT token for authentication
    GetTrusted Backend->>GetTrusted Backend: Validate JWT signature
    GetTrusted Backend->>GetTrusted Backend: Extract fingerprint from user_id<br/>(strip 'gtm' prefix)

    Note over New Device,SQLite Database: Phase 3: Retrieve Backup Metadata
    GetTrusted Backend->>Firestore: GET /backups/{user_id}
    Firestore-->>GetTrusted Backend: {fingerprint, s3Key, size, exportedAt}

    Note over New Device,SQLite Database: Phase 4: Download Encrypted Blob from S3
    GetTrusted Backend->>AWS S3: GET object<br/>Key: backups/{fingerprint}/backup.bin
    AWS S3-->>GetTrusted Backend: Encrypted backup blob<br/>[version:1][nonce:12][ciphertext+tag]

    GetTrusted Backend-->>New Device: {success: true, encrypted_backup_blob, metadata}
    Note right of GetTrusted Backend: Zero-knowledge: backend never sees plaintext

    Note over New Device,SQLite Database: Phase 5: BEK Retrieval from Keychain
    New Device->>Secure Enclave: Retrieve BEK from keychain<br/>(stored during identity recovery)
    Secure Enclave-->>New Device: BEK (32 bytes)
    Note right of Secure Enclave: Hardware-protected keychain storage<br/>No user interaction needed

    Note over New Device,SQLite Database: Phase 6: Decryption with AES-256-GCM
    New Device->>New Device: Parse encrypted blob:<br/>[version:1][nonce:12][ciphertext+tag]
    New Device->>New Device: Extract nonce (12 bytes)
    New Device->>New Device: Decrypt compressed data:<br/>AES-256-GCM(ciphertext, BEK, nonce)
    New Device->>New Device: Verify authentication tag<br/>(prevents tampering)

    Note over New Device,SQLite Database: Phase 7: Decompression
    New Device->>New Device: Decompress with GZIP
    Note right of New Device: Restore original size from ~60% compression

    Note over New Device,SQLite Database: Phase 8: Master ID Verification
    New Device->>New Device: Deserialize JSON to BackupData structure
    New Device->>New Device: Extract backup.master_identity_id
    New Device->>New Device: Compare with recovered Master ID
    alt Master ID Mismatch
        New Device->>New Device: Abort restore with error:<br/>MasterIdMismatch
    end
    Note right of New Device: Security: Prevents restoring wrong user's backup

    Note over New Device,SQLite Database: Phase 9: Nuclear Table Clearing
    New Device->>SQLite Database: DELETE FROM contacts
    New Device->>SQLite Database: DELETE FROM personas
    New Device->>SQLite Database: DELETE FROM trust_attestations
    Note right of SQLite Database: Clean slate approach<br/>Removes any pre-existing data

    Note over New Device,SQLite Database: Phase 10: Device ID Injection & Restoration
    loop For each contact
        New Device->>New Device: Inject new device_id (new device)
        New Device->>New Device: Generate new created_at timestamp
        New Device->>New Device: Generate new updated_at timestamp
        New Device->>SQLite Database: INSERT contact with new device_id
    end

    loop For each persona
        New Device->>New Device: Inject new device_id
        New Device->>New Device: Generate new timestamps
        New Device->>SQLite Database: INSERT persona with new device_id
    end

    loop For each trust attestation
        New Device->>New Device: Inject new device_id
        New Device->>New Device: Generate new timestamps
        New Device->>SQLite Database: INSERT trust_attestation with new device_id
    end

    Note over New Device,SQLite Database: Phase 11: Restore Complete
    New Device->>New Device: Generate RestoreReport:<br/>{contacts_restored, personas_restored, attestations_restored}
    New Device->>New Device: Display success message to user
    Note right of New Device: User sees all data restored<br/>Ready to use immediately

Cryptographic Security

Why BEK is Available:

• During identity recovery, SDK calls derive_bek_personal(master_id, passphrase)

• Derived BEK is immediately stored in hardware keychain

• Same BEK used for backup creation is now available for restoration

• Deterministic derivation ensures BEK is identical on any device with same Master ID + passphrase

AES-256-GCM Decryption

Encrypted Blob Structure:

┌─────────┬──────────────┬────────────────────────────────┐ │ Version │ Nonce │ Ciphertext + Authentication Tag │ │ 1 byte │ 12 bytes │ Variable (compressed data + 16) │ │ (0x01) │ (from backup)│ (AES-256-GCM output) │ └─────────┴──────────────┴────────────────────────────────┘

Security Properties:

• Authentication Verification: 128-bit tag ensures data integrity and authenticity

• Tamper Detection: Modified ciphertext fails to decrypt (authentication error)

• Nonce Uniqueness: Each backup has unique nonce (extracted from blob)

• 256-bit Key: BEK provides 256-bit security strength

• AEAD: Decrypt-then-verify integrated (NIST-approved)

Field Injection:

• device_id: New device's unique ID (different from backup device)

• created_at: Current timestamp (not from backup)

• updated_at: Current timestamp (not from backup)

Why Field Injection:

• Each device has unique device_id tracked for security auditing

• Timestamps reflect when record was created ON THIS DEVICE

• Backup data (contacts, personas, trust attestations) remains intact

• Device-specific metadata updated for new device context

Security Guarantees

1. BEK Availability Through Deterministic Derivation

• Same Master ID + passphrase → same BEK (reproducible)

• BEK derived during identity recovery, stored in hardware keychain

• Retrieve BEK from secure storage for restoration (no re-derivation needed)

• Hardware-protected storage ensures BEK security

2. Master ID Verification Before Restoration

• Backup Master ID must match recovered identity's Master ID

• Prevents accidental restoration of wrong user's backup

• Cryptographic proof of identity ownership

• Fails fast if wrong backup attempted

3. Zero-Knowledge Backend

• Backend retrieves encrypted blob from S3 (opaque ciphertext)

• Backend never sees BEK or plaintext data

• Decryption happens entirely on device

• Backend compromise does NOT expose user data

4. Hardware-Protected BEK Storage

• BEK stored in iOS Keychain / Android KeyStore

• Hardware-level encryption automatically applied

• Protected by device biometrics/passcode

• Non-exportable from device hardware

5. Authenticated Decryption

• AES-256-GCM verifies data integrity and authenticity

• Authentication tag prevents tampering

• Modified ciphertext fails to decrypt

• Wrong BEK produces authentication failure (not garbage data)

6. Nuclear Table Clearing for Clean Slate

• Complete database wipe before restoration

• No orphaned records or ID conflicts

• Backup represents complete truth

• Predictable and simple (no merge logic bugs)

7. Device ID Injection for Portability

• New device_id injected into all restored records

• Timestamps regenerated for new device context

• Backup data (contacts, personas) remains intact

• Clean migration across devices

Strategic Implications

Seamless Cross-Device Recovery

Traditional Problem:

• User sets up new phone:

  • Manually re-add all contacts

  • Manually re-create personas

  • Lose trust attestation history

  • Hours of manual data entry

  • Risk of forgetting contacts

GetTrusted Solution:

• User recovers identity on new phone:

  • Enter passphrase (derives same BEK)

  • SDK automatically downloads backup from S3

  • SDK automatically decrypts and restores

  • All contacts, personas, attestations appear

  • Zero manual data entry

  • Complete history preserved

  • Ready to use in seconds

Zero-Knowledge Cloud Storage

Backend Cannot:

• Decrypt any backup data

• Read contacts or personas

• Access trust attestations

• Derive BEK from encrypted blobs

• Correlate backups across users (fingerprint-based S3 keys)

• Restore user data without user's BEK

Backend Can:

• Store encrypted blobs reliably (S3 durability: 99.999999999%)

• Track backup metadata (sizes, timestamps)

• Enable cross-device recovery (blob retrieval)

• Audit access patterns (Firestore logs)

• Scale storage elastically (S3 auto-scaling)