f5messageembed

func ApplyDeZigZag ¶

func ApplyDeZigZag(shuffledIndex int) int

ApplyDeZigZag transforms a shuffled coefficient index using the JPEG de-zigzag table.

JPEG stores DCT coefficients in zigzag order to improve compression by grouping zero coefficients together. The F5 algorithm applies this transformation after permutation to access coefficients in their natural 8x8 block positions.

Formula: zigzag = shuffled - shuffled%64 + deZigZag[shuffled%64]

This can be understood as:

• (shuffled / 64) * 64: The base offset of the 8x8 block
• deZigZag[shuffled % 64]: The de-zigzag position within the block

Parameters:

• shuffledIndex: The permuted coefficient index

Returns:

• The de-zigzagged index for accessing the coefficient array

Example:

shuffled := permutation[i]
zigzag := ApplyDeZigZag(shuffled)
coefficient := coefficients[zigzag]

func ApplyMatrixChange ¶

func ApplyMatrixChange(coefficients []int16, indices []int, position int) int16

ApplyMatrixChange applies the coefficient modification at the calculated position. This is an alias to f5matrix.ApplyMatrixChange for backward compatibility. See f5matrix.ApplyMatrixChange for full documentation.

func BuildHeader ¶

func BuildHeader(k, messageSize int) int32

BuildHeader constructs a 32-bit F5 header from k parameter and message size.

The classic F5 header format is:

• Bits 24-31 (8 bits): k parameter value (matrix encoding parameter)
• Bits 0-22 (23 bits): message file size in bytes

This header format allows messages up to 8,388,607 bytes (2^23 - 1) and k values from 0-255 (though only 1-8 are typically used).

Parameters:

• k: The matrix encoding parameter (typically 1-8)
• messageSize: The message size in bytes (max MaxMessageSize)

Returns:

• A 32-bit header value ready for XOR and embedding

Example:

header := BuildHeader(4, 1000)
// header bits 24-31 = 4 (k parameter)
// header bits 0-22 = 1000 (message size)

func CalculateCapacityForK ¶

func CalculateCapacityForK(usableCoeffCount, k int) int

CalculateCapacityForK computes the embedding capacity in bits for a specific k value.

This helper function calculates how many message bits can be embedded using a specific k parameter, accounting for the header overhead.

Parameters:

• usableCoeffCount: Number of non-zero, non-DC coefficients
• k: The matrix encoding parameter (1-8)

Returns:

• The message capacity in bits (excluding header)

Example:

// With 1000 coefficients and k=4 (n=15):
capacity := CalculateCapacityForK(1000, 4)
// Returns (1000/15)*4 - 32 = 66*4 - 32 = 232 bits

NOTE: This function does not account for shrinkage. For accuracy that matches F5.jar's actual k-selection on real images, prefer CalculateCapacityForKWithShrinkage which uses f5.jar's `_expected` effective pool (P − h(1)) + ⌊0.49·h(1)⌋ before computing capacity.

func CalculateCapacityForKWithShrinkage ¶

func CalculateCapacityForKWithShrinkage(usableCoeffCount, magnitudeOneCount, k int) int

CalculateCapacityForKWithShrinkage is the shrinkage-aware variant of CalculateCapacityForK. It computes the message-byte capacity using the f5.jar effective-capacity `_expected` = (P − h(1)) + ⌊0.49·h(1)⌋, which reserves space for the expected shrinkage cascade.

Parameters mirror CalculateCapacityForK plus magnitudeOneCount, the count of usable coefficients with |value| = 1. CapacityResult.EstimatedShrinkageFactor times CapacityResult.UsableCoefficients gives the same value.

Use this for embed-time k-selection when capacity fidelity to F5.jar's published formula matters more than the simpler/faster non-shrinkage form.

func CalculateEmbeddingRate ¶

func CalculateEmbeddingRate(k int) float64

CalculateEmbeddingRate computes the embedding rate R(k) for a given k parameter.

The embedding rate represents the efficiency of the matrix encoding: R(k) = k / (2^k - 1)

As k increases, the embedding rate decreases but embedding efficiency improves (fewer changes per embedded bit). The optimal k balances capacity needs with statistical detectability.

Embedding rates for common k values:

• k=1: R(1) = 1.000 (1 bit per coefficient, lowest efficiency)
• k=2: R(2) = 0.667 (2 bits per 3 coefficients)
• k=3: R(3) = 0.429 (3 bits per 7 coefficients)
• k=4: R(4) = 0.267 (4 bits per 15 coefficients)
• k=5: R(5) = 0.161 (5 bits per 31 coefficients)
• k=6: R(6) = 0.095 (6 bits per 63 coefficients)
• k=7: R(7) = 0.055 (7 bits per 127 coefficients)
• k=8: R(8) = 0.031 (8 bits per 255 coefficients, highest efficiency)

Parameters:

• k: The matrix encoding parameter (typically 1-8)

Returns:

• The embedding rate as a float64 value
• Returns 0 for invalid k values (k <= 0)

Example:

rate := CalculateEmbeddingRate(4) // Returns 0.267 (4/15)

func CodeWordLength ¶

func CodeWordLength(k int) int

CodeWordLength returns the code word length n for a given k parameter. This is an alias to f5matrix.CodeWordLength for backward compatibility. See f5matrix.CodeWordLength for full documentation.

func ComputeCodeWordHash ¶

func ComputeCodeWordHash(codeWord []int, n int) int

ComputeCodeWordHash computes the hash function for matrix encoding. This is an alias to f5matrix.ComputeCodeWordHash for backward compatibility. See f5matrix.ComputeCodeWordHash for full documentation.

func DetectShrinkage ¶

func DetectShrinkage(coefficient int16) bool

DetectShrinkage determines if modifying a coefficient will cause shrinkage. This is an alias to f5coefficient.IsShrinkageCandidate for backward compatibility. See f5coefficient.IsShrinkageCandidate for full documentation.

func EffectiveCapacityCoefficients ¶

func EffectiveCapacityCoefficients(usableCoeffCount, magnitudeOneCount int) int

EffectiveCapacityCoefficients returns the F5 effective number of coefficients available for matrix encoding (f5.jar's `_expected`), which reserves space for the expected shrinkage cascade.

It reproduces f5.jar's shipped calculation BYTE-EXACTLY (james/JpegEncoder.java:281-282):

_large    = coeffCount - _zero - _one - coeffCount/64;  // = P - h(1)
_expected = _large + (int) (0.49 * _one);               // INTEGER TRUNCATION

where P = usableCoeffCount (non-zero, non-DC) and _one = h(1) = magnitudeOneCount. Re-expressed against P:

_expected = (P − h(1)) + ⌊0.49·h(1)⌋

This is NOT the same as P − round(0.51·h(1)). For even h(1) the two differ by exactly 1 — the algebraic identity (P−h1)+⌊0.49·h1⌋ = P − ⌈0.51·h1⌉ holds, and ⌈0.51·h1⌉ exceeds round(0.51·h1) by 1 whenever h1 is even. A 1-coefficient error in `_expected` flips the selected k at a code-word bucket boundary (selectOptimalKJavaExact's `usable < byteToEmbed+4` test), producing byte-divergent, un-extractable stego. The earlier round(0.51·h1) form matched f5.jar only on the ~half of covers with odd h(1); this exact truncation matches on all of them.

Go's int() conversion truncates toward zero for the non-negative product 0.49·h(1), matching Java's (int) cast. Source: Westfeld 2001 §3, Liu 2020 Eq.(1), and f5.jar james/JpegEncoder.java.

Returns 0 if usableCoeffCount is non-positive or the reserve consumes the entire pool.

func EmbedHeader ¶

func EmbedHeader(coefficients []int16, permutation []int, header int32) (nextIndex int, err error)

EmbedHeader embeds a 32-bit header into coefficients using simple LSB embedding.

Unlike the message payload which uses matrix encoding, the F5 header is embedded using simple LSB modification. This is because the header must be extracted first to determine the k parameter needed for matrix decoding.

The function:

1. Iterates through permuted coefficient indices
2. Skips DC coefficients (index % 64 == 0)
3. Applies de-zigzag transformation
4. Skips zero coefficients
5. Embeds one header bit per usable coefficient
6. Modifies coefficient if current stego bit doesn't match desired bit

Parameters:

• coefficients: The DCT coefficient array to modify (modified in-place)
• permutation: The Fisher-Yates permutation of coefficient indices
• header: The 32-bit XORed header value to embed

Returns:

• nextIndex: The permutation index to resume from for message embedding
• err: An error if insufficient coefficients for header embedding

Example:

nextIndex, err := EmbedHeader(coefficients, permutation, xoredHeader)
if err != nil {
    return err
}
// Continue embedding message starting at permutation[nextIndex]

func ExtractStegoBits ¶

func ExtractStegoBits(coefficients []int16) []int

ExtractStegoBits extracts the steganographic bit values from a slice of coefficients. This is an alias to f5coefficient.ExtractStegoBits for backward compatibility. See f5coefficient.ExtractStegoBits for full documentation.

func GeneratePermutation ¶

func GeneratePermutation(random f5prng.RandomSource, size int) ([]int, error)

GeneratePermutation generates a Fisher-Yates permutation of indices.

The permutation is used for "permutative straddling" in F5, which shuffles coefficient indices before embedding to distribute changes uniformly across the image. This prevents localized statistical analysis attacks.

The function uses the fisheryates package's GenerateInto method for zero allocation when reusing buffers. The permutation is deterministic based on the RandomSource state, ensuring the same password produces the same permutation for both embedding and extraction.

PRNG Consumption: This function consumes PRNG state proportional to the size parameter. After calling GeneratePermutation, the PRNG state will have advanced exactly as the Java F5 implementation expects.

Parameters:

• random: A seeded f5prng.RandomSource (typically from InitializePRNG)
• size: The number of elements in the permutation (coefficient count)

Returns:

• A slice containing a permutation of [0, 1, ..., size-1]
• An error if size is negative or exceeds fisheryates.MaxPermutationSize

Example:

prng := InitializePRNG("password")
defer prng.Clear()
perm, err := GeneratePermutation(prng, len(coefficients))
if err != nil {
    return err
}
// perm now contains shuffled indices for coefficient access

func GetStegoBit ¶

func GetStegoBit(coefficient int16) int

GetStegoBit extracts the steganographic bit value from a DCT coefficient. This is an alias to f5coefficient.GetStegoBit for backward compatibility. See f5coefficient.GetStegoBit for full documentation.

func HandleShrinkage ¶

func HandleShrinkage(codeWord []int, position int, coefficient int16) (shrunk bool, newCoeff int16)

HandleShrinkage applies a coefficient modification and detects shrinkage.

This function combines the modification operation with shrinkage detection, providing a single entry point for the shrinkage handling workflow in the F5 embedding process.

The function:

1. Applies ModifyCoefficient to decrement the absolute value
2. Detects if the original coefficient was 1 or -1 (shrinkage case)
3. Returns both the shrinkage status and the new coefficient value

The codeWord and position parameters are included for interface consistency with the matrix encoding workflow, where shrinkage handling may need context about which code word and position triggered the shrinkage. In the current implementation, these parameters are reserved for future use.

Parameters:

• codeWord: The current code word being processed (reserved for future use)
• position: The position within the code word (reserved for future use)
• coefficient: The coefficient to modify

Returns:

• shrunk: true if the modification caused the coefficient to become 0
• newCoeff: the coefficient value after modification

Example:

shrunk, newCoeff := HandleShrinkage(codeWord, 1, int16(5))
// shrunk = false, newCoeff = 4

shrunk, newCoeff = HandleShrinkage(codeWord, 1, int16(1))
// shrunk = true, newCoeff = 0

shrunk, newCoeff = HandleShrinkage(codeWord, 1, int16(-1))
// shrunk = true, newCoeff = 0

func IsUsableCoefficient ¶

func IsUsableCoefficient(index int, coefficient int16) bool

IsUsableCoefficient determines if a coefficient can carry steganographic data. This is an alias to f5coefficient.IsUsableCoefficient for backward compatibility. See f5coefficient.IsUsableCoefficient for full documentation.

func MatrixEncode ¶

func MatrixEncode(codeWord []int, messageBits, k int) (changePosition int, err error)

MatrixEncode performs (1, n, k) matrix encoding to determine which coefficient to modify in order to embed k message bits. This is an alias to f5matrix.MatrixEncode for backward compatibility. See f5matrix.MatrixEncode for full documentation.

func ModifyCoefficient ¶

func ModifyCoefficient(coefficient int16) int16

ModifyCoefficient decrements the absolute value of a coefficient. This is an alias to f5coefficient.ModifyCoefficient for backward compatibility. See f5coefficient.ModifyCoefficient for full documentation.

func SelectOptimalK ¶

func SelectOptimalK(usableCoeffCount, messageBits int) (k int, err error)

SelectOptimalK determines the best k parameter for embedding a message.

F5 uses (1, n, k) matrix encoding where n = 2^k - 1. Higher k values provide better embedding efficiency (fewer coefficient changes) but require more coefficients per embedded bit chunk. This function selects the largest k that can accommodate the given message plus the 32-bit header.

The selection algorithm:

1. Try k from 8 down to 1 (highest efficiency first)
2. For each k, calculate capacity: (usableCoeffs / n) * k
3. Select the first k where capacity >= messageBits + HeaderSize
4. Return error if no k can accommodate the message

The capacity formula accounts for:

• Code word length n = 2^k - 1
• Each code word embeds k bits
• The 32-bit header overhead (HeaderSize = 32)

Parameters:

• usableCoeffCount: Number of non-zero, non-DC coefficients available
• messageBits: Number of bits in the message to embed

Returns:

• k: The optimal encoding parameter (1-8)
• err: ErrInsufficientCapacity if message cannot fit

Example:

// With 10000 usable coefficients and 1000 message bits:
k, err := SelectOptimalK(10000, 1000)
// Returns k=8 (highest efficiency that fits)

// With limited coefficients, a lower k may be selected:
k, err = SelectOptimalK(500, 400)
// Returns k=1 (only option with enough capacity)

func SelectOptimalKWithShrinkage ¶

func SelectOptimalKWithShrinkage(usableCoeffCount, magnitudeOneCount, messageBits int) (int, error)

SelectOptimalKWithShrinkage is the shrinkage-aware k-selector. It computes the f5.jar effective capacity (P − h(1)) + ⌊0.49·h(1)⌋ and then walks the same iterative k-selection loop f5.jar uses (JpegEncoder.java:337- 349, see selectOptimalKJavaExact), so it returns the SAME k value f5.jar would pick for the same (cover, message) inputs.

Prior to 2026-05-23 this delegated to SelectOptimalK (a "largest k that fits" walk using the standard floor(P/n)*k capacity formula). That gave the WRONG k at certain bucket-boundary covers — empirically a 64×64 cover with 1081 usable coefficients and 1-byte message: f5.jar picks k=6 (its quirky formula returns 0 bits at i=7, forcing break and k = i-1); the old SelectOptimalK picked k=7 because the standard formula gives 56 non-zero bits. The mismatched k produced byte-divergent stego on roughly half of (cover, Q) combinations — see project_f5jar_parity.md and the reproducer at /tmp/mcu_parity_test/.

Use this in place of SelectOptimalK whenever the caller has access to h(1) (the magnitudeOneCount). The non-shrinkage SelectOptimalK is retained for API compatibility but does NOT match f5.jar's k choice.

func SetTranslator ¶

func SetTranslator(t TranslatorProvider)

SetTranslator sets the global translator for i18n error messages. Pass nil to disable translation and use English fallback messages.

This function is safe for concurrent use.

func Translate ¶

func Translate(key string) string

Translate returns a translated message for the given key. If no translator is set or the key is not found, returns the default English message. This is the public translation helper function for i18n support.

func ValidateCoefficients ¶

func ValidateCoefficients(coefficients []int16) error

ValidateCoefficients validates that the coefficient slice is valid for embedding. It checks that:

• The slice is not empty
• All coefficient values are within the valid JPEG DCT range [-2048, 2047]

Returns nil if validation passes, or a ValidationError if it fails.

func ValidateInputs ¶

func ValidateInputs(coefficients []int16, password string, message []byte, capacity int) error

ValidateInputs performs all input validations for an embedding operation. This is a convenience function that combines ValidateCoefficients, ValidatePassword, and ValidateMessage.

Returns the first validation error encountered, or nil if all validations pass.

func ValidateMessage ¶

func ValidateMessage(message []byte, capacity int) error

ValidateMessage validates that the message can be embedded within the given capacity. It checks that:

• The message size does not exceed MaxMessageSize (2^23 - 1 bytes)
• The message fits within the specified capacity in bytes

The capacity parameter should be the maximum bytes that can be embedded, typically obtained from CapacityResult.CapacityByK for the selected k value.

Returns nil if validation passes, or a ValidationError if it fails.

func ValidatePassword ¶

func ValidatePassword(password string) error

ValidatePassword validates that the password is valid for embedding. It checks that the password is not an empty string.

Returns nil if validation passes, or a ValidationError if it fails.

func XORHeaderWithPRNG ¶

func XORHeaderWithPRNG(header int32, random RandomSource) int32

XORHeaderWithPRNG XORs a header with 4 consecutive PRNG bytes.

The F5 algorithm XORs the header with PRNG bytes to add another layer of password-dependent obfuscation. This must be done in the exact same order as the Java implementation for byte-identical compatibility.

PRNG consumption order (Java-compatible):

• Byte 0: XORed with header bits 0-7
• Byte 1: XORed with header bits 8-15
• Byte 2: XORed with header bits 16-23
• Byte 3: XORed with header bits 24-31

Important: Uses signed byte arithmetic to match Java's behavior. Go's bytes are unsigned [0, 255], but Java's bytes are signed [-128, 127]. The int(int8(byte)) conversion ensures sign extension matches Java.

Parameters:

• header: The 32-bit header value from BuildHeader
• random: A seeded RandomSource (PRNG state after permutation generation)

Returns:

• The XORed header value ready for embedding

Example:

prng := InitializePRNG(password)
_, _ = GeneratePermutation(prng, coeffCount) // consumes PRNG for permutation
header := BuildHeader(k, len(message))
xoredHeader := XORHeaderWithPRNG(header, prng) // consumes 4 more PRNG bytes