android-encrypted-archiver/.planning/phases/01-format-specification/01-01-SUMMARY.md

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, patterns-established, requirements-completed, duration, completed

phase	plan	subsystem	tags	requires	provides	affects	tech-stack	key-files	key-decisions	patterns-established	requirements-completed	duration	completed
01-format-specification	01	docs	binary-format aes-256-cbc hmac-sha256 pkcs7 gzip specification	phase provides none First phase, no dependencies	Complete binary format specification at docs/FORMAT.md Byte-level field definitions for header (40 bytes), file table entries (variable), and data blocks Encryption pipeline: SHA-256 -> gzip -> PKCS7 -> AES-256-CBC -> HMAC-SHA-256 Worked example: 2-file archive with annotated hex dump (323 bytes) Shell decoder reference functions (read_le_u16, read_le_u32, verify_hmac, decrypt_file) Kotlin decoder reference (decrypt, HMAC verify, gzip decompress, SHA-256 verify)	02-core-archiver 03-round-trip-verification 04-kotlin-decoder 05-shell-decoder 06-obfuscation-hardening	added patterns encrypt-then-mac pkcs7-padding little-endian-integers length-prefixed-utf8-strings	created modified docs/FORMAT.md	IV stored only in TOC, not duplicated in data blocks (simplifies dd extraction) Same 32-byte key for AES-256-CBC and HMAC-SHA-256 in v1 (v2 will use HKDF) Magic bytes 0x00 0xEA 0x72 0x63 (leading null signals binary, not in any known signature DB) XOR obfuscation key: 0xA5 0x3C 0x96 0x0F 0xE1 0x7B 0x4D 0xC8 (8-byte repeating) HMAC input is IV (16 bytes) || ciphertext (encrypted_size bytes), no ambiguity	Field table pattern: offset, size, type, endian, field name, description for every binary structure Worked example pattern: concrete inputs -> pipeline walkthrough -> hex dump -> shell decode commands All offsets absolute from archive byte 0	FMT-05	7min	2026-02-24

Phase 1 Plan 1: Format Specification Summary

Complete binary format spec with 40-byte header, variable-length TOC entries, AES-256-CBC encrypt-then-MAC pipeline, PKCS7 padding formula, obfuscation features (XOR/encrypted TOC/decoy padding), and a 323-byte worked example with annotated hex dump

Performance

• Duration: 7 min
• Started: 2026-02-24T20:15:59Z
• Completed: 2026-02-24T20:22:38Z
• Tasks: 2
• Files modified: 1

Accomplishments

• Complete binary format specification (1031 lines) covering all 13 sections from overview through shell/Kotlin reference appendix
• Every binary structure (header, file table entry, data block) has a field table with exact offsets, sizes, types, and endianness
• Worked example with 2 files (hello.txt, data.bin) showing every byte of a 323-byte archive with real SHA-256 hashes and internally consistent offsets verified by automated script
• Shell decode walkthrough with exact dd/xxd commands for every extraction step
• Obfuscation features (XOR header, encrypted TOC, decoy padding) fully specified with byte ranges and activation flags

Task Commits

Each task was committed atomically:

1. Task 1: Write format specification with byte-level field definitions - fcd37f5 (feat)
2. Task 2: Write worked example with annotated hex dump and shell reference appendix - 1c698fe (feat)

Files Created/Modified

• docs/FORMAT.md - Complete binary format specification (1031 lines, 13 sections)

Decisions Made

• IV storage location: IV stored only in TOC entry, not duplicated at data block start. Differs from research suggestion of dual storage. Rationale: simpler dd extraction, TOC is always read before data blocks.
• HMAC key: Same 32-byte key for both AES-256-CBC and HMAC-SHA-256 in v1. Cryptographically safe for this specific combination. v2 will use HKDF-derived subkeys.
• Magic bytes: 0x00 0xEA 0x72 0x63. Leading null byte signals binary. Verified not in known file signature databases.
• XOR obfuscation key: 0xA5 0x3C 0x96 0x0F 0xE1 0x7B 0x4D 0xC8 (8-byte repeating over 40-byte header).
• HMAC scope: Explicitly defined as IV (16 bytes) || ciphertext (encrypted_size bytes). No ambiguity.

Deviations from Plan

None - plan executed exactly as written.

Issues Encountered

None.

User Setup Required

None - no external service configuration required.

Next Phase Readiness

• Format specification is complete and ready to serve as the build target for Phase 2 (Core Archiver)
• All three decoder implementations (Rust, Kotlin, Shell) have sufficient detail to implement against
• Worked example can serve as golden reference for Phase 3 test vectors
• Open questions from research resolved: HMAC uses same key as AES (v1), shell functions use xxd -p with manual byte reversal

Self-Check: PASSED

• FOUND: docs/FORMAT.md (1031 lines)
• FOUND: .planning/phases/01-format-specification/01-01-SUMMARY.md
• FOUND: commit fcd37f5 (Task 1)
• FOUND: commit 1c698fe (Task 2)

---

Phase: 01-format-specification Completed: 2026-02-24