Quick start

This walkthrough builds CSha and demonstrates three different outputs: an
encrypted PNG, a PNG data URL, and a Minecraft biome map. Commands run from the
repository root on macOS or Linux. Use a new directory for generated files;
ordinary image commands can replace existing output files.

Build the executable

Install the dependencies in Building and installation, then run:

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

The executable is build/csha. After installation you can use csha instead
of ./build/csha. The examples below use disposable demonstration key strings.
The -p option is a symmetric encryption-key input despite its historical name
--public-key; it is not a public certificate to share with everyone.

Encode and recover text

mkdir -p build/docs-demo
./build/csha -M es -s "Hello from CSha" -p demo-key -o build/docs-demo/message.png
./build/csha -M di -i build/docs-demo/message.png -p demo-key

The first command writes an encrypted image. The second prints diagnostic lines
followed by Decoded: Hello from CSha. Defaults are AES-GCM and PBKDF2. Preserve
the key and any non-default -A / -k choices with your recovery instructions.
Changing the key should make GCM authentication fail.

Keep the original PNG. A screenshot, resized copy, or JPEG conversion changes
the encoded pixels. Displaying the image is fine; editing it is not a supported
way to preserve the payload.

Put the PNG in a text file

./build/csha -M es -s "Hello from a data URL" -p demo-key \
  -o build/docs-demo/url-message.png --data-url-output build/docs-demo/message.url
./build/csha -M di --image-data-url @build/docs-demo/message.url -p demo-key

message.url starts with data:image/png;base64,. It contains the whole PNG,
not a web-hosted link. The @file form avoids passing a large value as a shell
argument. Do not specify --image and --image-data-url together.

Encode and recover an archive

The ZIP route writes restored bytes to a file, making it convenient for an
exact file comparison. It needs the zip command to prepare this example.

printf 'Example document\n' > build/docs-demo/note.txt
zip -j build/docs-demo/notes.zip build/docs-demo/note.txt
./build/csha -M ez -z build/docs-demo/notes.zip -p demo-key -o build/docs-demo/notes.png
./build/csha -M dz -i build/docs-demo/notes.png -p demo-key -Z build/docs-demo/restored.zip
cmp build/docs-demo/notes.zip build/docs-demo/restored.zip

cmp prints nothing and exits successfully when the archives are identical.
ez stores the archive in one encrypted image. It does not unpack the ZIP.

Generate a biome map

./build/csha -M mfs -S 12345678 -m 18 -o build/docs-demo/map.png
./build/csha -M dm -i build/docs-demo/map.png

The second command prints the embedded seed, version, and spawn coordinates.
This is a map visualization with seed metadata, not an encrypted copy of a
Minecraft world or a world-save directory.

Choose your next guide

Goal	Guide
Choose an encryption algorithm	Encryption algorithms
Run focused checks	Testing
Find mode names and flags	Commands and examples
Unlock a payload with either of two images	Image-password examples
Exchange live encrypted bytes between devices	Blob Streams
Store, restore, or run a Docker image from a PNG	Docker images as PNGs
Understand keys, compatibility, and size limits	Formats and keys
Call the code from another C++ target	C++ API
Diagnose configuration or decoding failures	Troubleshooting

Quick start

Build the executable#

Encode and recover text#

Put the PNG in a text file#

Encode and recover an archive#