docs(01-01): complete format specification plan
- SUMMARY.md with execution metrics and self-check - STATE.md updated: Phase 1 complete, decisions logged - ROADMAP.md updated: Phase 1 progress 1/1 - REQUIREMENTS.md: FMT-05 marked complete Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
NikitolProject
@@ -11,7 +11,7 @@
|
||||
- [ ] **FMT-02**: Поле версии формата (1 байт) для forward compatibility
|
||||
- [ ] **FMT-03**: Таблица файлов с метаданными: имя файла, original size, compressed size, encrypted size, offset, IV, HMAC
|
||||
- [ ] **FMT-04**: Little-endian для всех multi-byte полей
|
||||
- [ ] **FMT-05**: Спецификация формата как документ (до начала реализации)
|
||||
- [x] **FMT-05**: Спецификация формата как документ (до начала реализации)
|
||||
- [ ] **FMT-06**: XOR-обфускация заголовков с фиксированным ключом
|
||||
- [ ] **FMT-07**: Зашифрованная таблица файлов (отдельный IV)
|
||||
- [ ] **FMT-08**: Decoy padding (случайные данные между блоками)
|
||||
@@ -97,7 +97,7 @@
|
||||
| FMT-02 | Phase 2 | Pending |
|
||||
| FMT-03 | Phase 2 | Pending |
|
||||
| FMT-04 | Phase 2 | Pending |
|
||||
| FMT-05 | Phase 1 | Pending |
|
||||
| FMT-05 | Phase 1 | Complete |
|
||||
| FMT-06 | Phase 6 | Pending |
|
||||
| FMT-07 | Phase 6 | Pending |
|
||||
| FMT-08 | Phase 6 | Pending |
|
||||
|
||||
@@ -9,29 +9,29 @@ See: .planning/PROJECT.md (updated 2026-02-24)
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: 1 of 6 (Format Specification)
|
||||
Plan: 0 of 1 in current phase
|
||||
Status: Ready to plan
|
||||
Last activity: 2026-02-24 -- Roadmap created
|
||||
Phase: 1 of 6 (Format Specification) -- COMPLETE
|
||||
Plan: 1 of 1 in current phase
|
||||
Status: Phase 1 complete, ready for Phase 2
|
||||
Last activity: 2026-02-24 -- Format specification written
|
||||
|
||||
Progress: [░░░░░░░░░░] 0%
|
||||
Progress: [█░░░░░░░░░] 12%
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
**Velocity:**
|
||||
- Total plans completed: 0
|
||||
- Average duration: -
|
||||
- Total execution time: 0 hours
|
||||
- Total plans completed: 1
|
||||
- Average duration: 7 min
|
||||
- Total execution time: 0.1 hours
|
||||
|
||||
**By Phase:**
|
||||
|
||||
| Phase | Plans | Total | Avg/Plan |
|
||||
|-------|-------|-------|----------|
|
||||
| - | - | - | - |
|
||||
| 1. Format Specification | 1 | 7 min | 7 min |
|
||||
|
||||
**Recent Trend:**
|
||||
- Last 5 plans: -
|
||||
- Trend: -
|
||||
- Last 5 plans: 7min
|
||||
- Trend: baseline
|
||||
|
||||
*Updated after each plan completion*
|
||||
|
||||
@@ -44,6 +44,10 @@ Recent decisions affecting current work:
|
||||
|
||||
- Roadmap: Format spec must precede all implementation (all three decoders build against same spec)
|
||||
- Roadmap: Obfuscation (XOR headers, encrypted TOC, decoy padding) deferred to Phase 6 after all decoders work without it
|
||||
- Phase 1: IV stored only in TOC, not duplicated in data blocks (simplifies shell dd extraction)
|
||||
- Phase 1: Same 32-byte key for AES-256-CBC and HMAC-SHA-256 in v1 (v2 will use HKDF)
|
||||
- Phase 1: Magic bytes 0x00 0xEA 0x72 0x63 (leading null signals binary)
|
||||
- Phase 1: HMAC scope = IV (16 bytes) || ciphertext (encrypted_size bytes)
|
||||
|
||||
### Pending Todos
|
||||
|
||||
@@ -52,11 +56,11 @@ None yet.
|
||||
### Blockers/Concerns
|
||||
|
||||
- Open question: Does target busybox have `openssl enc -aes-256-cbc` with `-K`/`-iv` flags? (affects Phase 5)
|
||||
- Open question: Is `xxd` available in target busybox? Fallback: `od` (affects Phase 5)
|
||||
- Open question: Should HMAC use same key as AES or derived subkey? (must resolve in Phase 1 spec)
|
||||
- Open question: Is `xxd` available in target busybox? Fallback: `od` (affects Phase 5; spec includes od fallback functions)
|
||||
- RESOLVED: HMAC uses same key as AES in v1 (decided in Phase 1 spec, v2 will use HKDF)
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-02-24
|
||||
Stopped at: Roadmap created, ready to plan Phase 1
|
||||
Stopped at: Completed 01-01-PLAN.md (Format Specification)
|
||||
Resume file: None
|
||||
|
||||
115
.planning/phases/01-format-specification/01-01-SUMMARY.md
Normal file
115
.planning/phases/01-format-specification/01-01-SUMMARY.md
Normal file
@@ -0,0 +1,115 @@
|
||||
---
|
||||
phase: 01-format-specification
|
||||
plan: 01
|
||||
subsystem: docs
|
||||
tags: [binary-format, aes-256-cbc, hmac-sha256, pkcs7, gzip, specification]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: none
|
||||
provides: "First phase, no dependencies"
|
||||
provides:
|
||||
- "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)"
|
||||
affects: [02-core-archiver, 03-round-trip-verification, 04-kotlin-decoder, 05-shell-decoder, 06-obfuscation-hardening]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns: [encrypt-then-mac, pkcs7-padding, little-endian-integers, length-prefixed-utf8-strings]
|
||||
|
||||
key-files:
|
||||
created: [docs/FORMAT.md]
|
||||
modified: []
|
||||
|
||||
key-decisions:
|
||||
- "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"
|
||||
|
||||
patterns-established:
|
||||
- "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"
|
||||
|
||||
requirements-completed: [FMT-05]
|
||||
|
||||
# Metrics
|
||||
duration: 7min
|
||||
completed: 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*
|
||||
Reference in New Issue
Block a user