User Data Backup

How GetTrusted backups user data when requested.

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 Backup Flow creates encrypted, compressed backups of user data (contacts, personas, trust attestations) with deterministic key derivation for automatic backup recovery. The system uses HKDF-SHA256 for Backup Encryption Key (BEK) derivation, AES-256-GCM for encryption, and stores encrypted blobs in AWS S3 with zero-knowledge security.

Key Security Features:

  • Deterministic BEK Derivation: HKDF-SHA256(Master ID, passphrase) — always same BEK for recovery

  • Hardware-Backed BEK Storage: BEK stored in iOS Keychain / Android KeyStore after derivation

  • Zero-Knowledge Server: Backend stores encrypted blobs in S3, never sees plaintext

  • GZIP Compression: ~60% size reduction before encryption

  • AES-256-GCM Encryption: Authenticated encryption with nonce-based security

  • Automatic Backup Triggering: Data changes trigger automatic background uploads

Process Overview

Alice (an existing user) makes changes to her contacts or personas. The app automatically creates an encrypted backup and uploads it to AWS S3 via the GetTrusted backend.

Alice's Perspective (User with Automatic Backups)

1

Identity & BEK state

  • Alice's identity already created with Master ID and passphrase.

  • BEK already derived during identity creation and stored in hardware keychain.

2

Data change detected

  • Alice adds a new contact or updates a persona.

  • App detects the data change and triggers automatic backup.

3

Data export & field stripping

  • SDK queries local storage (contacts, personas, attestations).

  • Encrypted rows are decrypted with the database encryption key.

  • Device-specific fields are stripped:

    • Remove device_id

    • Remove created_at

    • Remove updated_at

  • Create BackupData structure: { master_id, contacts[], personas[], attestations[] }

4

Compression

  • Serialize BackupData to JSON.

  • Compress with GZIP (Compression::default).

  • Typical reduction: ~60% size reduction.

5

BEK retrieval

  • SDK retrieves BEK (32 bytes) from secure hardware-backed keychain (stored during identity creation).

  • Retrieval requires no user interaction on typical automatic backup flow.

6

Encryption

  • Generate random nonce (12 bytes).

  • Encrypt compressed data using AES-256-GCM with BEK and nonce.

  • Build encrypted blob: [version:1][nonce:12][ciphertext+tag]

7

Upload to backend

  • POST /api/v1/backup/cloud/export with { user_id, encrypted_backup_blob, metadata }.

  • JWT token used for authentication.

8

Backend stores blob & metadata

  • Backend uploads blob to S3 and stores metadata in Firestore.

  • SDK receives success response and updates local backup status.

  • App continues normally — backup happened invisibly in background.

Backend Perspective (GetTrusted API + AWS Services)

1

Receive upload

  • Backup upload request arrives with encrypted blob.

  • Request includes JWT token for authentication.

2

Validate & extract

  • Validate JWT token (device signature verification).

  • Extract user fingerprint from Master ID (strip any prefix such as 'gtm').

3

Store encrypted blob in S3

  • Upload encrypted blob to S3 (zero-knowledge storage).

  • Example key: backups/{fingerprint}/backup.bin

4

Store metadata in Firestore

  • Store metadata at /backups/{user_id} with { fingerprint, s3Key, size, exportedAt, status }.

5

Return success

  • Return success response { success: true, backend_backup_id } to mobile device.

Process Flow Diagram

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

    Note over Alice Device,Firestore: Phase 1: Automatic Backup Trigger
    Alice Device->>Alice Device: User adds/updates contact or persona
    Alice Device->>Alice Device: Data change detected
    Alice Device->>SQLite Database: Query contacts, personas, attestations

    Note over Alice Device,Firestore: Phase 2: Data Export with Field Stripping
    SQLite Database-->>Alice Device: Encrypted rows (database_encryption_key)
    Alice Device->>Alice Device: Decrypt rows with database_encryption_key
    Alice Device->>Alice Device: Strip device-specific fields:<br/>- Remove device_id<br/>- Remove created_at<br/>- Remove updated_at
    Alice Device->>Alice Device: Create BackupData structure:<br/>{master_id, contacts[], personas[], attestations[]}

    Note over Alice Device,Firestore: Phase 3: Compression
    Alice Device->>Alice Device: Serialize to JSON
    Alice Device->>Alice Device: Compress with GZIP (Compression::default)
    Note right of Alice Device: ~60% size reduction typical

    Note over Alice Device,Firestore: Phase 4: BEK Retrieval from Keychain
    Alice Device->>Alice Secure Enclave: Retrieve BEK from keychain<br/>(stored during identity creation)
    Alice Secure Enclave-->>Alice Device: BEK (32 bytes)
    Note right of Alice Secure Enclave: Hardware-protected keychain storage<br/>No user interaction needed

    Note over Alice Device,Firestore: Phase 5: Encryption with AES-256-GCM
    Alice Device->>Alice Device: Generate random nonce (12 bytes)
    Alice Device->>Alice Device: Encrypt compressed data:<br/>AES-256-GCM(compressed_data, BEK, nonce)
    Alice Device->>Alice Device: Build encrypted blob:<br/>[version:1][nonce:12][ciphertext+tag]

    Note over Alice Device,Firestore: Phase 6: Upload to Backend
    Alice Device->>GetTrusted Backend: POST /api/v1/backup/cloud/export<br/>{user_id, encrypted_backup_blob, metadata}
    Note right of Alice Device: 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 Alice Device,Firestore: Phase 7: S3 Storage (Zero-Knowledge)
    GetTrusted Backend->>AWS S3: PUT object<br/>Key: backups/{fingerprint}/backup.bin<br/>Body: encrypted_backup_blob
    AWS S3-->>GetTrusted Backend: S3 upload complete<br/>{s3Key, size, bucketName}

    Note over Alice Device,Firestore: Phase 8: Metadata Storage
    GetTrusted Backend->>Firestore: SET /backups/{user_id}<br/>{fingerprint, s3Key, size, exportedAt, status}
    Firestore-->>GetTrusted Backend: Document created

    GetTrusted Backend-->>Alice Device: {success: true, backend_backup_id}
    Alice Device->>Alice Device: Update local backup status<br/>Continue normal operation

Cryptographic Security

BEK Derivation (HKDF-SHA256)

Deterministic Key Derivation:

  • HKDF-SHA256(Master ID, passphrase) → BEK

Security Properties:

  • Deterministic: Same Master ID + passphrase → same BEK (required for recovery)

  • Hardware-Protected Master ID: Master ID stored in Secure Enclave/StrongBox

  • User Knowledge Factor: Passphrase required (multi-factor security)

  • Standard KDF: HKDF-SHA256 is NIST-approved (RFC 5869)

  • One-Way: Cannot derive Master ID or passphrase from BEK

AES-256-GCM Encryption

Encrypted Blob Structure:

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

Security Properties:

  • Authenticated Encryption: Integrity and confidentiality guaranteed

  • Unique Nonce: Fresh random nonce per backup (no nonce reuse)

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

  • Authentication Tag: 128-bit tag prevents tampering

  • AEAD: Encrypt-then-MAC integrated (NIST-approved)

Security Guarantees

  1. Deterministic BEK for Recovery

  • Same Master ID + passphrase → same BEK

  • No random components in derivation (fully reproducible)

  • Required for automatic backup restoration on new device

  • HKDF-SHA256 ensures uniform distribution

  1. Multi-Factor BEK Security

  • Hardware Factor: Master ID in Secure Enclave (cannot extract)

  • Knowledge Factor: User passphrase required

  • Attacker needs BOTH factors to decrypt backup

  • Breaking one factor insufficient for backup access

  1. Zero-Knowledge Backend

  • Backend never sees BEK or plaintext data

  • S3 stores only encrypted blobs (opaque ciphertext)

  • Firestore stores only metadata (sizes, timestamps)

  • Backend compromise does NOT expose user data

  1. 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

  • Cleared on logout or backup disable

  1. Field Stripping for Portability

  • Device-specific fields removed before backup

  • New device injects its own device_id on restore

  • Timestamps regenerated for new device

  • Clean migration across devices

  1. Authenticated Encryption

  • AES-256-GCM provides integrity + confidentiality

  • Authentication tag prevents tampering

  • Modified ciphertext fails to decrypt

  • Nonce uniqueness prevents replay attacks

  1. Compression Before Encryption

  • GZIP reduces plaintext size (~60% typical)

  • Compressed before encryption (standard practice)

  • Reduces S3 storage costs

  • Faster network transfer

Strategic Implications

Automatic Cross-Device Sync

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

GetTrusted solution:

  • User recovers identity on new phone:

    • Enter passphrase (derives same BEK)

    • Automatic backup download from S3

    • Automatic restoration with BEK

    • All contacts, personas, attestations restored

    • Zero manual data entry

Zero-Knowledge Cloud Storage

Backend cannot:

  • Decrypt any backup data

  • Read contacts or personas

  • Access trust attestations

  • Derive BEK from encrypted blobs

Backend can:

  • Store encrypted blobs reliably (S3 durability)

  • Track backup metadata (sizes, timestamps)

  • Enable cross-device recovery (blob retrieval)

  • Audit access patterns (Firestore logs)

PreviousTrust Verification ChallengeNextUser Data Restoration

Last updated