CEB tools

Tools for working with Conversations Encrypted Backups

CEB is: gzip-compressed SQL insert statements, encrypted with AES-128-GCM, plus a simple header. The SQL encodes various local account data, such as message history and OMEMO secrets, as well as login credentials. The login passphrase is usually also the backup encryption passphrase, the key derived from it with 1024 rounds of PBKDF2-HMAC-SHA1.

The toolbox currently contains:

• ceb2sqlgz command for decrypting the backup files;
• schema*.sql files containing accounts database table creation statements.

Comparison with similar tools

name	conversions¹	language	license	crypto library	memory use⁴
ceb2txt	ceb→txt²	Java 11	Apache 2.0	Conscrypt	database
ceb-extract	ceb→{sqlgz,db}, db→json²	Python 3.8	none	cryptography	ceb+gz+sql
ceb2xml³	ceb→db	Lua 5.3	none	OpenSSL	constant
ceb-tools	ceb→sqlgz, sql→databases	C++20	GNU AGPL3+	OpenSSL	constant

1. 'db' = SQLite 3 database.
2. Partial export (mainly messages), no particular schema.
3. XML part not actually published/finished.
4. If not 'constant', linear is implied, with purposes indicated. Relevant when handling huge backups in memory-constrained environments.

Requirements

• A C++20-ish compiler. g++ 8 or clang++ 9 will do.
• GNU Make (not strictly necessary – ceb2sqlgz is not terribly hard to build manually – but the instructions below rely on it).
• (optional) For Android, you might want unsupported things to be cleaned out of the produced binaries to avoid warnings printed to stderr. The makefile does this if termux-elf-cleaner is found.

To install on...

• GNU/Linux
  • Debian >= 10:
    • # apt install g++ make
• Android
  • Termux:
    • $ apt install clang make termux-elf-cleaner
• Windows
  • MSYS2 (untested):
    • $ pacman --sync gcc make

Build-time dependencies

• libcrypto
• unaesgcm 0.4 (in source form)

To install on...

• GNU/Linux
  • Debian:
    • # apt install libssl-dev
• Android
  • Termux:
    • $ apt install openssl
• Windows
  • MSYS2 (untested):
    • $ pacman --sync openssl-devel

If you're fetching this repo with git clone, add --recurse-submodules option or do git submodule init after.

If not using git, manually place unaesgcm 0.4 sources under unaesgcm directory, e.g.: curl https://codeload.github.com/Yuubi-san/unaesgcm/tar.gz/refs/tags/v0.4 | tar -zx && mv unaesgcm-0.4 unaesgcm.

Run-time dependencies

• libcrypto;
• (optional) gunzip or some other gzip decompressor;
• (optional) sqlite3 or any other tool that understands SQL and does with it what you need.

To install on...

• GNU/Linux
  • Debian:
    • # apt install libssl1.1 gzip sqlite3
• Android
  • Termux:
    • $ apt install openssl gzip sqlite
• Windows
  • MSYS2 (untested):
    • $ pacman --sync openssl gzip sqlite

Building

$ make

Usage examples

Caution: All your database are belong to us! (Some of) the examples below may persist unencrypted account data, including passwords and cryptographic secrets, to permanent storage. User descretion is advised, full-disk encryption is recommended. Alternatively, see secure-delete and man shred.

Create an SQLite database from an account backup

ceb2sqlgz account.ceb | gunzip | cat schema.sql - | sqlite3 account.db

ceb2sqlgz will prompt you to enter the passphrase to decrypt the .ceb.

...or from a bunch of (distinct) accounts

cat schema.sql | sqlite3 accounts.db &&
for ceb in backup-2022-04-13/*.ceb; do
  ceb2sqlgz "$ceb" | gunzip | sqlite3 accounts.db
done

Search things directly in SQL

ceb2sqlgz backup.ceb | gunzip | \
  sed -e's/VALUES(/VALUES\n(/' -e's/),(/),\n(/g' | \
  grep -i -A10 "cake recipe"

The sed incantations try to put line breaks between messages (there are 20 per line, usually), but aren't strictly necessary.

Security & privacy considerations

Currently no effort has been put into keeping secure the decryption passphrase/key or CEB contents (which include private OMEMO keys, among other potentially sensitive data), beyond not echoing the passphrase at entry and not explicitly writing anything to non-volatile memory (storage). Secrets can still leak from volatile memory, e.g., via swap space (unless it's encrypted).

License

GNU Affero General Public License v3.0 or later, with OpenSSL linking exception