randtest is an application for statistically testing pseudo-random number generators à la
dieharder,
TestU01, and the NIST sts.
Warning: This is alpha software still in the pre-0.1 release stage.
This application is built on top of the librandtest crate.
The randtest application should still be usable by those developing a custom generator, but
who do not know any Rust.
You can ask questions about this project or talk to me directly in the #randtest IRC channel
on the irc.mozilla.org network.
Installation
Install randtest using the cargo package manager for Rust.
It is worth considering using RUSTFLAGS="-C target-cpu=native" cargo install randtest,
because rustc will only enable certain performant native cpu extensions if explicitly told to
do so. This especially holds true if you do not use the blas feature, since this resorts to
native Rust substitutes for blas routines and the CPU extensions availability really helps.
Usage
The expected usage of randtest is primarily through the terminal application. We'll example a
few common use cases below, but use randtest -h to see a help message after installation.
Builtin Generators
Run all the tests against all the generators built into randtest:
Run only the 'frequency' test (a short name for the Monobit Frequency Deviation test) against
only the Isaac 32 and 64 bit generators using the -t and -g selectors:
Custom Generators
You can write custom random number generators in any programming language and pass the output
to randtest for testing as long as you can produce a sufficiently large file to read enough
bytes from (not ideal) or can write to the stdout standard stream in base64 encoding
(preferred).
Files
Run all the tests against the system non-blocking generator file /dev/urandom (on some Unix
systems) using the -f or --file selectors:
Try that on the blocking system generator file /dev/random on systems that support it and
watch it immediately stall out.
Your best bet to complete a run with the blocking system generator is to run only one of the
tests and pass very small values to the -p/--psamples (e.g. 1 or 2) and -m/--multiplier
(e.g. 0.001 or 0.005) options which modulate the sample sizes of the two-level and one-level
internal hypothesis testing procedures respectively. Then wave your mouse about wildly to
generate some hardware entropy!!
Note that this reads the raw bytes of the file and does not expect any form of other encoding.
Stdin
Below, we use the --stdin flag to take in base64 encoded data from the system generator over
the standard streams. We read from the same non-blocking system generator source file as in the
file example above and use the common base64 program from GNU
coreutils for encoding.
| |
On macOS and other systems you may not have coreutils base64 installed, you can also use
openssl for encoding or any other program with a base64 encoding function:
| |
In both encoding examples, the flags -w 0 and -A are used to prevent newlines being placed
into our encoded data stream. We require one, long data stream without any whitespace.
However, suppose you write an executable program gen.py in Python that writes random bits to
stdout in base64 encoding directly. Then you can provide it as a custom generator directly with
no intermediate encoding program:
|