99 lines
3.5 KiB
Markdown
99 lines
3.5 KiB
Markdown
---
|
|
phase: 05-shell-decoder
|
|
plan: 01
|
|
subsystem: shell-decoder
|
|
tags: [posix-sh, busybox, openssl, aes-256-cbc, dd, xxd, od, hmac, sha256]
|
|
|
|
# Dependency graph
|
|
requires:
|
|
- phase: 01-format-specification
|
|
provides: "FORMAT.md binary format spec with shell decoder reference (Section 13)"
|
|
- phase: 02-core-archiver
|
|
provides: "Rust archiver for creating test archives"
|
|
provides:
|
|
- "shell/decode.sh -- busybox-compatible POSIX shell decoder script"
|
|
- "Full decode pipeline: header -> TOC -> HMAC verify -> decrypt -> decompress -> SHA-256 verify -> write"
|
|
affects: [06-obfuscation]
|
|
|
|
# Tech tracking
|
|
tech-stack:
|
|
added: [sh, dd, openssl-enc, xxd, od, gunzip, sha256sum]
|
|
patterns: [posix-shell-binary-parsing, xxd-od-fallback, hmac-graceful-degradation]
|
|
|
|
key-files:
|
|
created:
|
|
- shell/decode.sh
|
|
|
|
key-decisions:
|
|
- "POSIX sh (not bash) for maximum busybox compatibility"
|
|
- "xxd/od auto-detection at startup for hex conversion"
|
|
- "Graceful HMAC degradation when openssl lacks -mac support"
|
|
- "Extract ciphertext to temp file before decryption (avoids pipe issues)"
|
|
- "LC_ALL=C for predictable byte handling"
|
|
|
|
patterns-established:
|
|
- "dd-based binary parsing with hex byte-swap for little-endian integers"
|
|
- "Temp file cleanup via trap on EXIT"
|
|
- "HMAC computed from raw archive bytes (IV from TOC offset + ciphertext), not from hex variables"
|
|
|
|
requirements-completed: [SHL-01, SHL-02, SHL-03]
|
|
|
|
# Metrics
|
|
duration: 3min
|
|
completed: 2026-02-25
|
|
---
|
|
|
|
# Phase 5 Plan 1: Shell Decoder Summary
|
|
|
|
**Busybox-compatible POSIX shell decoder with full decode pipeline (dd+xxd/od for parsing, openssl enc for AES-256-CBC decryption, HMAC verification with graceful degradation, SHA-256 integrity checks)**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** 3 min
|
|
- **Started:** 2026-02-24T22:37:48Z
|
|
- **Completed:** 2026-02-24T22:40:29Z
|
|
- **Tasks:** 1
|
|
- **Files created:** 1
|
|
|
|
## Accomplishments
|
|
- Created self-contained POSIX shell decoder script (250 lines) implementing full FORMAT.md Section 10 decode pipeline
|
|
- Verified byte-identical extraction against Rust archiver output (ASCII and Cyrillic filenames)
|
|
- Implemented xxd/od auto-detection fallback for hex conversion on minimal busybox systems
|
|
- HMAC graceful degradation: detects openssl HMAC support at startup, skips with warning if unavailable
|
|
|
|
## Task Commits
|
|
|
|
Each task was committed atomically:
|
|
|
|
1. **Task 1: Create shell/decode.sh with full decode pipeline** - `6df2639` (feat)
|
|
|
|
## Files Created/Modified
|
|
- `shell/decode.sh` - Busybox-compatible POSIX shell script implementing complete archive decode pipeline
|
|
|
|
## Decisions Made
|
|
- Used POSIX sh (not bash) with no bash-specific syntax for maximum compatibility
|
|
- Auto-detect xxd vs od at startup; define read_hex using whichever is available
|
|
- Graceful HMAC degradation: test openssl HMAC capability at startup, set SKIP_HMAC flag
|
|
- Extract ciphertext to temp file before decryption (avoids pipe buffering issues with openssl enc)
|
|
- Set LC_ALL=C at script top for predictable byte handling across locales
|
|
- Used printf-based substring extraction instead of bash ${var:offset:len} for POSIX compliance
|
|
|
|
## Deviations from Plan
|
|
|
|
None - plan executed exactly as written.
|
|
|
|
## Issues Encountered
|
|
None.
|
|
|
|
## User Setup Required
|
|
None - no external service configuration required.
|
|
|
|
## Next Phase Readiness
|
|
- Shell decoder complete, ready for cross-validation testing in Plan 2
|
|
- Script verified against Rust archiver with both ASCII and Cyrillic filenames
|
|
- Phase 6 (obfuscation) can extend the script with XOR header deobfuscation and TOC decryption
|
|
|
|
---
|
|
*Phase: 05-shell-decoder*
|
|
*Completed: 2026-02-25*
|