Package zeroecho

package zeroecho
Command-line tooling built around streaming cryptographic pipelines for encryption, tagging, key management, and covert transport.

This package provides a small set of composable subcommands exposed through a single dispatcher and implemented on top of builder-style SDK components. The design favors streaming I/O so large inputs are never fully buffered in memory, and it emphasizes strong defaults with explicit opt-ins for advanced parameters.

Design goals

  • Single front end, multiple tools: the ZeroEcho dispatcher selects a subcommand and passes through the remaining CLI arguments to it, allowing each tool to define its own options without global conflicts.
  • Streaming composition: subcommands assemble DataContent chains so input is transformed on the fly (encrypt, tag, verify, embed) and written to the destination stream. This keeps memory usage low and makes stdin/stdout a first-class I/O mode.
  • Safe, explicit defaults: symmetric modes default to authenticated variants when available, headers are on by default when they carry required parameters, and verification errors cause clear exit codes and cleanup of incomplete outputs.

Core ideas and algorithms

The tools build on two families of primitives:

  • Asymmetric/KEM envelopes: hybrid encryption encapsulates a content-encryption key with a chosen KEM, then applies a symmetric cipher (AES-GCM/CTR/CBC or ChaCha AEAD/stream). HKDF-SHA256 is supported for deriving the payload key from the KEM secret, with limits on accepted KEM-ciphertext sizes.
  • Trailer tags: a trailer at the end of the stream carries either a digital signature or a digest. Produce mode computes and appends the tag; verify mode validates and strips it, returning a non-zero status on mismatch.

Key material is loaded from a simple, text-based keyring that supports listing, generation, and import/export of versioned snippets for both symmetric and asymmetric algorithms.

Subcommands overview

  • Guard - multi-recipient envelope that mixes public-key recipients and passwords, optionally shuffling recipients; payload is AES or ChaCha with optional header and AAD.
  • Kem - KEM-based hybrid encryption and decryption with AES or ChaCha payloads, HKDF support, counters/nonces, and compact symmetric headers.
  • KeyStoreManagement - maintenance of a text keyring: list algorithms and aliases, generate keys, and import/export versioned snippets.
  • Tag - produce or verify trailer tags using digital signatures or message digests.
  • CovertCommand - embed or extract a binary payload in JPEG files via configurable EXIF slots.

I/O conventions and exit codes

  • All tools accept "-" for stdin/stdout when appropriate, enabling shell pipelines.
  • Exit code 0 indicates success; non-zero codes signal parse errors, verification failures, or I/O problems. Verification failures attempt to remove partially written outputs.

Typical usage

# Multi-recipient envelope (AES-GCM) with shuffled recipients
ZeroEcho -G --encrypt in.bin --output out.enc \
  --keyring keyring.txt --to-alias alice --to-psw s3cret \
  --alg aes-gcm --tag-bits 128 --aad-hex DEADBEEF

# KEM + ChaCha AEAD with header
ZeroEcho -E --encrypt in.bin -o out.enc \
  --keyring keyring.txt --pub alice-pub \
  --kem ML-KEM --chacha --chacha-nonce 00112233445566778899AABB \
  --aad 01020304 --header

# Generate a key into the keyring
ZeroEcho -K --keystore keyring.txt --generate --alg Ed25519 --alias signing

# Trailer signature (produce/verify)
ZeroEcho -T --type signature --mode produce --alg Ed25519 \
  --ks keyring.txt --priv signing.prv --in file.bin --out file.tagged

# Covert EXIF embedding
ZeroEcho -C --embed --jpeg in.jpg --payload secret.bin --output out.jpg
Since:
1.0
  • Classes
    Class
    Description
    CovertCommand
    Command-line extension of ZeroEcho for covert embedding and extraction of binary payloads in JPEG files using EXIF metadata slots.
    Guard
    Guard is a unified subcommand that encrypts and decrypts using a multi-recipient envelope with AES or ChaCha payloads.
    Kem
    Command-line utility that performs hybrid file encryption and decryption using a KEM envelope and an AES or ChaCha payload.
    KeyStoreManagement
    Command-line utility for managing an encrypted software keyring.
    Tag
    CLI entry point for producing and verifying trailer tags based on digital signatures or digests.
    ZeroEcho
    ZeroEcho is a command-line utility for managing asymmetric keys and certificates, primarily focusing on Certificate Authority (CA) operations such as issuing, revoking, and listing certificates.