f5

f5

A pure-Go toolkit for the F5 JPEG steganography algorithm (Westfeld, 2001): embed a message into the quantized DCT coefficients of a JPEG, extract it back, produce f5.jar-compatible carriers, and statistically detect F5 with the Fridrich–Goljan–Hogea (2002) attack.

The module is split into independent, narrowly scoped packages. A Go module is the unit of review and release; a Go package is the unit of compilation. So a build only ever compiles the capability it imports — importing embed never compiles detect or encode, and the lightest path pulls in no JPEG codec.

import path: github.com/0verkilll/f5

Packages

embed and extract operate on coefficient slices, not pixels: obtain the coefficients from a JPEG decoder, embed or extract, then re-encode (for example with encode). Keeping the codec out of these two packages is what lets them compile to TinyGo/WebAssembly.

Install

go get github.com/0verkilll/f5

Usage

Embed

import "github.com/0verkilll/f5/embed"

result, err := embed.Embed(coefficients, "passphrase", []byte("hidden message"))
if err != nil {
	return err
}
// result.KParameter, result.BytesEmbedded, result.ShrinkageCount

Extract

The extractor is constructed with an injected SHA-1 Hasher, a Fisher-Yates Permutator, and the PRNG factory, so the extraction PRNG path mirrors embedding exactly. See examples/roundtrip for the two small adapters that bridge the upstream sha1 and fisheryates primitives.

import "github.com/0verkilll/f5/extract"

extractor := extract.NewExtractor(hasher, permutator,
	extract.WithPRNGFactory(f5prng.NewDefaultFactory()))

message, err := extractor.ExtractBytes(coefficients, "passphrase")

Encode

import "github.com/0verkilll/f5/encode"

jpegBytes, err := encode.WeeksEncodeToBytes(img, 80) // quality 1..100

Detect

import "github.com/0verkilll/f5/detect"

detected, confidence, err := detect.DetectF5(jpegBytes)

result, err := detect.Analyze(jpegBytes)
// result.Verdict (clean / stego_detected / inconclusive), result.Beta, result.Quality
// result.Signatures — structural carrier fingerprint (see below)

Alongside the statistical β attack, Analyze attaches a set of structural signatures (result.Signatures, also detect.Signatures(jpegBytes) standalone) that fingerprint the JPEG itself rather than its statistics. None of them mean "F5" on their own; added up they describe whether an image is a plausible F5 carrier and what encoder produced it:

• decodable_format — baseline or progressive frame (F5 coefficients survive); lossless/re-encoded means they are gone
• embedding_capacity — has usable non-zero AC coefficients (a solid black/white image cannot carry F5)
• chroma_420 — 4:2:0 subsampling, the James/f5.jar encoder's fixed mode
• weeks_app0 — the JFIF APP0 f5.jar writes (units=0, density 1×1)
• weeks_com — the James R. Weeks copyright COM comment (with f5.jar's length-field truncation)
• ijg_quant_tables — luminance quantization table on the standard IJG quality curve

Score is the summed weight of matched signatures (0–1); CarrierViable is a hard gate (decodable format with real capacity). This is useful precisely when β is inconclusive — e.g. a double-compressed f5.jar stego can saturate β yet still score 1.0 on the structural signatures. f5 detect prints them; -json includes the full report.

Runnable versions of all four live under examples/:

go run ./examples/embed
go run ./examples/roundtrip   # embed then extract
go run ./examples/encode
go run ./examples/detect

Command-line tool and TUI

cmd/f5 is a single binary that drives the whole toolkit. Run it with no arguments on a terminal for an interactive Bubble Tea UI; pass a subcommand to script it. The UI dependency (Bubble Tea) lives only in this command — importing any library package never pulls it in.

go build -o f5 ./cmd/f5

f5                      # interactive TUI (menu: detect / embed / extract / encode)
f5 detect    in.jpg [-threshold T] [-json]
f5 embed     cover.jpg -p PASS (-m "msg" | -in msg.txt) -o stego.jpg
f5 embed-jar image.png -p PASS (-m "msg" | -in msg.txt) [-q 80] -o stego.jpg
f5 extract   stego.jpg -p PASS [-o out.bin]
f5 encode    image.png [-q 80] -o out.jpg
f5 help

The file argument may come before or after the flags. embed/extract decode the JPEG to DCT coefficients, run F5, and (for embed) re-encode with the original image metadata, so f5 embed … && f5 extract … round-trips a message through a real JPEG.

embed-jar is the bit-exact path: it takes pixels (PNG/JPEG/GIF) and reproduces the reference f5.jar's encode + embed exactly, so the output JPEG is byte-for-byte identical to what f5.jar would produce for the same pixels, message, password, and quality. The library entry point is encode.EmbedJPEGIdentical(img, quality, password, message); encode.WriteBMP24 emits the 24-bit BMP f5.jar reads, for cross-checking.

Design

• Single responsibility per package. Each capability is self-contained; the root package is documentation only, with no facade that would couple them.
• Dependency inversion. Optional logging and localization are injected through small interfaces (SetLogger, SetTranslator) and default to no-ops, so a minimal build links neither a logger nor the locale tables.
• Pay for what you import. Shared algorithm code lives once under internal/ (permutation, coefficient, valid, logx). The locale tables live in the opt-in i18nx package, which no library package imports.
• No cgo, no unsafe, no panics in library code. All errors are returned. Enforced by forbidigo, gosec, and errcheck (with check-blank).

TinyGo / WebAssembly

Every package builds for both standard GOOS=js GOARCH=wasm and TinyGo -target=wasm. embed and extract are the lightest (no JPEG codec); encode and detect are larger because they pull in the JPEG codec, but still compile under TinyGo.

Localization

Error messages default to English. To localize, inject a translator built from the bundled locale tables:

import "github.com/0verkilll/f5/i18nx"

t, _ := i18nx.NewTranslator("es-ES")
embed.SetTranslator(t)
extract.SetTranslator(t)

Because library code depends only on a small translator interface (never on i18nx), builds that skip localization do not compile the locale tables.

Security notes

• F5 seeds its permutation PRNG with the password via Java's SHA1PRNG for byte-parity with the reference f5.jar. SHA1PRNG is not a modern KDF; the password protects ordering, not the payload. Encrypt sensitive payloads before embedding.
• F5 is statistically detectable. The detect package implements the published 2002 attack against it. Treat F5 as a study/forensics subject, not as a secure channel.

Development

The module depends on a set of github.com/0verkilll/* primitive modules (f5core, f5coefficient, f5matrix, f5prng, fisheryates, securerandom, sha1, jpeg, logger, i18n), each published with its own v1.0.x tag, so a plain go get github.com/0verkilll/f5 resolves them from the public proxy. No replace block is needed.

Only cmd/f5 depends on Bubble Tea (github.com/charmbracelet/*); those modules resolve normally from the public proxy.

Verification matrix (build, vet, race tests, lint, wasm, TinyGo, and the dependency-segregation assertions):

./scripts/verify.sh

Run tests and fuzzers directly:

go test ./...
go test ./extract -run=x -fuzz=FuzzExtract -fuzztime=30s

References

• A. Westfeld. F5 — A Steganographic Algorithm: High Capacity Despite Better Steganalysis. Information Hiding 2001, LNCS 2137. (docs/)
• J. Fridrich, M. Goljan, D. Hogea. Steganalysis of JPEG Images: Breaking the F5 Algorithm. Information Hiding 2002, LNCS 2578. (docs/)

License

MIT. See LICENSE.