Provided by: bit-babbler_0.8build1_amd64 
NAME
bbcheck - run automated tests on BitBabbler hardware RNG devices
SYNOPSIS
bbcheck [options]
DESCRIPTION
The bbcheck utility is is tool for quickly and simply analysing the output of a BitBabbler RNG at various
bitrates. It can run tests on multiple devices in parallel, and highlight the best and worst results
from a series of tests on each device.
OPTIONS
The following options are available:
-s, --scan
Scan the system for available BitBabbler devices.
-i, --device-id=id
Select a BitBabbler device to analyse by its unique ID. If no devices are explicitly specified
then the default is to use all of them which are present when testing begins. This option may be
passed multiple times to test multiple devices. The id may be the device serial number, or its
logical address in the form:
[busnum:]devnum
or on systems where knowing the USB topology is supported, its physical address in the form
busnum-port[.port ...]
For a logical address the busnum part is optional, but if devnum is not unique across all buses,
then exactly which device will be selected if it is not fully specified becomes a matter of
chance. All of the available IDs which can be used to refer to a device will be reported by the
--scan option. Bus, device, and port numbers are expected to be decimal integers.
Since bbcheck only operates on available devices and does not wait for a device to be hotplugged,
it is an error to specify an ID which does not refer to a device currently available in the
system.
-r, --bitrate=min[:max]
Select the bitrate, or range of bitrates, to analyse (in bits per second). The available bitrates
are determined by an integer clock divider, so not every rate is exactly achievable. An
unsupported rate will be rounded up to the next higher rate. For convenience the rate may be
followed by an SI multiplier (eg. 2.5M for 2500000). If a colon separated range is specified,
then all possible bitrates between min and max will be tested.
-b, --bytes=n
The number of bytes to analyse for each test. A suffix of 'k', 'M', or 'G' will multiply n by the
respective power of two.
-B, --block-size=bytes
The block size used for folding. This size must be a multiple of 2^n, where n is the level of
folding used (ie. it must be able to fold the desired number of times without any remainder). A
suffix of 'k', 'M', or 'G' will scale bytes by the respective power of two. Default is 64kB. A
larger block size will mix samples taken over a longer timescale. At high bitrates this will mean
more of the lower frequency noise can be factored into each sample where otherwise the higher
frequency noise would dominate. The optimum block size (beyond which any change to the result is
negligible) for any given bitrate is still a matter that is ripe for further study. See the
--fold option below for a more detailed description of folding.
-A, --all-results
Show all the test results, not just the final summary.
--no-colour
Don't colour the final results. By default the four best results will be highlighted bright-
green, dull-green, yellow, and orange, while the worst result will be highlighted in red. This
option suppresses the output of terminal escape codes which are responsible for that.
-v, --verbose
Make more noise about what is going on internally. If used (once) with the --scan option this
will show more information about each device, but otherwise it's mostly only information useful
for debugging. It may be passed multiple times to get swamped with even more information.
-?, --help
Show a shorter version of all of this, which may fit on a single page.
--version
Report the bbcheck release version.
Per device options
The following options may be used multiple times to individually configure each device when more than one
BitBabbler is available. If passed before any --device-id option, then they set new default values which
will apply to every device. If passed after one of those options they will only be applied to the
immediately preceding device.
--latency=ms
Override the calculated value for the USB latency timer. This controls the maximum amount of time
that the device will wait if there is any data in its internal buffer (but less than a full
packet), before sending it to the host. If this timer expires before a packet can be filled, then
a short packet will be sent to the host. The default value is chosen to ensure that we do not
send more short packets than necessary for the selected bitrate, since that will increase the
number of packets sent and the amount of CPU time which must be spent processing them, to transfer
the same amount of data.
Unless you are experimenting with changes to the low level code, there is probably no reason to
ever use this option to override the latency manually.
-f, --fold=n
Set the number of times to fold the BitBabbler output before analysing it. Each fold will take
the first half of the block that was read and XOR it with the bits in the second half. This will
halve the throughput, but concentrate the available entropy more densely into the bits that
remain.
There are two main things this is expected to do based on the BitBabbler design. It will better
mix the low-frequency noise that is captured with that of the higher frequencies, allowing it to
sample at higher bitrates without narrowing the noise bandwidth available to influence adjacent
bits. It will help to break up any transient local correlations that might occur in the physical
processes from which ambient environmental noise is collected.
Folding should never reduce the real entropy of each sample, but when all is working exactly as it
should, it may not do anything to increase it either. Mathematically, an XOR summation is
expected to exponentially smooth any bias in a stream of independent bits, with the result having
at least as much entropy as the least predictable of either of the two inputs (in the same way
that a one time pad is no less secure despite the plaintext having much less entropy than the pad
does).
--enable-mask=mask
Select a subset of the generators on BitBabbler devices with multiple entropy sources. The
argument is a bitmask packed from the LSB, with each bit position controlling an individual
source, enabling it when set to 1. As a special case for bbcheck, if a mask of 0 is used, then
the tests will be performed on each source unit individually. A mask of 16 (0x10) will first test
each source individually, and then all of of them enabled together as well.
--limit-max-xfer
Limit the maximum transfer chunk size to 16kB. On Linux, prior to kernel 3.3, individual bulk
transfer requests were somewhat arbitrarily limited to 16kB. With kernels later than that, larger
transfers were supported, and we will make use of those to optimise transfer speeds for large
requests at high bitrates when a new enough kernel and libusb with support for this are both
available.
Unfortunately, the USB chipsets on some motherboards are still buggy when these larger transfers
are used, and there is no easy way for us to automatically detect those, since the symptoms they
exhibit do vary and aren't always directly visible to our code. Ideally any problems like that
should be reported to the kernel maintainers, where they can be fixed, or worked around for device
specific quirks, but this option allows you to explicitly request that the transfer size be
limited on machines where you are experiencing problems with that.
If in doubt, it is safe to use this option on any system, the impact on transfer speed is
relatively minimal unless you are trying to obtain huge numbers of bits as quickly as possible.
But it's not the default, since at present only a very small number of systems are still known to
be affected, and that number should continue to decrease over time.
SEE ALSO
seedd(1), bbctl(1).
AUTHOR
bbcheck was written by Ron <ron@debian.org>. You can send bug reports, feature requests, praise and
complaints to support@bitbabbler.org.
May 29, 2017 BBCHECK(1)