How bepaald/signalbackup-tools works
Project Type and Purpose
• This is a single‐binary C++17 command-line application (“signalbackup-tools”) for decrypting, inspecting, modifying and re-encrypting Signal Android backup files. It uses OpenSSL for crypto, SQLite3 for database operations, and (optionally) D-Bus to fetch Signal Desktop keys.
High-Level File-Structure Analysis
• Top-level build/config: CMakeLists.txt, BUILDSCRIPT.bash, .github/workflows
• CLI/front-end: main.cc, main.h, arg/ (argument parsing)
• Crypto layer: cryptbase/, sqlcipherdecryptor/
• Frame modules: headerframe/, databaseversionframe/, attachmentframe/, avatarframe/, stickerframe/, keyvalueframe/, sharedprefframe/, sqlstatementframe/, endframe/
• I/O layer: androidattachmentreader/, desktopattachmentreader/, rawfileattachmentreader/, baseattachmentreader/
• Database layer: filesqlitedb/, memfiledb/, memsqlitedb/, jsondatabase/
• Operation modules: signalbackup/ (dump, export, crop, merge, import), csvreader/, xmldocument/
• Utility modules: base64/, protobufparser/, common_*.h, logger/, scopeguard/, etc.
Key Insights from README
• The tool reads an encrypted backup file (or directory), decrypts it frame by frame, reconstructs an in-memory SQLite DB, performs user-requested operations (dump, export, fix, merge, import), then writes out frames and re-encrypts into a new backup.
• Supports multiple export formats (HTML, TXT, CSV, XML), plus import from Signal Desktop and Telegram JSON.
Main Components
a. CLI Front-End
• main.cc + arg module
• Parses flags and subcommands (dump, exporthtml, importfromdesktop, etc.)
b. Crypto Layer
• cryptbase: key derivation (PBKDF2), cipher/MAC setup
• sqlcipherdecryptor: decrypt SQLite-encrypted Desktop DB
• fileencryptor/filedecryptor: frame-level encrypt/decrypt
c. Frame Parser/Writer Pipeline
• Sequence of Frame modules (HeaderFrame → DatabaseVersionFrame → SqlStatementFrame → SharedPrefFrame → KeyValueFrame → AttachmentFrame/AvatarFrame/StickerFrame → EndFrame)
• Each module reads/writes its SBF binary frame; collectively they reconstruct or assemble backup.
d. In-Memory Database
• filesqlitedb / memfiledb / memsqlitedb for temporary DB
• JSONDatabase for JSON import/export
e. I/O Readers/Writers
• AndroidAttachmentReader, DesktopAttachmentReader, RawFileAttachmentReader for pulling attachment bytes from backups or directories
f. Operation Engines
• signalbackup/: core logic for dumping, cropping, merging, fix-corruption
• Export modules: csvreader, xmldocument, HTML template engine (within signalbackup/)
• Import modules: desktopdatabase (DBus or manual key), JSON import, Telegram mapping
g. External Dependencies
• OpenSSL (crypto)
• SQLite3 (database engine)
• D-Bus (optional, to fetch desktop secrets)
• File system (reading/writing backups and directories)
Relationships & Data Flows
• Branch:
• Database → Operation Engines (dump to FS, crop, fix, merge) → Frame Writer → Crypto Layer → New backup file
• Database → Export Engines (HTML/TXT/CSV/XML) → Output directory/files
• External Input (Desktop DB / JSON) → Import Engines → In-Memory Database
• External Dependencies called by respective layers (OpenSSL by Crypto, SQLite by DB layer, D-Bus by desktopdatabase).
Architectural Patterns & Principles
• Modular layering: separation of concerns between CLI, crypto, parsing/writing, DB, operations, I/O, export/import
• Pipeline pattern: sequential frame processing
• Strategy/Plugin style: each frame type and each operation (dump, export, import) lives in its own module
• Single executable “monolith” with clear internal modules rather than microservices