qeltrix-v6 1.0.0

A useful paacakge for ultra high file encryption and routing

Qeltrix V6 — Network-Native Encrypted Streaming Container

Author: Muhammed Shafin P (@hejhdiss)
License: CC BY-SA 4.0
Architecture: C shared library (.so/.dll) + Python cryptography library Documentation: https://qeltrix-v6.hejhdiss.workers.dev/

⚠️ PROOF-OF-CONCEPT ONLY. Not for production/security-critical use without independent cryptographic audit.

Created fully with Claude Sonnet 4.6.

---

What is Qeltrix V6?

V6 is the network-native evolution of the Qeltrix encrypted archiving system. It turns any data stream into a live, seekable, encrypted V6 container — without needing the entire file first.

Key capabilities:

• On-the-fly encryption as data arrives from any source
• HTTP Range Request support — seek into encrypted files without full download
• Parallel processing via ThreadPoolExecutor (cross-platform, including Windows)
• Per-block integrity via SHA-256 + AEAD authentication tags
• Dual-layer key security — CDK wrapped in MK, V6-C metadata also encrypted
• Two AEAD ciphers: AES-256-GCM and ChaCha20-Poly1305
• Full Windows support — .dll built with MinGW, tested on Windows PowerShell

---

Architecture

┌──────────────────────────────────────────────────────────┐
│                    Qeltrix V6 System                     │
│                                                          │
│  ┌─────────────────────┐    ┌──────────────────────────┐ │
│  │  C Shared Library   │    │  Python (cryptography)   │ │
│  │  libqeltrix_v6.so   │    │                          │ │
│  │  qeltrix_v6.dll     │    │  ● AES-256-GCM           │ │
│  │                     │    │  ● ChaCha20-Poly1305      │ │
│  │  ● Block framing    │◄──►│  ● HKDF-SHA256 (CDK)     │ │
│  │  ● Permutation      │    │  ● SHA-256 hashing       │ │
│  │  ● Header/footer    │    │  ● Master key wrapping   │ │
│  │  ● TCP networking   │    │  ● V6-C metadata crypto  │ │
│  │  ● HTTP parsing     │    │                          │ │
│  │  ● Seek math        │    │                          │ │
│  └─────────────────────┘    └──────────────────────────┘ │
│                                                          │
│  ┌───────────────┐  ┌───────────────┐  ┌──────────────┐  │
│  │ pack/unpack   │  │ GatewayServer │  │  SeekServer  │  │
│  │ container.py  │  │ gateway.py    │  │ (HTTP+Range) │  │
│  └───────────────┘  └───────────────┘  └──────────────┘  │
└──────────────────────────────────────────────────────────┘

V6 Container Layout

[V6Header 416 bytes]
  ├── magic: "QLTX", version: 6
  ├── block_size, total_blocks, original_file_size
  └── footer_offset, footer_size

[Block 0]
  ├── prefix (28 bytes): magic + block_index + v6c_size + payload_size
  ├── v6c_iv (12 bytes)
  ├── encrypted V6-C metadata  ← Layer 2: whole metadata encrypted with MK
  │     └── contains IV, salt, encrypted_CDK  ← Layer 1: CDK encrypted with MK
  └── encrypted payload  ← AEAD encrypted with CDK (AES-GCM or ChaCha20)

[Block 1] ... [Block N]

[Footer]
  ├── magic: "QLTXFOOT", block_count, footer_hash
  └── BlockIndexEntry × N  (original_offset, container_offset, hash, …)

---

Build

Linux / macOS

cd c_lib
make
cp libqeltrix_v6.so ../python/qeltrix_v6/

Windows (MinGW / Git Bash)

cd c_lib
make                           # produces qeltrix_v6.dll
copy qeltrix_v6.dll ..\python\qeltrix_v6\

Requirements:

• Python 3.11+
• pip install cryptography
• GCC (Linux/macOS) or MinGW x86_64-w64-mingw32-gcc (Windows)

---

Python API

import qeltrix_v6 as qltx
from qeltrix_v6.crypto import random_master_key, CIPHER_AES256_GCM, CIPHER_CHACHA20_POLY1305

# ── Key generation ─────────────────────────────────────────────
mk = random_master_key()   # 32 secure random bytes

# Or derive from a passphrase:
import hashlib
mk = hashlib.pbkdf2_hmac("sha256", b"my-passphrase", b"salt", 200_000)

# ── Pack ───────────────────────────────────────────────────────
result = qltx.pack(
    "input.bin",                    # file path, bytes, or file-like
    "output.qltx",
    mk,
    block_size=1024*1024,           # 1 MB blocks (default)
    cipher_id=CIPHER_AES256_GCM,    # or CIPHER_CHACHA20_POLY1305
    workers=4,
)
print(f"{result.total_blocks} blocks, {result.elapsed_s:.2f}s")

# ── Unpack ─────────────────────────────────────────────────────
result = qltx.unpack("output.qltx", "recovered.bin", mk, workers=4)
print(f"Integrity: {'OK' if result.integrity_ok else 'FAILED'}")

# ── Seek (partial extraction, no full download needed) ─────────
data = qltx.seek_extract(
    "output.qltx",
    seek_offset=1_000_000,
    seek_len=500_000,
    master_key=mk,
)
# Only the blocks that contain those bytes are decrypted.

# ── Stream packing (live / gateway core) ───────────────────────
from qeltrix_v6.gateway import StreamPacker
import io

packer = StreamPacker(mk, block_size=256*1024, cipher_id=CIPHER_CHACHA20_POLY1305)
out = io.BytesIO()
packer.pack_stream(io.BytesIO(raw_data), out.write, total_size=len(raw_data))
packer.patch_header(out, total_size=len(raw_data))   # fix header if buf is seekable
container = out.getvalue()

# ── GatewayServer ──────────────────────────────────────────────
# Receives raw TCP data, encrypts on-the-fly, sends V6 stream back
gw = qltx.GatewayServer(
    mk,
    listen_host="0.0.0.0", listen_port=7620,
    cipher_id=CIPHER_AES256_GCM,
    workers=4,
    dest_host=None,   # None = reflect V6 stream back to sender
)
gw.start()   # non-blocking thread

# ── SeekServer (HTTP + Range Requests) ─────────────────────────
srv = qltx.SeekServer("output.qltx", mk, host="0.0.0.0", port=7621, workers=4)
srv.start()
# Clients can now do:
#   GET http://localhost:7621/  Range: bytes=0-1048575
# and receive exactly those bytes from the original file,
# with only the needed blocks decrypted.

---

CLI

cd python

# Pack a file
python -m qeltrix_v6 pack  input.bin output.qltx --passphrase secret

# Unpack
python -m qeltrix_v6 unpack output.qltx recovered.bin --passphrase secret

# Seek — extract byte range without unpacking the whole file
python -m qeltrix_v6 seek output.qltx --offset 1000000 --length 500000 \
    --passphrase secret --output extracted.bin

# Gateway server — encrypts all incoming connections on-the-fly
python -m qeltrix_v6 gateway --port 7620 --passphrase secret

# Gateway with downstream routing
python -m qeltrix_v6 gateway --port 7620 --passphrase secret \
    --dest-host storage.example.com --dest-port 9000

# HTTP Seek server with Range Request support
python -m qeltrix_v6 serve output.qltx --port 7621 --passphrase secret

# Container info (no passphrase needed)
python -m qeltrix_v6 info output.qltx

# Options
--cipher aes|chacha    Cipher (default: aes = AES-256-GCM)
--block-size N         Block size in KB (default: 1024 = 1 MB)
--workers N            Parallel workers (default: 4)
--no-verify            Skip per-block integrity checks (faster)

---

Running Tests

# From the project root (qeltrix_v6/)
python tests\test_all.py      # Windows
python tests/test_all.py      # Linux / macOS

Expected output:

============================================================
Qeltrix V6 Test Suite
============================================================
[C Library]
  ✓ version string  ✓ block count  ✓ block range  ...
[Cryptography]
  ✓ AES-256-GCM  ✓ ChaCha20-Poly1305  ✓ HKDF  ...
[Pack / Unpack]
  ✓ pack small file  ✓ unpack + verify integrity
  ✓ ChaCha20 roundtrip  ✓ seek extraction  ...
============================================================
Results: 20/20 passed — All tests passed!

---

Windows Notes

Why ThreadPoolExecutor instead of ProcessPoolExecutor

On Linux/macOS, ProcessPoolExecutor uses os.fork() — the child process inherits memory directly. On Windows there is no fork, so Python uses spawn: it starts a brand-new Python interpreter and re-imports your module from scratch in every worker. This causes the "bootstrapping phase" error if the module creates an executor at import time.

ThreadPoolExecutor avoids this completely — threads share process memory, no re-import needed. Crypto operations with the cryptography library release the GIL during computation, so threads still run in parallel for I/O and crypto.

Why if __name__ == '__main__': in test_all.py

Even with ThreadPoolExecutor, this guard is best practice on Windows for any script that uses concurrency. All test logic lives inside run_tests(), only called when the script is the entry point.

---

Platform Support

Platform	Library	Build command
Linux	.so	make in c_lib/
macOS	.dylib	make in c_lib/
Windows	.dll	make in c_lib/ (MinGW)

---

Cryptographic Design (V6cs Mode)

Master Key (MK)  ←  32 secure random bytes
        │
        ├─ HKDF(MK, block_index, block_hash, salt) → CDK
        │     Unique per block, bound to content AND position
        │
        ├─ AES-GCM(MK, CDK) → Encrypted CDK        [Layer 1]
        │     Stored in V6-C metadata block
        │
        └─ AES-GCM(MK, V6-C metadata) → Encrypted metadata  [Layer 2]
              Attacker without MK cannot read per-block keys

Block payload:
  CDK + random IV → AES-256-GCM or ChaCha20-Poly1305
  AAD = big-endian block_index  (binds ciphertext to position)

---

File Structure

qeltrix_v6/
├── c_lib/
│   ├── qeltrix_v6.c          ← C core (permutation, framing, TCP I/O)
│   └── Makefile
├── python/
│   └── qeltrix_v6/
│       ├── __init__.py       ← Public API
│       ├── __main__.py       ← python -m qeltrix_v6
│       ├── _clib.py          ← ctypes bindings to C library
│       ├── crypto.py         ← All crypto (cryptography library)
│       ├── container.py      ← Pack / Unpack / Seek
│       ├── gateway.py        ← GatewayServer / SeekServer / StreamPacker
│       ├── cli.py            ← CLI argument parsing
│       └── qeltrix_v6.dll    ← Windows: copy built DLL here
│           libqeltrix_v6.so  ← Linux: copy built .so here
├── tests/
    ├── test_all.py           ← 20 tests, run from project root
    ├── test_network.py       ← 14 tests, run from project root