Documentation
¶
Overview ¶
Package stats holds the cipher-agnostic statistical primitives the toolkit uses to triage a captured payload: is it plaintext, a weak classical cipher, an obfuscation, or strong encryption? Plus the repeating-key-XOR key-length estimators (Friedman/Hamming) and a crib-dragging helper for many-time-pad / keystream-reuse analysis.
Index ¶
- func Autocorrelation(data []byte, maxLag int) []float64
- func ByteFrequency(data []byte) [256]int
- func ChiSquareUniform(data []byte) float64
- func HammingDistance(a, b []byte) int
- func IndexOfCoincidence(data []byte) float64
- func ShannonEntropy(data []byte) float64
- type DragHit
- type KeyLenScore
- type NGram
- type PeriodCandidate
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Autocorrelation ¶ added in v0.5.8
Autocorrelation returns, for each lag 1..maxLag, the coincidence rate: the fraction of positions i where data[i] == data[i+lag]. For a uniform random byte stream this sits near 1/256 ≈ 0.0039 at every lag; a repeating-key cipher, a periodic scrambler, or a reused keystream produces sharp peaks at multiples of its period. This is the byte-level analogue of CrypTool's autocorrelation view, and the prerequisite measurement before choosing a repeating-XOR key length or a rolling-descramble frame size.
func ByteFrequency ¶
ByteFrequency returns the count of each byte value.
func ChiSquareUniform ¶
ChiSquareUniform returns the chi-square statistic of the byte distribution against a uniform 256-value model. Near (256-1)=255 for uniform/random data; large for structured data.
func HammingDistance ¶
HammingDistance returns the bit-difference count between equal-length byte slices. It panics if the lengths differ — callers slice first.
func IndexOfCoincidence ¶
IndexOfCoincidence returns the probability that two bytes drawn at random (without replacement) are equal. English text over the 26-letter alphabet sits near 0.066; uniform random over 256 values near 1/256.
func ShannonEntropy ¶
ShannonEntropy returns the per-byte Shannon entropy in bits (0..8). High values (~8) indicate compression or strong encryption; low values indicate structure (plaintext, weak ciphers, obfuscation).
Types ¶
type DragHit ¶
DragHit is one crib-drag position and the plaintext fragment it reveals in the other message when two ciphertexts share a keystream (c1 ^ c2 ^ crib).
type KeyLenScore ¶
KeyLenScore pairs a candidate repeating-XOR key length with its normalized average Hamming distance (bits/byte); the true length tends to minimize it.
func GuessXORKeyLength ¶
func GuessXORKeyLength(ct []byte, maxLen int) []KeyLenScore
GuessXORKeyLength ranks candidate key lengths for a repeating-key XOR ciphertext by averaging the normalized Hamming distance between adjacent key-length blocks (the Friedman/Kasiski idea). Lower score = more likely. Results are sorted best-first.
type PeriodCandidate ¶ added in v0.5.8
type PeriodCandidate struct {
Lag int
Coincidence float64
// ZScore is how many baseline standard deviations the coincidence sits
// above the mean coincidence across all lags — a scale-free strength.
ZScore float64
}
PeriodCandidate is one lag whose coincidence rate stands out, the likely period (or a multiple of it) of a repeating structure.
func DetectPeriod ¶ added in v0.5.8
func DetectPeriod(data []byte, maxLag, topN int) []PeriodCandidate
DetectPeriod ranks the lags of Autocorrelation by how far their coincidence rate exceeds the across-lag baseline, returning the strongest candidates first. An empty result means no lag stood out (no detectable period within maxLag). topN <= 0 returns all peaks above the threshold.
Source Files