C++ API

The repository exposes reusable CMake targets and headers alongside the CLI.
They are source-level interfaces: the installation target currently installs
only csha, not a packaged SDK. Examples here assume the CSha source tree is
available to the parent CMake project.

Link the core library

A small parent project can add the checkout as a subdirectory:

Replace the absolute example path. Configuration still discovers the dependencies
of the repository's full CMake project, even if your executable links only one
target. Includes and transitive libraries are supplied by the linked target.
Use Ninja and upstream Clang 16 or later. Keep CXX_EXTENSIONS OFF on consuming
targets so their language mode matches the compiled module. Select the compiler before the parent
project() call; the subdirectory cannot change an already selected compiler.
On macOS with Homebrew LLVM, configure the parent project with:

cmake -S . -B build -G Ninja \
  -DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++" \
  -DCMAKE_OSX_SYSROOT="$(xcrun --show-sdk-path)"
cmake --build build --target roundtrip
./build/roundtrip

On Linux, select the installed upstream Clang with -DCMAKE_CXX_COMPILER=clang++;
omit the macOS SDK option. See Building and installation.

Complete binary round trip

Save this as roundtrip.cpp. The example demonstrates explicit AES settings,
PNG serialization through a data URL, and a payload containing a NUL byte.

Configure and build the parent project with CMake, then run its roundtrip
executable. It reports Recovered 11 bytes in addition to library diagnostics.
The code uses std::string as a byte container; write data() and size() to a
binary output stream when storing recovered data. Do not use a NUL-terminated
string conversion for arbitrary file bytes.

Core operations

Include CSha.h and link csha_core.

Method	Inputs and result
`encode_aes(data, key, mode, derive, cipher)`	Returns an encrypted `cv::Mat`
`decode_aes(image, password, key, mode, derive)`	Returns recovered bytes as `std::string`; ordinary AES uses the key input
`encode_zip(path, key, mode, derive, cipher)`	Reads an archive, Base64-wraps it, and returns an encrypted image
`decode_zip(image, password, output, key, mode, derive)`	Restores archive bytes to a file
`generate_map(seeds, mc_version)`	Returns a biome map with embedded seed metadata
`extract_seeds_from_map(image)`	Returns `std::vector<SeedData>`
`image_to_seed(image, salt, gen_seed)`	Hashes image content when `gen_seed` is true, otherwise reads metadata
`generate_env_map(data, password, key, mode, derive, cipher)`	Returns a map containing encrypted data
`decode_env_map(image, password, key, mode, derive)`	Recovers the map payload using matching settings
`embed_png_text(bytes, keyword, text)`	Adds a PNG text chunk and returns PNG bytes
`extract_png_text(bytes, keyword)`	Reads a PNG text chunk; returns empty when absent

The optional final cipher defaults to csha::crypto::Cipher::AES. Pass, for
example, Cipher::ChaCha20Poly1305 to select another algorithm; decoders detect
its stored envelope. See Encryption algorithms for compatibility
and key-derivation differences.

SeedData contains world_seed, hex, mc_version, spawn_x, and spawn_z.
encode_sha / decode_sha support the legacy SHA representation/verification
path; a hash is not reversible encryption of the original input.

Some core methods print diagnostics to stdout and some return an empty value
for an empty image rather than throwing. Validate input matrices, inspect return
values, and handle exceptions; do not assume a fully uniform error contract.
The high-level defaults are GCM/PBKDF2; see Formats and keys before
using lower-level AES primitives or compatibility settings.

Image-pair and data URL helpers

These free functions are also in csha_core:

Load credentials as nonempty BGR images, for example with cv::imread's default
color mode. Image-pair encoding is bounded by its single-map payload capacity;
either original credential image may be supplied when recovering. URL decoding
accepts a complete PNG data URL, not the CLI's @filename shorthand. File
reading for that shorthand happens in the CLI adapter.

Stream sessions

Include streams/blob_stream.h and link csha_blob_streams.
generate_identity() returns a local private PEM and public certificate PEM;
fingerprint(certificate) returns the identity fingerprint to verify with the
peer. Construct Session(Role, Identity, trusted_peer_certificate) only after
establishing that peer trust.

Method	Caller responsibility
`ready()`	Wait until handshake completion before sending plaintext
`receive(data, size)`	Feed ordered ciphertext in chunks no larger than 16 KiB
`send(data, size)`	Supply at most 16 KiB of plaintext per call
`take_ciphertext()`	Drain and forward handshake, data, and shutdown bytes
`take_plaintext()`	Drain authenticated received bytes
`finish()`	End local sending; keep forwarding output and receiving peer data
`peer_finished()` / `local_finished()`	Track independent directional completion
`transport_eof()`	Validate that a transport close follows authenticated shutdown

Use one owner/thread, honor backpressure, and discard failed sessions. The
Blob Streams guide explains the complete transport loop and
atomic-file completion requirements. The engine does not preserve application
message boundaries.

Docker archive codec

Include docker/image_archive.h and link csha_docker_image.
Key is std::array<unsigned char, 32>. generate_key() creates a key.
encode_archive(tar_fd, png_fd, key, image_id, reference, cipher) and
decode_archive(png_fd, tar_fd, key) return Info with the image ID, reference,
archive size, SHA-256 digest, and cipher. The optional encode cipher defaults
to AES; decoding detects the stored algorithm.

The caller owns all file descriptors and positions them at offset zero. Pass
-1 as the output archive descriptor to verify without retaining plaintext.
On a failure, discard provisional output; decoding may have written bytes
before the final authentication result. Publish a restored archive only after
successful return. The codec functions do not call Docker; the CLI adapter
handles image resolution, save/load, tags, and process exit codes.

Shared encoder interface

src/crypto/encoder.ixx exports the C++20 module csha.encoder, including
Cipher, EncoderConfig, Encoder, and StreamingEncoder. Link
csha_ciphers for the cipher implementations, or csha_core for the factory
and the high-level image APIs. Include crypto/encoder_factory.h to call
csha::crypto::make_encoder(config); that header imports the module.

Set config.mode = AESMode::GCM explicitly for authenticated AES: the lower-level
configuration defaults to CBC for compatibility. Encoder::encode produces
ciphertext bytes, not a PNG. Encoder::decode returns a string containing the
recovered bytes and verifies authentication for authenticated algorithms.

Streaming callers must treat output from process as provisional until
verify succeeds. finish produces the encryption tag. These operations are
stateful; do not reuse a completed encoder for another message. The Docker
codec handles framing and safe output completion when that is the desired format.

CLI entry helper

heler.h declares int csha::run_cli(int argc, char* argv[]). It belongs to the
executable target and is used by the five-line main.cpp. It is not the embedding
API: it uses process-global getopt state, writes to standard streams, and
legacy validation may call exit. Library consumers should call the modules
above instead of invoking the CLI parser repeatedly inside another process.

Link the core library#

Complete binary round trip#

Core operations#

Image-pair and data URL helpers#

Stream sessions#

Docker archive codec#

Shared encoder interface#

CLI entry helper#