Documentation
¶
Overview ¶
Package randomness implements a battery of statistical randomness tests drawn from NIST SP 800-22 (the "STS" suite), specialised for the question an RF analyst actually asks of a captured payload or a recovered keystream: is this stream indistinguishable from random (strong keyed encryption — no weak structure to exploit), or does it carry exploitable structure (a keyless scrambler, a short LFSR, a biased generator)?
Each test returns a p-value in [0,1]; a stream "passes" a test at significance level alpha when p >= alpha. A truly random stream passes all tests; a structured one fails one or more (most diagnostically the spectral and linear-complexity tests for RF scramblers). The toolkit's existing entropy / index-of-coincidence triage (engine/stats) answers the same question coarsely; this battery answers it rigorously.
Bit sequences are represented as a []byte holding one 0/1 value per element (the same convention as engine/lfsr), so callers convert packed capture bytes with lfsr.BitsFromBytes. The incomplete-gamma p-values use gonum's mathext.GammaIncRegComp and the spectral test uses gonum's real FFT, so the suite stays pure-Go with no new dependencies.
Index ¶
- Constants
- type Report
- type TestResult
- func ApproximateEntropy(bits []byte, m int) TestResult
- func BinaryMatrixRank(bits []byte) TestResult
- func BlockFrequency(bits []byte, m int) TestResult
- func CumulativeSums(bits []byte) TestResult
- func LinearComplexity(bits []byte, m int) TestResult
- func LongestRun(bits []byte) TestResult
- func Monobit(bits []byte) TestResult
- func Runs(bits []byte) TestResult
- func Serial(bits []byte, m int) TestResult
- func Spectral(bits []byte) TestResult
Constants ¶
const DefaultAlpha = 0.01
DefaultAlpha is the conventional NIST significance level.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Report ¶
type Report struct {
Bits int `json:"bits"`
Alpha float64 `json:"alpha"`
Tests []TestResult `json:"tests"`
Passed int `json:"passed"`
Failed int `json:"failed"`
Skipped int `json:"skipped"`
}
Report is the full battery outcome over one bit stream.
func Battery ¶
Battery runs the full suite over the bit stream, choosing block sizes from the stream length. alpha <= 0 selects DefaultAlpha.
func (Report) LooksRandom ¶
LooksRandom reports whether every applicable test passed — i.e. the stream is statistically indistinguishable from random at the report's alpha.
func (Report) WeakestTests ¶
func (r Report) WeakestTests() []TestResult
WeakestTests returns the applicable tests sorted by ascending p-value (the strongest evidence of non-randomness first).
type TestResult ¶
type TestResult struct {
Name string `json:"name"`
// PValue is the test statistic's p-value in [0,1]; only meaningful when
// Applicable is true.
PValue float64 `json:"p_value"`
// Passed reports p >= alpha. Only meaningful when Applicable is true.
Passed bool `json:"passed"`
// Applicable is false when the stream is too short for the test's
// preconditions; Note explains what is missing.
Applicable bool `json:"applicable"`
Note string `json:"note,omitempty"`
}
TestResult is the outcome of one randomness test.
func ApproximateEntropy ¶
func ApproximateEntropy(bits []byte, m int) TestResult
ApproximateEntropy: compares the frequency of overlapping m- and (m+1)-bit patterns; structure lowers the apparent entropy.
func BinaryMatrixRank ¶
func BinaryMatrixRank(bits []byte) TestResult
BinaryMatrixRank: do the ranks of disjoint 32×32 sub-matrices follow the expected distribution? Detects linear dependence among bit positions.
func BlockFrequency ¶
func BlockFrequency(bits []byte, m int) TestResult
BlockFrequency: is the proportion of ones uniform across M-bit blocks?
func CumulativeSums ¶
func CumulativeSums(bits []byte) TestResult
CumulativeSums (forward): treats the ±1 sequence as a random walk and tests whether the maximum excursion from zero is too large.
func LinearComplexity ¶
func LinearComplexity(bits []byte, m int) TestResult
LinearComplexity: blocks the stream and tests the distribution of each block's shortest-LFSR length (via Berlekamp–Massey). Low linear complexity is the defining weakness of an LFSR-based scrambler, so this is the most RF-diagnostic test in the suite.
func LongestRun ¶
func LongestRun(bits []byte) TestResult
LongestRun: is the longest run of ones within a block consistent with randomness? Uses the NIST block size / category table selected by length.
func Monobit ¶
func Monobit(bits []byte) TestResult
Monobit (frequency) test: are roughly half the bits one? The most basic test; everything else assumes this passes.
func Runs ¶
func Runs(bits []byte) TestResult
Runs: is the number of uninterrupted runs of identical bits what a random stream would produce? Detects oscillation that is too fast or too slow.
func Serial ¶
func Serial(bits []byte, m int) TestResult
Serial: are all overlapping m-bit patterns equally likely? Returns a single result that passes only when both NIST sub-p-values pass.
func Spectral ¶
func Spectral(bits []byte) TestResult
Spectral (DFT): does the discrete Fourier transform of the ±1 sequence show periodic features (spikes) inconsistent with randomness? This is the sharpest test for periodic RF scramblers and rolling codes.
Source Files