Metadata-Version: 2.4
Name: pdf-stego
Version: 0.1.3
Summary: Structure-based PDF Steganography tool
Project-URL: Homepage, https://github.com/samijuvaste/pdf-stego
Project-URL: Repository, https://github.com/samijuvaste/pdf-stego
Project-URL: Issues, https://github.com/samijuvaste/pdf-stego/issues
Author: Sami Juvaste
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click
Requires-Dist: cryptography
Requires-Dist: pikepdf
Description-Content-Type: text/markdown

# pdf-stego

Structure-based PDF watermarking — implementation of the scheme from Jiang et al. [1].

Embeds watermarks or arbitrary payloads as dictionary entries in Font Dictionary Objects and XObjects within the PDF structure. The embedding is invisible, produces zero visual distortion (SSIM = 1.0), and survives content editing, page extraction, and textbox-level attacks.

> **Note:** Most of the code was generated by Claude Opus 4.6 and Gemini 3.1 Pro running in Antigravity.

## Installation

```bash
pip install pdf-stego
```

### From source

```bash
git clone https://github.com/samijuvaste/pdf-stego.git
cd pdf-stego
uv sync
```

## Usage

### CLI

> **Tip:** Run `pdf-stego --help` or `pdf-stego <command> --help` (e.g. `pdf-stego embed --help`) to see all available flags for each subcommand.

```bash
# Embed a payload (split across objects, default mode)
pdf-stego embed -i document.pdf -o payload.pdf -f payload.txt

# Embed a watermark (redundant copy to every object)
pdf-stego embed -i document.pdf -o watermarked.pdf -m "my watermark" --mode watermark

# Embed with AES encryption and explicit ordering
pdf-stego embed -i document.pdf -o encrypted-payload.pdf -m "secret" --encryption aes --key "passphrase" --order forwards

# Extract (flags must match what was used during embed)
pdf-stego extract -i payload.pdf
pdf-stego extract -i watermarked.pdf --mode watermark
pdf-stego extract -i encrypted-payload.pdf --encryption aes --key "passphrase" --order forwards

# Show object counts and watermark status
pdf-stego info -i document.pdf
```

> **Important:** Extraction requires the same `--mode`, `--order`, `--seed`, `--channel`, and `--encryption`/`--key` flags that were used during embedding.

### Python API

```python
from pdf_stego import embed, extract, info

# Embed
embed("input.pdf", "output.pdf", "my watermark", mode="watermark")

# Embed with encryption
embed("input.pdf", "output.pdf", "secret", encryption="aes", encryption_key="passphrase")

# Embed payload from a file
from pathlib import Path
embed("input.pdf", "output.pdf", Path("payload.txt"))

# Extract (parameters must match embed)
data = extract("watermarked.pdf")
data = extract("watermarked.pdf", encryption="aes", encryption_key="passphrase")
data = extract("watermarked.pdf", mode="watermark", output="extracted.bin")

# Inspect
info("document.pdf")
```

## Modes

- `payload` (default) — Base64-encodes the input and splits it across available objects to maximize capacity. Each chunk is independently decodable. Can be ordered via `--order` (`forwards`, `backwards`, or `random`). A `--seed` can be supplied for `random` ordering (default: `0`).
- `watermark` — Embeds the full data into every available object for maximum redundancy and survivability.

## Channels

- `font` — Embed in Font Dictionary Objects only
- `xobject` — Embed in Image/Form XObjects only
- `both` (default) — Embed in both channels

## Encryption

- `none` (default) — No encryption
- `aes` — AES-256-GCM with PBKDF2 key derivation

## Reference

[1] Jiang, Z., Wang, H. & Han, S. A robust PDF watermarking scheme with versatility and compatibility. Multimed Tools Appl 83, 64341-64367 (2024). <https://doi.org/10.1007/s11042-024-18151-w>
