User Data Restoration
How GetTrusted Restores User Data.
Overview
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)
Backend Perspective (GetTrusted API + AWS Services)
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 immediatelyCryptographic 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)
Last updated