Security¶
Threat model¶
Lightferry is meant to move data across an air gap while letting the receiver trust where it came from.
In scope:
- A bystander who can show codes to the receiver's camera, or play sounds, cannot inject data: every packet carries an HMAC-SHA256 tag keyed from the pre-shared key and session nonces.
- Replayed or reordered packets are rejected (4096-wide sliding replay window per direction).
- Packets from a previous session fail the MAC because each session draws fresh nonces.
- Audio replies are keyed tokens bound to the session and the packet they answer. A recorded sender screen replayed later is refused: the receiver keeps used sender nonces in
<dest>/.lightferry-seen(fails closed withDEST_NOT_WRITABLE). - Bad audio tokens are rate limited: more than 20 in a minute pauses acceptance.
- A malicious or corrupted archive cannot write outside the destination.
Out of scope:
- Confidentiality. Data is signed, not encrypted. Anyone who sees the screen or camera feed can read it.
- Compromised endpoints, or someone who holds the key.
- Denial of service: jamming the optical or audio path stops a transfer (it aborts, it does not corrupt).
- The key's transport. You move it by hand.
Key handling¶
lightferry keygenwrites 32 random bytes with mode 600 and never overwrites.- Keys shorter than 16 bytes are refused.
- Prefer
--key-fileorLIGHTFERRY_KEYover--key, which is visible in the process list. - Never commit keys. The repository ignores
*.keyand.env. - The phone test client never receives the key; all key use stays on the host.
- Phone server: binds the LAN IP only (
--hostoverrides), one WebSocket client (a second gets HTTP 409), a fresh self-signed cert per run in a private temp dir that is removed once loaded, a token on every request. Debug output only withLIGHTFERRY_DEBUG=1.
VERIFY code¶
A 6-digit code derived from the session keys and manifest hash. On real hardware the operator compares it by eye and answers y/N on the console (phone server: on-screen buttons); no answer aborts with VERIFY_TIMEOUT. Only test channels (--camera dir:, --yes) confirm automatically, and --yes with a real webcam is an error.
In audio mode the sender can only hear a 16-bit token, so it reports success as "unconfirmed"; the receiver's console is authoritative (the archive sha256 is always checked there).
Replay and sessions¶
Each side draws a fresh nonce per session; keys and the session id derive from both. Engines are single use. Audio message sequence numbers are 16-bit, so a session should stay well below 65536 messages per direction.
Archive extraction safety¶
On the receiver the archive is validated before anything touches the destination:
- Manifest schema, total size and SHA-256 checked before extraction; decompression is bounded (1 GiB default, 256 MiB LZMA memory).
- Extraction goes to a private (mode 700) temp directory inside the destination, files and directories are cross-checked against the manifest, then moved into place; an overwrite is rolled back if it fails.
- Path rules: forward-slash, relative, NFC-normalised, no absolute paths,
.., reserved Windows names, forbidden characters, trailing dots or spaces, case or Unicode collisions, over-long names. - Symlinks are skipped when packing.
- Existing items are never replaced without
--overwrite.
Everything is held in RAM; plan for a few times the transfer size in memory.
Reporting¶
Report vulnerabilities privately through the repository's GitHub security advisories.