Software Requirements Specification
Introduction
Purpose
This SRS defines MVP requirements for AirGap Transfer, a command-line utility for safely transferring large files across air-gap boundaries.
Scope
Product: AirGap Transfer — a minimal CLI tool for chunked file transfers via removable media.
In Scope:
Split large datasets into chunks for USB transfer
Reconstruct files from chunks with integrity verification
Resume interrupted transfers
Cross-platform support (macOS, Windows, Linux)
Out of Scope:
Network transfers, cloud sync, auto-updates
Compression or encryption (defer to post-MVP; cryptographic agility for hashing is in scope)
GUI interface
Real-time synchronization
Ollama-specific logic (general-purpose only)
Definitions
Term |
Definition |
|---|---|
Air-gap |
Physical separation between systems with no network connectivity |
Chunk |
A fixed-size tar archive containing a portion of source data |
Pack |
Operation to split source files into chunks |
Unpack |
Operation to reconstruct files from chunks |
Manifest |
Metadata file describing chunk inventory and checksums |
Cryptographic agility |
Ability to swap hash algorithms without rearchitecting the system |
Overall Description
Product Perspective
Standalone CLI tool for transferring data across air-gap boundaries using removable media. All operations occur locally with no network connectivity. See the Software Design Document for architecture diagrams and component details.
Constraints
Constraint |
Description |
|---|---|
Offline-only |
Zero network calls at runtime |
Air-gap ready |
Deployable without internet access |
Platforms |
macOS, Windows, Linux |
UI model |
Command-line interface only (no GUI) |
Media |
Works with standard removable media (USB, external drives) |
Functional Requirements
Pack Operation
ID |
Priority |
Title |
|---|---|---|
must |
Split Files into Chunks |
|
must |
Auto-Detect USB Capacity |
|
must |
Generate Chunk Checksums |
|
must |
Create Manifest File |
|
must |
Stream Data to USB |
|
should |
Manual Chunk Size Specification |
|
should |
Show Pack Progress |
|
should |
Prompt for USB Swapping |
|
should |
Resume Interrupted Pack |
|
must |
Pack Command |
Split source files/directories into fixed-size chunks |
Auto-detect USB capacity and set chunk size accordingly |
Generate checksums for each chunk using the configured hash algorithm (default: SHA-256) |
Create manifest file with chunk metadata and checksums |
Stream data directly to USB without intermediate temp files |
Support manual chunk size specification |
Show progress during chunk creation |
Prompt for USB swapping when multiple chunks needed |
Unpack Operation
ID |
Priority |
Title |
|---|---|---|
must |
Reconstruct Files from Chunks |
|
must |
Verify Chunk Checksums Before Unpack |
|
must |
Place Files in Destination |
|
must |
Validate Chunk Completeness |
|
should |
Resume Partial Unpacks |
|
should |
Delete Chunks After Unpack |
|
should |
Show Unpack Progress |
|
should |
Resume Interrupted Unpack |
|
must |
Unpack Command |
Reconstruct original files from chunks |
Verify chunk checksums before reconstruction |
Place reconstructed files in specified destination |
Validate chunk completeness (all chunks present) |
Resume partial unpacks if interrupted |
Optionally delete chunks after successful reconstruction |
Show progress during reconstruction |
List Operation
ID |
Priority |
Title |
|---|---|---|
must |
Display Chunk Inventory |
|
must |
Show Chunk Sizes and Status |
|
should |
Identify Missing Chunks |
|
should |
Display Estimated Total Size |
|
must |
List Command |
Display chunk inventory from manifest |
Show chunk sizes and verification status |
Identify missing or corrupted chunks |
Display estimated total size after reconstruction |
Integrity Verification
ID |
Priority |
Title |
|---|---|---|
must |
Verify Chunk Checksums Before Unpack |
|
must |
Show Chunk Sizes and Status |
|
must |
Generate Checksums |
|
must |
Verify Checksums During Unpack |
|
must |
Detect Corrupted Chunks |
|
should |
Verify Final File Checksum |
|
must |
No-Verify Flag |
Generate checksums during pack using the configured hash algorithm (default: SHA-256) |
Verify checksums during unpack |
Detect corrupted chunks and report errors |
Verify final reconstructed file against original checksum |
Cryptographic Agility
ID |
Priority |
Title |
|---|---|---|
must |
Configurable Hash Algorithm |
|
must |
Algorithm Identified in Manifest |
|
must |
Pluggable Hash Backend |
|
should |
AEAD Algorithm Default and Agility |
The system SHALL allow users to select a hash algorithm via CLI flag ( |
The manifest SHALL record which hash algorithm was used, so unpack can verify with the correct algorithm. |
The hash module SHALL use a trait-based interface so new algorithms can be added without modifying existing code. |
State Management
ID |
Priority |
Content |
|---|---|---|
must |
Maintain operation state in manifest file |
|
must |
Track chunk completion status |
|
should |
Support resume for interrupted pack operations |
|
should |
Support resume for interrupted unpack operations |
Maintain operation state in manifest file |
Track chunk completion status |
Support resume for interrupted pack operations |
Support resume for interrupted unpack operations |
Command Interface
ID |
Priority |
Title |
|---|---|---|
must |
Pack Command |
|
must |
Unpack Command |
|
must |
List Command |
|
must |
Dry Run Flag |
|
must |
No-Verify Flag |
|
should |
Chunk Size Flag |
|
should |
Verbose Flag |
|
|
|
|
Checksum verification SHALL be enabled by default for all operations. The |
|
|
Error Handling
ID |
Priority |
Content |
|---|---|---|
must |
Detect corrupted chunks and report errors |
|
must |
Detect and report insufficient USB capacity |
|
must |
Handle missing chunks gracefully |
|
must |
Provide clear error messages with suggested actions |
Detect and report insufficient USB capacity |
Handle missing chunks gracefully |
Provide clear error messages with suggested actions |
Safety Features
ID |
Priority |
Content |
|---|---|---|
must |
Confirm overwrite of existing files |
|
must |
Validate destination paths and permissions |
|
must |
Safely sync USB before prompting for removal |
|
should |
Atomic operations where possible |
Confirm overwrite of existing files |
Validate destination paths and permissions |
Safely sync USB before prompting for removal |
Atomic operations where possible |
Deployment
ID |
Priority |
Content |
|---|---|---|
must |
All dependencies available for offline build |
|
must |
Build process works without internet after initial setup |
|
should |
Single, static binary deployment |
All dependencies available for offline build |
Build process works without internet after initial setup |
Single, static binary deployment |
Non-Functional Requirements
ID |
Priority |
Content |
|---|---|---|
should |
Chunk creation time < 10 minutes for 10GB dataset |
|
must |
Memory footprint < 100 MB during streaming operations |
|
must |
All data stays on local/removable media; no network calls |
|
must |
100% functional offline |
|
must |
Build and run on systems with no internet access |
|
must |
Support macOS, Windows, Linux |
|
must |
The system SHALL verify all chunks using the hash algorithm specified in the manifest before reconstruction |
|
must |
Pack and unpack operations SHALL be idempotent (safe to run multiple times) |
|
must |
The system SHALL handle interruptions gracefully (Ctrl+C, system shutdown) and allow resume |
|
must |
The system SHALL detect and report data corruption via checksum mismatch |
|
must |
Progress indicators SHALL be shown for all operations taking longer than 2 seconds |
|
must |
Error messages SHALL include specific details about the failure and suggested fixes |
|
must |
The CLI SHALL provide help text accessible via --help for all commands |
|
should |
First-time users SHALL be able to transfer a file within 5 minutes using provided examples |
|
must |
The codebase SHALL achieve at least 80% test coverage |
|
must |
All public APIs SHALL have rustdoc documentation |
|
must |
The code SHALL pass cargo clippy with zero warnings |
|
must |
The code SHALL be formatted with rustfmt |
|
should |
The system SHALL handle files up to 100GB in size |
|
must |
Chunk operations SHALL use streaming architecture to handle files larger than available RAM |
|
could |
The system SHOULD support concurrent chunk verification to improve performance |
|
must |
The system SHALL be designed for cryptographic agility: hash algorithms are pluggable via a common trait interface, enabling adoption of new standards (e.g., post-quantum algorithms) without architectural changes. |
|
must |
The system SHALL NOT write passphrases or derived keys to disk, logs, or the manifest in plaintext. Passphrases SHALL be read from an interactive terminal prompt (with echo disabled) or from a file descriptor, and SHALL be zeroized from memory after key derivation completes. |
Performance
Chunk creation time < 10 minutes for 10GB dataset |
Memory footprint < 100 MB during streaming operations |
Reliability
The system SHALL verify all chunks using the hash algorithm specified in the manifest before reconstruction |
Pack and unpack operations SHALL be idempotent (safe to run multiple times) |
The system SHALL handle interruptions gracefully (Ctrl+C, system shutdown) and allow resume |
The system SHALL detect and report data corruption via checksum mismatch |
Usability
Progress indicators SHALL be shown for all operations taking longer than 2 seconds |
Error messages SHALL include specific details about the failure and suggested fixes |
The CLI SHALL provide help text accessible via –help for all commands |
First-time users SHALL be able to transfer a file within 5 minutes using provided examples |
Maintainability
The codebase SHALL achieve at least 80% test coverage |
All public APIs SHALL have rustdoc documentation |
The code SHALL pass cargo clippy with zero warnings |
The code SHALL be formatted with rustfmt |
Portability
Support macOS, Windows, Linux |
Scalability
The system SHALL handle files up to 100GB in size |
Chunk operations SHALL use streaming architecture to handle files larger than available RAM |
The system SHOULD support concurrent chunk verification to improve performance |
Security & Privacy
All data stays on local/removable media; no network calls |
The system SHALL be designed for cryptographic agility: hash algorithms are pluggable via a common trait interface, enabling adoption of new standards (e.g., post-quantum algorithms) without architectural changes. |
Deployment
100% functional offline |
Build and run on systems with no internet access |
v1.1 — SBOM-Aware Transfer Manifests
The following requirements are planned for v1.1 and are not in scope for the MVP release.
When a CycloneDX SBOM file ( |
The system SHALL log the presence and filename of any SBOM file in the transfer audit trail, providing chain-of-custody documentation for compliance purposes. |
v1.2 — Authenticated Encryption (AEAD) for Chunks at Rest
The following requirements are planned for v1.2 and are not in scope for the MVP release. These address the threat of USB interception by providing encryption at rest for chunk data and tamper detection for the transfer manifest.
The system SHALL support optional authenticated encryption of chunk data using an AEAD
construction. When a user provides a passphrase via |
The default AEAD algorithm SHALL be ChaCha20-Poly1305. The system SHALL support
algorithm selection via |
The system SHALL derive encryption keys from user-provided passphrases using a memory-hard key derivation function (Argon2id recommended). KDF parameters (algorithm, memory cost, time cost, salt) SHALL be recorded in the manifest so the unpack operation can reproduce the same derived key. |
Each chunk SHALL be encrypted with a unique nonce. Nonces SHALL be stored alongside chunk metadata in the manifest. Nonce reuse across chunks with the same key SHALL be treated as a fatal error. |
When AEAD encryption is enabled, the manifest SHALL be authenticated using a keyed MAC (HMAC-SHA256, KMAC, or BLAKE3 keyed mode) derived from the same passphrase. The manifest SHALL remain human-readable (unencrypted JSON) but SHALL include a MAC field that the unpack operation verifies before processing any chunks. Verification failure SHALL abort the unpack operation. |
When encryption is enabled, the manifest SHALL record: the AEAD algorithm used, the KDF algorithm and parameters (excluding the passphrase), per-chunk nonces, and the MAC algorithm used for manifest authentication. This metadata SHALL be sufficient for the unpack operation to decrypt and verify without out-of-band configuration. |
The system SHALL NOT write passphrases or derived keys to disk, logs, or the manifest in plaintext. Passphrases SHALL be read from an interactive terminal prompt (with echo disabled) or from a file descriptor, and SHALL be zeroized from memory after key derivation completes. |
Error Handling
Scenario |
Behavior |
|---|---|
Insufficient USB capacity |
Warn user, suggest smaller chunk size or larger USB |
Missing chunks during unpack |
List missing chunks, abort with clear error |
Checksum mismatch |
Identify corrupted chunk, abort with error |
Disk full during pack |
Stop operation, clean up partial chunk |
Permission denied |
Clear error message with required permissions |
USB disconnected during operation |
Detect failure, allow resume from last completed chunk |
Appendix: Chunk Format Specification
Manifest Structure
{
"version": "1.0",
"operation": "pack",
"source_path": "/path/to/source",
"total_size_bytes": 10737418240,
"chunk_size_bytes": 1073741824,
"chunk_count": 10,
"hash_algorithm": "sha256",
"chunks": [
{
"index": 0,
"filename": "chunk_000.tar",
"size_bytes": 1073741824,
"checksum": "sha256:abc123...",
"status": "completed"
}
],
"created_utc": "2026-01-04T12:00:00Z",
"last_updated_utc": "2026-01-04T12:15:00Z"
}
The hash_algorithm field identifies which algorithm was used. The checksum value prefix (e.g., sha256:) is redundant but kept for readability when inspecting manifests manually.
Chunk Naming Convention
Format:
chunk_XXX.tarwhere XXX is zero-padded chunk indexManifest:
airgap-transfer-manifest.json