CSha

CSha is a C++20 command-line project for encoding data into PNG images with
AES or ten additional authenticated ciphers, generating SHA-256 image representations, and generating Minecraft biome
maps. It builds one application: csha.

Read the CSha documentation for installation,
commands, examples, and architecture.

Documentation guides

Start here	Reference and internals
Quick start	Commands and examples
Building and installation	Formats and keys
Blob Streams	C++ API
Docker images as PNGs	Architecture
Troubleshooting	Changelog
Testing	Encryption algorithms

Build and test

Dependencies: CMake 3.28+, Ninja 1.11+, upstream Clang 16+ with clang-scan-deps, a C compiler, OpenCV, OpenSSL 3.0+, Crypto++ 8.9+, zlib, libpng, libzip,
pkg-config, and Catch2 3 plus Python 3.9+ for tests. Cubiomes is bundled under third_party/
and compiled as C for map generation.

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
ctest --test-dir build --output-on-failure
csha --help

On macOS with Homebrew, install the dependencies; CMake discovers its OpenSSL
prefix automatically:

brew install cmake ninja llvm pkgconf opencv openssl@3 cryptopp libpng libzip catch2
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release

See building for Linux dependencies, CLI-only builds,
installation, and CLion setup.

Use

# Encode text as a PNG, then decode it.
csha -M es -s "Hello World" -p example-key -o encoded.png
csha -M di -i encoded.png -p example-key

# Generate a biome map from a seed.
csha -M mfs -S 12345678 -m 18 -o map.png

See commands and csha --help for the existing modes.

Encryption choices

csha --list-ciphers lists AES and ten additional authenticated cipher options.
Use --cipher NAME for images, files, ZIPs, maps and Docker PNGs. See
encryption algorithms for formats, key handling and examples.

Blob Streams

Live two-way encryption is available through csha blob-streams. Each device
has its own identity; an optional HTTP relay forwards ciphertext between them.
See Blob Streams for key exchange, direct/relay commands,
and the transport-independent C++ API.

Docker images as PNGs

csha docker-image pack --image NAME:TAG encrypts a saved Docker image into
actual PNG pixels. Restore the archive, load the image, or run it with the
matching key. See Docker image commands for examples.

Layout

CMakeLists.txt          Build, test, and install definitions
src/                   CLI and CSha implementation
  crypto/              AES, image encoding, and metadata
  map/                 Seed conversion and map generation
  streams/             Authenticated live byte streams
  docker/              Streamed Docker archive PNGs
third_party/cubiomes/  Bundled C dependency and upstream license
tests/                Catch2 tests
docs/                 Build, usage, and architecture notes

See architecture for the internal targets. Project code
is covered by LICENSE; Cubiomes retains its own
license.

Documentation guides#

Build and test#

Use#

Encryption choices#

Blob Streams#

Docker images as PNGs#