pdf-stego 0.1.0

Structure-based PDF Steganography tool

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

With uv

uv sync

This installs the package in development mode with all dependencies.

With pip + venv

python -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows
pip install -e .

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.

# 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

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