Skip to content

Secure Content Store

rockcutto edited this page Oct 5, 2026 · 1 revision

Secure Content Store (SCS) is LibreSpan's protected local storage layer for message text and media.

The goal is not merely to “encrypt a file”, but to control the complete lifecycle of protected content.

Object identity

Protected content is isolated per account.

Conceptually, an object is addressed by a tuple such as:

namespace | cryptoVersion | accountUuid | contentId

Association with a specific message is handled separately through messageUuid.

This prevents protected content from different accounts from being mixed and avoids using a public filesystem path as the primary identity.

Write lifecycle

A write moves through explicit states:

ALLOCATED
  ↓
WRITING
  ↓
READY_TO_COMMIT
  ↓
COMMITTED

Cancelled or failed operations terminate in:

ABORTED
FAILED

The key rule is:

Readers consume only COMMITTED objects.

This reduces the risk of reading partially written or corrupt protected content.

Core components

SCS separates responsibilities across distinct layers:

  • MetadataStore
  • BlobStore
  • KeyMaterialStore
  • SecureContentWriteSession

This makes it possible to control:

  • metadata;
  • encrypted payloads;
  • key material;
  • write atomicity.

Protected text

Protected text uses a dedicated repository path.

After successful verification/decryption, text may temporarily use a verified cache for display, but durable plaintext should not become the new source of truth.

Media

The protected path is used for:

  • images;
  • albums;
  • video;
  • audio;
  • voice messages;
  • files.

After a successful commit, staging data should be removed.

Decoded images may use a verified bitmap cache, which is also not a durable primary store.

Export boundary

New protected media remains in app-private storage by default.

Explicit user actions such as:

  • Save
  • Share

are treated as deliberate export boundaries outside LibreSpan's protected storage.

After export, security of the copied data is determined by the operating system and the receiving application.

Data clearing

Account-scoped clearing should remove protected local content for the selected account without affecting other accounts.

Depending on the operation, this may include:

  • SCS text;
  • SCS media;
  • blind-search index;
  • verified caches.

Account identity, roster data, and long-term OMEMO identity/trust state do not necessarily need to be destroyed by ordinary local-content clearing.

Logout is not wipe

Logging out or temporarily disabling an account is not treated as destruction of protected data.

This separation is intentional:

account state != data destruction

Full local deletion should be a separate explicit action.

Search

For protected text, LibreSpan may use a blind-search approach so that a normal durable plaintext index is not required.

Boundaries

SCS protects data within the application boundary, but it cannot control:

  • user-exported copies;
  • system clipboard content;
  • screenshots;
  • a compromised operating system;
  • copies already delivered to other participants;
  • data retained by a server outside the local device.

Clone this wiki locally