Page last updated: Sun Apr 23 23:07:24 CDT 2017

Table of contents

Software & Documentation Kit contents

Folder ‘linux’ – contains all necessary files and source code for building the ‘swrandom’ kernel module used with Linux distributions.

Folder ‘linux-and-OSX’ – contains all necessary files and source code for building ‘swrng’, ‘swrng-cl’, ‘swperftest’, ‘swperf-cl-test’, ‘sample’, ‘sample-cl’, ‘swdiag’ and ‘swdiag-cl’ utilities used with Linux and macOS distributions.

Folder ‘windows’ – contains all necessary files and source code for building WIN32 versions of ‘SwiftRNG.dll’ component, ‘swrng.exe’ and ‘swdiag.exe’ utilities for Windows using Visual C++ 2010 Express. This version of the SwiftRNG software API is deprecated. New application development should use windows-x64 version of the software API.

Folder ‘windows-x64’ – contains all necessary files and source code for building x64 versions of ‘SwiftRNG.dll’ component, ‘swrng.exe’, ‘swdiag.exe’, ‘sample.exe’, ‘dll-sample.exe’ and ‘dll-test.exe’ utilities for Windows 8.1 & 10 using Visual Studio C++ 2015 (Community Edition) or newer.

SwiftRNG Software API cluster capability with Linux and macOS

Beginning with SwiftRNG Software Kit version 3.3, the SwiftRNG API contains device cluster scalability and fail-over capabilities. With this, it is possible to use multiple SwiftRNG devices to additively increase the random number generation speed. By doing so, the reliability of the cluster is increased. This new API feature seamlessly integrates multiple devices and uses them concurrently as a single stream of random data. The API will monitor the health of the cluster and will resize the cluster on-the-fly, allowing device swapping in real-time. This makes it possible to remove and add SwiftRNG devices in the middle of random number generation.

Building and loading the ‘swrandom’ kernel module with Linux

(Refer to section “Configuring ‘swrandom’ module for using with ‘rngd’ daemon on Ubuntu” for specific details) The ‘swrandom’ ‘make’ project is available in the following SDK location:

linux\swrandom

We strongly recommend performing the following steps before building the ‘swrandom’ module on Ubuntu:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get reboot
sudo apt-get install make
sudo apt-get install gcc

We strongly recommend performing the following steps before building the ‘swrandom’ module on CentOS and Red Hat with system administration permissions:

yum install make
yum install gcc
yum install kernel-devel
reboot

The ‘swrandom’ module can be built with ‘make’. You will need to rebuild the module each time a new version of the kernel is installed (this step and the next one can be automated so that the module can be built and loaded at system boot time so you will not need to perform it manually - ask system administrator to automate these steps).

Once the module is successfully built with ‘make’, it should be loaded into the kernel by running the ins-swrandom.sh script with system administration permissions:

./ins-swrandom.sh

To load the module with a specific SwiftRNG power profile, use the following command (this example loads the module using SwiftRNG power profile 5, valid values are 0 through 9):

./ins-swrandom.sh powerProfile=5

After the ‘swrandom’ module is successfully loaded by the kernel, the random bytes will be available for download from the following device:

/dev/swrandom

The module allows the entropy available in /dev/swrandom to be shared concurrently by multiple applications.

You can download random bytes to a file using the following command:

sudo dd if=/dev/swrandom of=download.bin bs=100 count=120000

The ‘swrandom’ module will automatically detect the event when a SwiftRNG device is plugged in or unplugged from any USB port.

To verify if the ‘swrandom’ module has successfully detected the SwiftRNG device, simply check the kernel system logs, you should see a log that should look similar to this:

  -----------------------------------------
  -- SwiftRNG device connected and ready --
  -----------------------------------------

Currently the ‘swrandom’ module can only use one SwiftRNG device at a time.

‘swrandom’ module can be unloaded from the kernel by running the following command (using system administration privileges):

rmmod swrandom

Configuring the ‘swrandom’ module for use with the ‘rngd’ daemon on Ubuntu

The following steps explain how to configure ‘swrandom’ module for using with ‘rngd’ daemon on Ubuntu server (64 and 32 bits) or desktop versions:

Step 1

Make sure the OS is updated with the latest changes by running the following from command line:

sudo apt-get update
sudo apt-get upgrade

Step 2

Reboot the system after step 1:

sudo reboot

Step 3

Make sure the ‘make’, ‘gcc’ and ‘rng-tools’ packages are installed by running the following commands:

sudo apt-get install make
sudo apt-get install gcc
sudo apt-get install rng-tools

Step 4

Build the swrandom module, make sure it builds successfully:

cd swrandom
make

Step 5

Install the ‘swrandom’ module (if successfully installed, it will create device /dev/swrandom):

sudo ./ins-swrandom.sh

Step 6

Make sure the SwiftRNG device is plugged in and the module has been installed successfully and initialized by running the following from command line:

tail -100f /var/log/syslog

You should see a log fragment similar to the following:

  -----------------------------------------
  -- SwiftRNG device connected and ready --
  -----------------------------------------

Step 7

Execute the following test from command line to verify that the SwiftRNG device is working:

sudo dd if=/dev/swrandom of=/dev/null bs=12000000 count=10

You should get a report similar to this one after waiting for about 10 seconds:

10+0 records in
10+0 records out
120000000 bytes (120 MB) copied, 9.60855 s, 12.5 MB/s

Step 8

You can start the rngd daemon by running the following (this daemon is part of the rng-tools package) (repeat this step if the SwiftRNG device gets re-connected to the computer):

sudo rngd -r /dev/swrandom

The command will return to command line with no message if everything went well. The rngd daemon will use the entropy from /dev/swrandom to actually feed the /dev/random pool. It will also check the SwiftRNG data quality when using /dev/swrandom device.

Step 9

Now you can test the /dev/random pool by running the following:

sudo dd if=/dev/random of=download.bin bs=1 count=120000

The output may look similar to this:

120000+0 records in
120000+0 records out
120000 bytes (120 kB) copied, 4.28862 s, 28.0 kB/s

Building and using swrng and swrng-cl utilities with Linux and macOS

The swrng software utility can be used to verify the SwiftRNG installation status and download true random bytes from a SwiftRNG. The swrng project requires ‘make’, ‘gcc’, ‘libusb’ and ‘gcc’ components to be installed prior to building the swrng utility. The project also contains the ‘swrngapi.c’ and ‘swrngapi.h’ source files that can be included in other projects for communicating with the SwiftRNG device directly. Source files ‘swrng-cl-api.c’ and ‘swrng-cl-api.h’ are used for communicating with a cluster of multiple SwiftRNG devices to boost the generation speed and for fail-over capability.

Note: swrng-cl is a clustered version of the swrng utility and it is designed to work with a cluster of two or more SwiftRNG devices concurrently.

The ‘swrng’ project is available in the following SDK location:

linux-and-osx\swrng

On Ubuntu, use the following commands to install the required dependencies:

sudo apt-get update
sudo apt-get install make
sudo apt-get install gcc
sudo apt-get install libusb-1.0

On CentOS or Red Hat, use the following commands to install the required dependencies:

yum update
yum install make
yum install gcc
yum install libusb*

On macOS, the ‘libusb’ dependency can be installed by running the following from the command line:

brew install libusb

To build the swrng software utility, you will need to run the following from the command line:

cd linux-and-osx\swrng
make

After the SwiftRNG device is plugged into an available USB port, to verify that the device was successfully configured for Linux or macOS, run the following from the command line:

sudo ./swrng –ld

When the SwiftRNG device is successfully installed and ready, the output from running the above command should look something like this:

{DevNum=0 DevModel=SwiftRNG DevVer=V1.0 DevS/N=HJA5A6D44A5BD43}

Where:

  • DevNum – logical device number starting with 0 (you can use multiple SwiftRNG devices)
  • DevModel – RNG device model
  • DevVer – SwiftRNG device version
  • DevS/N – Unique serial number assigned to a SwiftRNG device when manufactured

To download 12 MB of true random numbers from the SwiftRNG device and store them in a file named ‘rnd.bin’:

sudo ./swrng -dd -fn rnd.bin -nb 12000000

To download 12 MB of true random numbers from a cluster of four SwiftRNG devices and store them in a file named ‘rnd.bin’:

sudo ./swrng-cl -dd -fn rnd.bin -nb 12000000 -cs 4

To download 12 MB of true random numbers from the SwiftRNG device and send them to standard output:

sudo ./swrng -dd -fn STDOUT -nb 12000000

To download an unlimited amount of true random numbers from the SwiftRNG device and store them in a file named ‘rnd.bin’:

sudo ./swrng -dd -fn rnd.bin

To continuously feed the Linux ‘/dev/random’ entropy pool, use the following command:

sudo ./swrng -fep

By default, the swrng utility will use the SwiftRNG power profile 9 (the fastest speed and highest power consumption). The following demonstrates how to lower the power consumption of SwiftRNG by setting power profile number to 4 (the number must be between 0 and 9) for downloading random bytes:

sudo ./swrng -dd -fn rnd.bin -nb 12000000 -ppn 4

Building and using swrng utility with Windows 10 and Vista 8.1

The SwiftRNG device should be connected to the PC using one of the available USB 2.0 or 3.0 ports. Once the SwiftRNG device is connected for the first time, Windows OS will automatically install the appropriate certified USB driver (the driver is already provided by OS).

The Software & Documentation Kit contains the ‘swrng.exe’ software utility located in folder ‘windows-x64\x64\Release’. Alternatively, the folder ‘windows-x64\swrng’ contains a Visual Studio C++ 2015 project that can be used to build the ‘swrng.exe’ software utility. The kit also comes with the SwiftRNG.dll and complete source code that can be included in other software projects for sharing random data generated by SwiftRNG device.

To verify the swrng device installation status, run the following command from the command line:

windows-x64\x64\Release\swrng.exe -ld

When the SwiftRNG device is successfully installed and ready, the output from running the above command should look something like this:

{DevNum=0 DevModel=SwiftRNG DevVer=V1.0 DevS/N=HJA5A6D44A5BD43}

Where:

  • DevNum – logical device number starting with 0 (you can use multiple SwiftRNG devices)
  • DevModel – RNG device model
  • DevVer – SwiftRNG device version
  • DevS/N – Unique serial number assigned to a SwiftRNG device when manufactured

To download 12 MB of true random numbers from the SwiftRNG device and store them in a file named ‘rnd.bin’:

windows-x64\x64\Release\swrng.exe -dd -fn rnd.bin -nb 12000000

To download an unlimited amount of true random numbers from the SwiftRNG device and store them in a file named ‘rnd.bin’:

windows-x64\x64\Release\swrng.exe -dd -fn rnd.bin

By default, the swrng utility will use the SwiftRNG power profile 9 (the fastest speed and highest power consumption). The following demonstrates how to lower the power consumption of SwiftRNG by setting power profile number to 4 (the number must be between 0 and 9) for downloading random bytes:

windows-x64\x64\Release\swrng.exe -dd -fn rnd.bin -nb 12000000 -ppn 4

Using SwiftRNG.dll for communicating with SwiftRNG device on Windows 8.1 & 10 systems

The Software Kit for Windows includes a x64 version of the DLL that allow applications running on Windows to share the SwiftRNG device for downloading the random byte stream. Pre-built and ready for use versions of the DLL are located in the following directories:

windows-x64\x64\Release\SwiftRNG.dll

A file with the DLL API function signatures can be found in the following locations:

windows-x64\DLL\ReadMe.txt

The kit contains ‘dll-samle.exe’ and ‘dll-test.exe’ DLL client sample program with complete source code that demonstrates how to use SwiftRNG.dll with C/C++ based Windows applications.

Testing SwiftRNG device performance using the ‘swperftest’ utility with Linux and macOS

Make sure the ‘swperftest’ utility is successfully built with ‘make’. Plug the SwiftRNG device in a USB port.

For the ‘swperftest’ utility, run the following command:

sudo ./swperftest

‘swperftest’ will discover all of the SwiftRNG devices connected to the system, run general device performance test and, report the random number generation speed in megabits per second.

The output may look similar to this:

sudo ./swperftest
------------------------------------------------------------
-- swperftest - SwiftRNG device performance test utility  --
------------------------------------------------------------
Searching for devices ------------------ found 1 SwiftRNG device(s)


Testing SwiftRNG with S/N: 1434A2BE0380D34 version: V1.1
Opening device -------------------------------------------- Success
Setting power profiles to 9 ------------------------------- Success
Performance ------- in progress ------------------ 100.00 Mbits/sec
Closing device -------------------------------------------- Success

-------------------------------------------------------------------

Testing performance of a cluster of SwiftRNG devices using the ‘swperf-cl-test’ utility with Linux and macOS

Make sure the ‘swperf-cl-test’ utility is successfully built with ‘make’. Plug in two or more SwiftRNG devices in USB ports available.

Run the following command:

sudo ./swperf-cl-test

‘swperf-cl-test’ will form a cluster of SwiftRNG devices connected to the system, run general device performance test, and report the random number generation speed in megabits per second.

The output may look similar to this:

sudo ./swperf-cl-test
------------------------------------------------------------------------
-- swperf-cl-test - SwiftRNG device cluster performance test utility  --
------------------------------------------------------------------------

Cluster preferred size: 2, actual cluster size: 2 (successfully open)

Performance ------- in progress ----------------------- 200.00 Mbits/sec
Number of cluster fail-over events ------------------------ 0
Closing cluster ------------------------------------------------ Success

Testing the SwiftRNG device using ‘swdiag’ utility with Linux and macOS

This section demonstrates how to run SwiftRNG general diagnostics and test the quality of random bytes generated by the device.

Make sure the ‘swdiag’ utility is successfully built with ‘make’. Plug the SwiftRNG device in one of the USB ports available.

For ‘swdiag’, run the following command:

sudo ./swdiag

‘swdiag’ will discover all the SwiftRNG devices connected to the system, run general diagnostics, and execute tests such as APT, RCT and Chi-Squire.

Testing a cluster of SwiftRNG devices using ‘swdiag-cl’ utility with Linux and macOS

This section demonstrates how to run SwiftRNG general diagnostics and test the quality of random bytes generated by a cluster of multiple devices.

Make sure the ‘swdiag-cl’ utility is successfully built with ‘make’. Plug two or more SwiftRNG devices in USB ports available.

For ‘swdiag-cl’, run the following command:

sudo ./swdiag-cl

‘swdiag-cl’ will form a cluster of two or more SwiftRNG devices connected to the system, run general diagnostics, and execute tests such as APT, RCT and Chi-Squire.

Testing the SwiftRNG device using swdiag utility with Windows 8.1 & 10

This section demonstrates how to run SwiftRNG general diagnostics and test the quality of random bytes generated by the device.

A pre-built version of ‘swdiag.exe’ utility is already available in ‘windows-x64\x64\Release\Release’ directory. Alternatively, the utility can be re-built with Visual Studio C++ 2015 or similar.

For ’swdiag’ utility, run the following command:

swdiag.exe

swdiag utility will discover all the SwiftRNG devices connected to the system, will run general diagnostics and will execute tests such as APT, RCT and Chi-Squire.

Testing the quality of random bytes using swrng utility on Ubuntu

This section demonstrates how to test the quality of random bytes generated by the device on Ubuntu OS. However, similar steps can be performed on CentOS or Red Hat systems as well.

Make sure the ‘rngtest’, ‘ent’ and ‘dieharder’ utilities are installed using the following commands:

sudo apt-get install rng-tools
sudo apt-get install ent
sudo apt-get install dieharder

For using ’rngtest’ utility, run the following command for downloading and testing 200000032 of random bits:

sudo ./swrng -dd -fn STDOUT | rngtest -c 10000

The output may look something like this (the number of failures must be very low compared with the number of successes):

rngtest: starting FIPS tests...
rngtest: bits received from input: 200000032
rngtest: FIPS 140-2 successes: 9993
rngtest: FIPS 140-2 failures: 7
rngtest: FIPS 140-2(2001-10-10) Monobit: 1
rngtest: FIPS 140-2(2001-10-10) Poker: 1
rngtest: FIPS 140-2(2001-10-10) Runs: 2
rngtest: FIPS 140-2(2001-10-10) Long run: 3
rngtest: FIPS 140-2(2001-10-10) Continuous run: 0
rngtest: input channel speed: (min=268.641; avg=4061.732; max=19073.486)Mibits/s
rngtest: FIPS tests speed: (min=28.596; avg=39.242; max=41.285)Mibits/s
rngtest: Program run time: 5045884 microseconds

For using ’ent’ utility, run the following command for downloading and testing 120,000,000 of random bytes:

sudo ./swrng -dd -fn STDOUT -nb 120000000 | ent

The output may look something like this:

Entropy = 7.999999 bits per byte.

Optimum compression would reduce the size
of this 120000000 byte file by 0 percent.

Chi square distribution for 120000000 samples is 239.23, and randomly
would exceed this value 75.29 percent of the times.

Arithmetic mean value of data bytes is 127.4971 (127.5 = random).
Monte Carlo value for Pi is 3.141073400 (error 0.02 percent).
Serial correlation coefficient is -0.000140 (totally uncorrelated = 0.0).

For using ’dieharder’ utility, run the following command (it may take up to 16 hours to complete the test):

sudo ./swrng -dd -fn STDOUT | dieharder -a -g 200

The output may look something like this (to keep this page short we only included the first 13 lines of the output):

#=============================================================================#
#            dieharder version 3.31.1 Copyright 2003 Robert G. Brown          #
#=============================================================================#
   rng_name    |rands/second|   Seed   |
stdin_input_raw|  2.67e+06  |1292664540|
#=============================================================================#
        test_name   |ntup| tsamples |psamples|  p-value |Assessment
#=============================================================================#
   diehard_birthdays|   0|       100|     100|0.71477273|  PASSED
      diehard_operm5|   0|   1000000|     100|0.86030318|  PASSED
  diehard_rank_32x32|   0|     40000|     100|0.84744819|  PASSED
    diehard_rank_6x8|   0|    100000|     100|0.28786307|  PASSED
   diehard_bitstream|   0|   2097152|     100|0.79008830|  PASSED

Testing the quality of random bytes using ‘swrandom’ module on Ubuntu

This section demonstrates how to test the quality of random bytes generated by the device on Ubuntu OS using ’swrandom’ kernel module. However, similar steps can be performed on CentOS or Red Hat systems as well. Read section ‘Building and loading the ‘swrandom’ kernel module with Linux’ that explains how to load the ’swrandom’ module.

Make sure the ‘rngtest’, ‘ent’ and ‘dieharder’ utilities are installed using the following commands:

sudo apt-get install rng-tools
sudo apt-get install ent
sudo apt-get install dieharder

For using ’rngtest’ utility, run the following command for downloading and testing 200000032 of random bits:

cat /dev/swrandom | rngtest -c 10000

The output may look something like this (the number of failures must be very low compared with the number of successes):

rngtest: starting FIPS tests...
rngtest: bits received from input: 200000032
rngtest: FIPS 140-2 successes: 9996
rngtest: FIPS 140-2 failures: 4
rngtest: FIPS 140-2(2001-10-10) Monobit: 1
rngtest: FIPS 140-2(2001-10-10) Poker: 0
rngtest: FIPS 140-2(2001-10-10) Runs: 1
rngtest: FIPS 140-2(2001-10-10) Long run: 2
rngtest: FIPS 140-2(2001-10-10) Continuous run: 0
rngtest: input channel speed: (min=423.855; avg=3891.754; max=9536.743)Mibits/s
rngtest: FIPS tests speed: (min=26.676; avg=39.110; max=42.386)Mibits/s
rngtest: Program run time: 4946762 microseconds

For using ’ent’ utility, run the following command for downloading and testing 120,000,000 of random bytes:

sudo dd if=/dev/swrandom bs=10 count=12000000 | ent

The output may look something like this:

12000000+0 records in
12000000+0 records out
120000000 bytes (120 MB) copied, 42.6431 s, 2.8 MB/s
Entropy = 7.999999 bits per byte.

Optimum compression would reduce the size
of this 120000000 byte file by 0 percent.

Chi square distribution for 120000000 samples is 245.22, and randomly
would exceed this value 50.00 percent of the times.

Arithmetic mean value of data bytes is 127.4974 (127.5 = random).
Monte Carlo value for Pi is 3.141486000 (error 0.00 percent).
Serial correlation coefficient is 0.000016 (totally uncorrelated = 0.0).

For using ’dieharder’ utility, run the following command (it may take up to 16 hours to complete the test):

cat /dev/swrandom | dieharder -a -g 200

The output may look something like this (to keep this page short we only included the first 13 lines of the output):

#=============================================================================#
#            dieharder version 3.31.1 Copyright 2003 Robert G. Brown          #
#=============================================================================#
   rng_name    |rands/second|   Seed   |
stdin_input_raw|  2.85e+06  |1581281168|
#=============================================================================#
        test_name   |ntup| tsamples |psamples|  p-value |Assessment
#=============================================================================#
   diehard_birthdays|   0|       100|     100|0.67854374|  PASSED
      diehard_operm5|   0|   1000000|     100|0.67569037|  PASSED
  diehard_rank_32x32|   0|     40000|     100|0.47867080|  PASSED
    diehard_rank_6x8|   0|    100000|     100|0.62835183|  PASSED
   diehard_bitstream|   0|   2097152|     100|0.11560427|  PASSED

Using ‘/dev/swrandom’ device, ’swrng’ download utility and ‘swrngapi’ software API with non ROOT access permissions on Linux platforms

To enable a non ROOT user to access the ’/dev’swrandom’ device, simply copy the supplied ’80-swiftrng-device-access.rules’ file to ‘/etc/udev/rules.d/’ location.

To enable a non ROOT user to access ’swrng’ download utility and ‘swrngapi’ software API, simply copy the supplied ’80-swiftrng-usb-access.rules’ file to ‘/etc/udev/rules.d/’ location.