Backup format

Last updated: September 14, 2026

1. Decrypting a backup on a computer

1. Install Python 3.
2. Install the cryptography library: pip install cryptography
3. Download the program sigbak_decrypt.py.
4. Run it with your archive and an output folder:

python sigbak_decrypt.py backup.sigbak my-documents

The program asks for your backup key at the keyboard (it is not shown on screen), then extracts each document into the folder. It checks the integrity of each one: a damaged document is reported and skipped, the others are extracted. The program only reads the archive and sends nothing over the Internet.

Exit code: 0 if the archive is intact, 1 if documents are missing or the archive is incomplete, 2 on error (wrong key, invalid file).

2. Format specification, version 1

This section is for people who want to check the format or write their own reader.

2.1 Backup key

• 16 random bytes (128 bits), generated by the app.
• Displayed as 28 symbols of Crockford's base32 alphabet 0123456789ABCDEFGHJKMNPQRSTVWXYZ, in groups of 4: the 128 bits followed by 2 zero bits give 26 symbols (most significant bit first), then 2 check symbols.
• Check: c = (Σ (i+1) × s[i]) mod 1021 for i from 0 to 25, written on 10 bits (c >> 5, then c & 31).
• On input: ignore spaces and dashes, convert to upper case, read O as 0 and I, L as 1; reject if the length, a character, the check or the 2 padding bits are wrong.

2.2 Key derivation

okm            = HKDF-SHA256(key, header salt, "Sigillarium archive v1", 64)   (RFC 5869)
encryption_key = okm[0..32]
check_key      = okm[32..64]

2.3 Header (56 bytes, plaintext)

Bytes	Content
0–5	SIGBAK (ASCII)
6	format version: 1
7	key derivation: 1 = HKDF-SHA256
8–39	random salt (32 bytes)
40–55	key check: HMAC-SHA256(check_key, bytes 0–39), truncated to 16 bytes

2.4 Records

After the header, until the end of the file: type (1 byte) · ciphertext length L, tag included (4 bytes, big-endian) · nonce (12 bytes) · AES-256-GCM (encryption_key), ciphertext followed by the 16-byte tag.

Associated data of the record at index n (0 for the first): header (56) ‖ n (4, big-endian) ‖ type (1) ‖ L (4, big-endian). A record that is moved, removed or taken from another archive therefore fails authentication.

Type	Name	Decrypted content
0x01	INFO	JSON: {"createdAt": "<ISO 8601 UTC>"}
0x02	META	JSON: document metadata
0x03	DATA	document bytes
0x7F	END	JSON: {"entries": <number of documents>}

Sequence: INFO, then (META, DATA) for each document, then END.

2.5 Metadata (META)

name, fileType (MIME type), createdAt, modifiedAt (or null), description (or null), tags, sha256 (of the DATA bytes), size, and metadata (optional). A reader ignores unknown fields, and must never use name as a file path as is.

2.6 Damaged archive

• A record that fails authentication loses its own document only; a document is delivered only if its META and DATA both authenticated, in place.
• If a length exceeds what remains of the file, reading stops.
• The archive is complete if END authenticates and nothing follows it.

2.7 Test vector

archive_v1_sample.sigbak — 1,078 bytes, SHA-256 01b1eb4ac4aca12d32f0a482d76ec5dc5ec1b2f90e64ad64fcc16b1b8c478dbb. Key: 000G-40R4-0M30-E209-185G-R38E-1W73 (bytes 00 to 0F). It contains photo.jpg (300 bytes) and a document named ../note.txt, a deliberately hostile name that a correct reader must not use as a path.

2.8 Limits of version 1

• A document cannot exceed 4 GiB.
• Each document is encrypted in one block: the memory needed is that of the largest document.