zxtx 0.2.2

ZXTX file format support.

ZXTX

ZXTX is a secure, compressed, and verifiable file format for structured text and binary data. It supports optional encryption, compression, and cryptographic signing, making it ideal for transmitting sensitive files safely.

Built in Python. Powered by cryptography.

Features

• AES-256-CTR + HMAC authenticated encryption
• LZMA and Zlib compression support
• Ed25519 and RSA signing and verification
• Structured file format with typed headers and bodies
• Command-line interface (CLI) for reading, writing, and inspecting .zxtx files

Installation

pip install zxtx

Or with uv:

uv add zxtx

Or just to test it out:

uvx zxtx --help

Usage

Writing a ZXTX file

zxtx write input.txt output.zxtx --cipher 1 --compression 1 -u private_key.pem -k public_key.pem -C certificate.pem

Reading a ZXTX file

zxtx read example.zxtx output.txt -u private_key.pem -k public_key.pem -C certificate.pem --verify

Dumping metadata

zxtx dump example.zxtx -u private_key.pem -k public_key.pem -C certificate.pem

Streaming (stdin/stdout)

ZXTX supports streaming via - for stdin/stdout, enabling pipe chains:

# Encrypt from stdin, write to file
echo "secret data" | zxtx write - output.zxtx --cipher 1

# Read from file, write to stdout
zxtx read input.zxtx - > output.txt

# Full pipe chain: encrypt, then decrypt
cat data.txt | zxtx write - - --cipher 1 | zxtx read - - > decrypted.txt

Signature Verification

Verify signatures during read operations:

zxtx read signed.zxtx output.txt --verify --certificate cert.pem

Interactive Password Prompt

If a private key is password-protected and no password is provided, ZXTX will prompt interactively:

zxtx read encrypted.zxtx output.txt --private-key mykey.pem
# Prompts: Enter private key password (or press Enter for none):

Progress Bars

When writing to files in an interactive terminal, ZXTX displays progress bars:

zxtx write largefile.bin output.zxtx --compression lzma
# Shows: Writing ZXTX file [████████████] 100%

---

Supported Methods

Cipher Methods

• 0: none
• 1: aes256_gcm
• 2: chacha20_poly1305
• 3: aes256_ctr_hmac

Compression Methods

• 0: none
• 1: zlib
• 2: lzma
• 3: brotli

Format Specification

The ZXTX file format is formally documented in SPECIFICATION.md. It defines:

• Magic header
• Versioning
• Field layout
• Signature embedding, etc

Security Notes

• ZXTX uses AEAD (authenticated encryption) to prevent tampering.
• Private keys can be password-encrypted.
• Signature verification ensures authenticity.
• Don't share your private key. Use a certificate for signing and a public key for verification.

Python API

Basic File Operations

from zxtx.highlevel import open

with open("file.zxtx", password=b"secret", public_key=b"...") as f:
    data = f.read_bytes()

Streaming API

Stream data without loading entire files into memory:

from zxtx.highlevel import read_stream, write_stream, read_stdin, write_stdout

# Read from any binary stream
with open("input.zxtx", "rb") as f:
    data = read_stream(f, private_key=private_key)

# Write to any binary stream
with open("output.zxtx", "wb") as f:
    write_stream(b"secret data", f, cipher=CIPHER_METHOD.AES256_GCM, public_key=public_key)

# Convenience functions for stdin/stdout
data = read_stdin(private_key=private_key)
write_stdout(b"data", cipher=CIPHER_METHOD.AES256_GCM, public_key=public_key)

Chunked Streaming for Large Files

Process large files in chunks to minimize memory usage:

from zxtx.highlevel import read_stream_chunked, write_stream_chunked

# Stream large file with progress callback
with open("large_input.bin", "rb") as infile, open("output.zxtx", "wb") as outfile:
    def progress(current, total):
        print(f"Processed: {current}/{total} bytes")

    write_stream_chunked(
        infile, outfile,
        compression=COMPRESSION_METHOD.ZLIB,
        chunk_size=1024*1024,  # 1MB chunks
        progress_callback=progress
    )

# Read back with chunked streaming
with open("output.zxtx", "rb") as infile, open("recovered.bin", "wb") as outfile:
    read_stream_chunked(infile, outfile, private_key=private_key)

See the zxtx.highlevel module for full API details.

License

MIT License – Copyright (c) 2025-2026 voyager-2021 (ZXTX)