practrand-RNG_test - Man Page

manual page for practrand-RNG_test using PractRand version 0.95

Description

practrand-RNG_test using PractRand version 0.95 syntax: practrand-RNG_test RNG_name [options] or: practrand-RNG_test  (use no command line options to see brief overview) or: practrand-RNG_test --help  (to see this message) or: practrand-RNG_test --version  (to see version number) A command line tool for testing RNGs with the PractRand library. RNG names:

To use an external RNG, use stdin as an RNG name and pipe in the random numbers.  stdin8, stdin16, stdin32, and stdin64 also work, each interpretting the input in slightly different ways.  Use stdin if you're uncertain how many bits the RNG produces at a time, or if it's not one of those options. The lowest quality recommended RNGs are sfc16 and mt19937. The entropy pooling RNGs available are arbee and sha2_basd_pool. Small recommended RNGs include sfc16, sfc32, sfc64, jsf32, jsf64, .

threshold options

At most one threshold option should be specified. The default threshold setting is '-e 0.1', alternatives are '-p 0.001' or '-a'

-a

no threshold - display all test results.

-e EXPECTED

sets intelligent p-value thesholds to display an expected number of test results equal to EXPECTED.  If EXPECTED is zero or less then intelligent p-value thresholds will be disabled EXPECTED is a float with default value 0.1

-p THRESHOLD

sets simple p-value thresholds to display any test results within THRESHOLD of an extrema.  If THRESHOLD is zero or less then simple p-value thresholds will be disabled THRESHOLD is a float with recommended value 0.001

test set options

The default test set options are '-tf 1' and '-te 0'

-tf FOLDING

FOLDING may be 0, 1, or 2.  0 means that the base tests are run on only the raw test data.  1 means that the base tests are run on the raw test data and also on a simple transform that emphasizes the lowest bits.  2 means that the base tests are run on a wider variety of transforms of the test data.

-te EXPANDED

EXPANDED may be 0 or 1.  0 means that the base tests used are the normal ones for PractRand, optimized for sensitivity per time.  1 means that the expanded test set is used, optimized for sensitivity per bit. ... and now additional value(s) are supported.  Setting this to 10 will use an systematically expanding Birthday Spacings Test in place of a normal test set.  This test is separate because it uses too much memory to run concurrently with other tests

test target options

At most one test target option should be specified. The default test target option is '-ttnormal'

-ttnormal

Test target: normal - the testing is done on the RNGs output.

-ttseed64

Test target: RNG seeding from 64 bit integers.  First, the RNG is seeded with a randomly chosen 64 bit integer.  Then 8 bytes of output are taken from the RNG and given to the tests.  Then another seed is chosen at a low hamming distance from the prior seed and another 8 bytes of RNG output are given to the tests. This is repeated indefinitely, with care taken to minimize the amount of duplicate seeds used.

-ttep

Test target: Entropy pooling.  This should only be done on RNGs that support entropy pooling.  It is similar to -ttseed64, but the entropy accumulation methods are used instead of simple seeding, and the amount of entropy used is much larger.

-walk_sequence

Some test-target modes will search seeds sequentially, each subsequent seed 1 higher than the previous.

-walk_greycode

Some test-target modes will search seeds in a simple greycoded sequence, each subsequent seed at Hamming distance 1 from the prior in a strict order.

-walk_random

Some test-target modes will search seeds in a random walk, each subsequent seed chosen at random from unused values at Hamming distance 1 from the prior value.

-walk_random_l

Some test-target modes will search seeds in a random walk, each subsequent seed chosen at random from unused values at Hamming distance 1 from the prior value, but lower bits will be changed much more often than higher bits.

-walk_random_h

Some test-target modes will search seeds in a random walk, each subsequent seed chosen at random from unused values at Hamming distance 1 from the prior value, but higher bits will be changed much more often than lower bits.

test length options

-tlmin LENGTH

sets the minimum test length to LENGTH.  The tests will run on that much data before it starts printing regular results.  A large minimum will prevent it from displaying results on any test lengths other than the maximum length (set by tlmax) and lengths that were explicitly requested (by tlshow). See notes on lengths for details on how to express the length you want. The default minimum is 1.5 seconds (-tlmin 1.5s).

-tlmax LENGTH

sets the maximum test length to LENGTH.  The tests will stop after that much data.  See notes on lengths for details on how to express the length you want. The default maximum is 32 terabytes (-tlmin 32TB).

-tlshow LENGTH sets an additional point at which to display interim results.

You can set multiple such points if desired. These are in addition to the normal interim results points, which are at every amount of data that is a power of 2 after the minimum and before the maximum. See the notes on lengths for details on how to express the lengths you want.

-tlfail

Halts testing after interim results are displayed if those results include any failures. (default)

-tlmaxonly

The opposite of -tlfail

other options

-multithreaded

enables multithreaded testing.  Typically up to 5 cores can be used at once.

-singlethreaded disables multithreaded testing.

(default)

-seed SEED

specifies a 64 bit integer to seed the tested RNG with.  If no seed is specified then a seed will be chosen randomly. The value should be expressed in hexadecimal.  An '0x' prefix on the seed is acceptable but not necessary.

-list_recommended_rngs

List the names of all recommended PRNGs.

-list_reference_rngs

List the names of all PRNGs used Tests_results.txt. These are (mostly) bad PRNGs used as a reference set for comparing different PRNG test suites.

notes on lengths

Each of the test length options requires a field named LENGTH.

These fields

can accept either an amount of time or an amount of data.

In either case,

several types of units are supported. A time should be expressed as a number postfixed with either s, m, h, or d, to express a number of seconds, minutes, hours, or days. example: -tlmin 1.4s (sets the minimum test length to 1.4 seconds) An amount of data can be expressed as a number with no postfix, in which case the number will be treated as the log-based-2 of the amount of bytes to test (in normal target mode) or the log-baed-2 of the number of seeds or strings to test in alternate test target modes. example: -tlmin 23 (sets the minimum test length to 8 million bytes or 8

million seeds, depending upon test target mode)

Alternatively, an amount of data can be expressed as a number followed by KB, MB, GB, TB, or PB for kilobytes, megabytes, gigabytes, or petabytes. example: -tlmin 14KB (sets the minimum test length to 14 kilobytes If the B is omitted on KB, MB, GB, TB, or PB then it treat the metric prefixes as refering to numbers of bytes in normal test target mode, or numbers of seeds in seeding test target mode, or numbers of strings in entropy pooling test target mode. example: -tlmin 40M (sets the minimum test length to ~40 million bytes or ~40

million seeds, depending upon test target mode)

A minor detail: I use the de facto standard (in which K means 1024 when dealing with quantities of binary information) not the official standard (in which K means 1000 no matter what is being dealt with unless an 'i' follows the 'K').

practrand-RNG_test version 0.95 A command line tool for testing RNGs with the PractRand library.

Examples

practrand-RNG_test stdin </dev/urandom
 Test quality of random numbers produced Linux's kernel urandom RNG

practrand-RNG_test jsf64 -tlmax 4G
 Test built-in Bob Jenkins Small Fast (Noncryptographic) PRNG, using maximum set length of 4GiB. See /usr/share/doc/practrand/RNG_engines.txt for the info about the built-in RNGs.

practrand-RNG_test jsf64 -tlmax 4G -multithreaded
 Test built-in jsf64 PRNG, running the tests multithreaded.

practrand-RNG_output hc256 inf | practrand-RNG_test stdin32 -tlmax 4G practrand-RNG_test hc256 -tlmax 4G
 Test first 4 GiB of HC-256 RNG. Compare performance of built-in RNG versus using pipe to pass the data from the external process.

bash -c "( ime practrand-RNG_output hc256 $(bc <<< 4*2^30)) | ( ime practrand-RNG_test stdin32 -tlmax 4G -multithreaded)"
 Collecting performance data to test first 4GiB bytes of HC-256 RNG using the multithreaded test.

See Also

The full documentation for practrand-RNG_test is maintained as a Texinfo manual.  If the info and practrand-RNG_test programs are properly installed at your site, the command

info practrand-RNG_test

should give you access to the complete manual.

Info

April 2021 practrand-RNG_test using PractRand version 0.95