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

pip install pdf-stego

From source

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.

# 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