Skip to content

Space Backup and Restore Technical White Paper

Abstract

UnoLock Space Backup is a client-side encrypted, stream-oriented export/import mechanism for moving one Space and its archives across Safes. The format is designed for:

  • large-file streaming without full in-memory buffering,
  • authenticated per-frame processing,
  • archive-ID remapping on restore.

This document describes the protocol, cryptography, restore semantics, and security boundaries as implemented in the current client.

Scope

Included in backup:

  • Space records and labels metadata,
  • non-Records archives belonging to the Space (Cloud, Msg, Local),
  • optional wallet secret material (when explicitly selected).

Not included:

  • Safe-global policy/configuration not part of Space data model,
  • keys/credentials of the source Safe,
  • server-side operational metadata not required to reconstruct Space content.

Design Goals

  • Maintain zero-knowledge handling (all backup payloads encrypted client-side).
  • Preserve streaming behavior for large archives.
  • Ensure record attachment references remain valid after restore into a different Safe.

Threat Model

Defended

  • Passive storage adversary reading .usbk contents without password.
  • In-transit tampering of backup bytes (detected by AES-GCM authentication).
  • Frame reordering/substitution attacks (frame index and type bound into AAD).
  • Malformed input classes that attempt oversize frame/KDF allocation denial of service (bounded in restore parser).

Not Defended

  • Endpoint compromise on source or destination client.
  • Offline brute-force against weak backup passwords.
  • Operational leakage from insecure handling of exported backup files.

Backup File Format (v2)

Header fields:

  • Magic: USBK2STR (8 bytes)
  • Format version: 2
  • KDF type: Argon2id
  • Salt
  • Nonce prefix (8 bytes)
  • Serialized KDF params (JSON)

The header carries all required metadata for deterministic restore.

Frame Stream

Backup body is a sequence of encrypted frames:

  • MANIFEST
  • ARCHIVE_START
  • ARCHIVE_CHUNK
  • ARCHIVE_END
  • ARCHIVE_ABORT
  • DONE

Each frame has:

  • frame type (1 byte),
  • frame index (uint32 LE),
  • ciphertext length (uint32 LE),
  • ciphertext bytes.

Parser protections include:

  • valid frame-type enforcement,
  • minimum/maximum ciphertext bounds,
  • strict monotonic index matching,
  • single DONE marker and no trailing data after DONE.

Cryptography

KDF

Current default for v2 backups:

  • Argon2id with explicit parameters in header.

Restore hardening validates KDF parameters against bounded ranges before derivation to reduce crafted-input DoS risk.

Encryption

Each frame payload is encrypted with AES-256-GCM.

  • Nonce: 12 bytes = random 8-byte nonce prefix + 4-byte frame index.
  • AAD: frame type + frame index.
  • Authentication tag: GCM standard tag.

This binds ciphertext integrity to frame position and type, preventing silent frame permutation.

Streaming Architecture

Backup

  • Manifest and control frames are emitted incrementally.
  • Archive content is streamed chunk-by-chunk from archive URLs (and local-file path for Local archives).
  • No full archive buffering is required.

Restore

  • Frames are read and decrypted sequentially.
  • For each archive stream, a destination archive is created and chunk data is piped into upload stream.
  • Failures convert to explicit skipped/archive-abort semantics where possible.

Records and Attachment Remap Semantics

Restored archive objects are created in the destination Safe and receive new archive IDs.

The restore pipeline builds a source→destination archive ID map, then rewrites record attachment references before writing restored Records data.

Supported reference forms:

  • record.archives[].

Unmapped references are dropped, and the record attachment field is normalized accordingly.

Local Archive Handling

Local archives are included when corresponding .ulf files are provided during backup.

Selection/matching behavior:

  • local file header is used to match archive ID,
  • strict mode can block backup if required local archives are missing,
  • unresolved local files are reported as skipped.

Wallet Portability Path

When wallet inclusion is enabled:

  • wallet protected secret parts are decrypted via WebAuthn-assisted flow,
  • decryption is batched to reduce ceremonies,
  • plaintext wallet material is included only inside encrypted backup payload,
  • on restore, secrets are re-encrypted using destination Safe WebAuthn-protected encryption,
  • plaintext wallet fields are removed from restored records.

Length consistency checks are enforced on decrypt/encrypt batch results to fail closed on partial responses.

Integrity and Failure Semantics

  • Archive stream failures during backup can emit ARCHIVE_ABORT.
  • Restore tracks skipped archives with reason codes.
  • Terminal DONE frame required for successful restore completion.
  • Password mismatch or authenticated decryption failure returns corruption/password error.

Format Validation

  • Unknown KDF type or unsupported version is rejected.
  • Frame order and frame type validity are enforced.

Operational Guidance

  • Prefer normal Safe redundancy and key hygiene over routine exported backups.
  • Use backups for controlled migration workflows.
  • Enforce high-entropy backup passphrases and secure storage handling.
  • Audit skipped archive counts during restore verification.

Security Limitations and Future Work

  • Password-derived backups are intrinsically susceptible to offline guessing if passphrase quality is weak.
  • Local archive matching can be further strengthened with additional content integrity checks at selection time.
  • Memory-hard KDF defaults should be periodically recalibrated to target hardware baselines and UX constraints.

Conclusion

The Space backup/restore design provides practical portability with strong client-side authenticated encryption and streaming for large archives. With strict parser/KDF bounds, explicit frame integrity, and deterministic attachment remapping, it is suitable for controlled cross-Safe migration while preserving UnoLock’s zero-knowledge posture.