Formats and keys

Several CSha features produce PNGs, but their payload formats and credentials
are different. Choose the decoder that matches the encoder; a .png extension
does not identify the CSha format inside it.

Format selection

Output	Create	Recover or inspect	Credential and storage model
Encrypted pixel image	`es`, `ef`, `ez`, `ens`, `pe`	`di`, `ds`, `pd`; `dz` for ZIP	Symmetric key input `-p`; image and plaintext held in memory
Environment map	`f`, `fz`	`fd`, `fdz`	`-P` plus `-p`; encrypted payload embedded across map pixels
Seed map	`mfs`; optional map output from `mfi` / `mfz`	`dm`, `mts`	Seed metadata; does not recover the original source file
Image-password map	`f` with two `--key-image` inputs	`fd` with either one	Random payload key wrapped independently for each image
Docker archive PNG	`docker-image pack`	`inspect`, `restore`, `load`, `run`	Separate 32-byte key file; archive streamed via private temporary files
PNG data URL	`--data-url-output`	`--image-data-url`	Text transport for the same PNG, not another encryption layer
Blob Stream	`blob-streams listen` / `connect`	Peer session	TLS 1.3 device identities; no PNG or offline archive

-p / --public-key is the input from which the image encryption key is derived.
The name is historical: these image operations do not use an asymmetric
public/private-key pair. Treat this value as a secret.

-P / --password has mode-dependent meaning. In pe and ens it is the
plaintext being encoded. In ordinary f it is both the plaintext and the
password used by the environment-map path. In fd and fdz, supply the same
password used during encoding. For es, plaintext comes from -s; for ef
it comes from -f. Supplying -P does not replace the -p key for those modes.

Image-pair mode uses image-derived credentials instead of -p. Docker PNGs
require their binary key file. Blob Streams use local PEM identities and a
trusted peer certificate. These credentials are not interchangeable.

AES configuration

The CLI and high-level CSha methods default to AES-GCM with PBKDF2. Keep the
same mode and derivation selection for encoding and decoding. The low-level
AESConfig constructor defaults to CBC, so library callers should choose their
mode explicitly when working at that level.

Setting	Current implementation
`-A GCM`	AES-256-GCM with authentication tag
`-A CBC`	AES-256-CBC; no separate message authentication tag
`-A CTR`	AES-256-CTR; no separate message authentication tag
`-k PBKDF2`	PBKDF2-HMAC-SHA256, 10,000 iterations in `CSha`, fixed `table_salt_v1` salt
`-k DIRECT`	SHA-256 of the supplied key input
`-k FIXED`	Built-in constant AES key; provides no user-specific key secrecy

These are descriptions of the current code, not a claim of an independently
audited cryptographic design. A successful decode under unauthenticated CBC or
CTR is not evidence of integrity. The CLI exposes no PBKDF2 iteration or random
KDF-salt option; -a is used by image-to-seed conversion, not by the AES KDF.

Alternative authenticated ciphers

--cipher NAME selects one of ten additional algorithms listed in
Encryption algorithms. Password-based images use a fresh 16-byte
salt and PBKDF2-HMAC-SHA256 with 600,000 iterations. This differs from the legacy
AES derivation above. Non-AES encoding rejects -A, -k DIRECT, and -k FIXED.
Decoders read the algorithm from the authenticated envelope automatically.

Image-pair maps use image-derived key material; Docker PNGs use their binary
key file. These paths do not apply a password KDF. New cipher formats need a
current decoder; legacy AES outputs retain their existing formats.

Pixel preservation and data URLs

AES images carry a versioned binary header and explicit ciphertext length.
PNG I/O preserves the encoded BGR bytes. The decoder also accepts the legacy
pixel format, but older binaries cannot read the new length-header format.
Legacy ciphertext ending in zero retains the old format's ambiguous padding
limitation; the new format records its actual length.

Data URLs wrap encoded PNG bytes in Base64. They are larger than the binary
PNG and must use the data:image/png;base64, prefix. @file input can have a
trailing newline. Other MIME types and malformed Base64 are rejected. A data
URL remains fully usable offline and does not upload anything to a service.

Map capacity and image credentials

Image-password maps accept at most 196,432 plaintext bytes in a single
512-by-512 map with default AES-GCM, or 196,288 bytes with an alternative
cipher. The selected authenticated cipher protects both the payload and the
two key slots. A key image is identified by its dimensions and decoded BGR
pixels. Renaming the file does not change the credential; resizing or editing
its pixels does. Either original image can unlock the entire payload. Possession
of one image is sufficient; both are not required at recovery time.

Ordinary environment maps have their own payload framing and capacity checks.
Their usable plaintext capacity is not the same number as the image-pair limit.
An oversized payload fails rather than being silently truncated. Do not estimate
capacity solely from the visible dimensions or assume compression always makes
an arbitrary input fit.

Seed metadata stays in the first row of newly generated maps. More than 56
seeds at a 512-pixel width cause horizontal expansion by a whole scale factor.
The reader accepts older multi-row seed maps. This metadata layout is separate
from the low-order pixel bits used by environment payloads.

Large inputs and compatibility boundaries

ef, ez, and ordinary image APIs use memory proportional to input size.
The ZIP image route also Base64-encodes the archive. These paths are not a
bounded-memory stream. Docker archive PNGs instead process 64 KiB archive
blocks and one PNG row, with a 63 GiB archive limit and temporary disk usage.
Blob Streams limit each API call to 16 KiB and internal queues to 256 KiB.
See their guides for output completion and backpressure rules.

Keep the producing CSha version, the mode, non-default AES choices, and the
appropriate credentials with your recovery process. Keep credentials separate
from shared encrypted artifacts. Core image CLI logs are human-readable and
some legacy paths print command lines containing supplied keys; avoid collecting
those logs as public artifacts.

For known command limitations, see Troubleshooting.

Formats and keys

Format selection#

The image CLI's two key-related flags#

AES configuration#

Alternative authenticated ciphers#

Pixel preservation and data URLs#

Map capacity and image credentials#