The SwiftRNG Software Kit contains a Linux kernel module ‘swrandom’ that can be used for distributing random byte stream generated by a SwiftRNG device to any application that is capable to read from a file. The random byte stream generated can be concurrently accessible by consumer applications using device /dev/swrandom (Fig. 4).

‘swrandom’ kernel device module use case on Linux platforms

Manually building and loading swrandom Kernel Module in development environments

The swrandom make project is available in the following SDK location:

linux/swrandom

Alternatively the project can be downloaded with git using the following command:

git clone https://github.com/tectrolabs/swiftrng.git

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 install make
sudo apt-get install gcc

When used with older versions of Ubuntu, you may also need to perform the following step:

sudo apt-get install libelf-dev

We recommend performing the following steps before building the swrandom module on CentOS and Red Hat:

sudo yum install make
sudo yum install gcc
sudo yum install kernel-devel

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.

Once the module is successfully built with make, it can be loaded into the kernel by running the ins-swrandom.sh script:

sudo ./ins-swrandom.sh

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

/dev/swrandom

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

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

The current version of swrandom module can only use one SwiftRNG device at a time.

swrandom module can be unloaded from the kernel by running the following command:

sudo rmmod swrandom

Auto-Build swrandom Kernel Module with DKMS in development environments

Dynamic Kernel Module Support (DKMS) is a framework that allows external kernel modules to be dynamically built and installed for each kernel in the system. With DKMS it is possible to automatically re-build kernel modules into the current kernel tree when the kernel version gets upgraded.

The following will demonstrate how to auto-build swrandom kernel module with DKMS on Linux.

Step 1

Install DKMS package with the following command:

When using Ubuntu or Debian:

sudo apt-get install dkms

Step 2

Download the SwiftRNG SDK which also contains the swrandom driver source code:

git clone https://github.com/tectrolabs/swiftrng.git
cd swiftrng

Step 3

Install the source code of the swrandom driver under /usr/src directory:

sudo cp -R linux/swrandom /usr/src/swrandom-2.1.0

Step 4

Create new dkms.conf file in the new source directory and add config data:

sudo vi /usr/src/swrandom-2.1.0/dkms.conf
PACKAGE_NAME="swrandom"
PACKAGE_VERSION="2.1.0"
BUILT_MODULE_NAME[0]="swrandom"
DEST_MODULE_LOCATION[0]="/kernel/drivers/char/swrandom/"
AUTOINSTALL="yes"

Step 5

Add swrandom module to the kernel tree:

sudo dkms add -m swrandom -v 2.1.0

Step 6

Build swrandom module against the currently running kernel:

sudo dkms build -m swrandom -v 2.1.0

Step 7

Install swrandom module under the current kernel tree:

sudo dkms install -m swrandom -v 2.1.0

Step 8

Check the status of the swrandom module:

dkms status | grep swrandom

Step 9

Verify that swrandom module can be loaded successfully:

sudo modprobe swrandom

Verify that /dev/swrandom device path exists:

ls /dev/swrandom

Step 10

To make swrandom module to load when the system boots, update `/etc/modules’ file:

sudo vi /etc/modules

Append the following content:

swrandom

Step 11

Connect a SwiftRNG device to one of the USB ports available and enter the following from command line to verify that swrandom module is working:

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

You should get a report similar to this ones:

10+0 records in
10+0 records out
1000000 bytes (1.0 MB, 977 KiB) copied, 0.0421225 s, 23.7 MB/s

Add swrandom driver source to the Linux kernel source code

We recommend using this solution on platforms such as Ubuntu, CentOS, RH in production environments.

swrandom driver code can be added to an existing Linux source code so it can be included as part of a kernel build.

That can be done with the following steps:

Step 1

Download a copy of the SwiftRNG SDK using git and locate swrandom directory:

git clone https://github.com/tectrolabs/swiftrng.git
cd swiftrng/linux/swrandom

Step 2

Create drivers/char/swrandom directory in your Linux kernel source tree (kernel-source-tree as an example) and copy swrandom.c and swrandom.h files to the new directory:

mkdir kernel-source-tree/drivers/char/swrandom
cp swrandom.c kernel-source-tree/drivers/char/swrandom/
cp swrandom.h kernel-source-tree/drivers/char/swrandom/

Step 3

Create kernel-source-tree/drivers/char/swrandom/Makefile with the following content:

obj-$(CONFIG_RNG_SWRANDOM) += swrandom.o

Step 4

Create kernel-source-tree/drivers/char/swrandom/Kconfig with the following content:

config RNG_SWRANDOM
tristate "TectroLabs support for SwiftRNG devices"
select USB_ACM
depends on TTY
depends on USB
default y
help
  A module/driver that registers /dev/swrandom device for supplying true random bytes generated by SwiftRNG devices

Step 5

Edit kernel-source-tree/drivers/char/Makefile and append the following content:

obj-$(CONFIG_RNG_SWRANDOM)      += swrandom/

Step 6

Edit kernel-source-tree/drivers/char/Kconfig and append the following content before endmenu tag:

source "drivers/char/swrandom/Kconfig"

Step 7

Run make menuconfig in the kernel source tree directory and make sure that entry TectroLabs support for SwiftRNG devices is enabled in location Device Drivers ---> Character devices.

Step 8

Build a new Kernel from sources. On Ubuntu that can be done, as part of deb files creation step, using the following command (parameter -j indicates how many CPU cores to use):

make -j4 deb-pkg 

Configuring for rngd on Ubuntu

rngd is a daemon developed to check and feed random data from a hardware device to kernel entropy pool. More information about rngd daemon can be found at this address.

rngd daemon is part of rng-tools package and can be installed by running the following command:

sudo apt-get install rng-tools

The following steps explain how to configure swrandom module for use with rngd daemon on Ubuntu server or desktop:

Step 1

Build and install the swrandom module using one of the methods described above.

Step 2

Make sure the SwiftRNG device is plugged in and the module has been installed successfully.

Step 3

Execute the following test from command line to verify that swrandom module is working:

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

You should get a report similar to this ones:

10+0 records in
10+0 records out
1000000 bytes (1.0 MB, 977 KiB) copied, 0.0421225 s, 23.7 MB/s

Step 4

You can start the rngd daemon by running the following:

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 feed the /dev/random pool.

Step 5

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

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

The output may look similar to this:

100000+0 records in
100000+0 records out
100000 bytes (100 kB) copied, 4.28862 s, 28.0 kB/s

Non-root access on Linux

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.

SwiftRNG device version compatibility

The latest version of swrandom module supports all SwiftRNG versions and models.

Kernel version compatibility

The swrandom module/driver has been tested on Ubuntu and CentOS platforms with kernel versions 4.14, 4.18, 4.19, 5.4, 5.11, 5.15 and 5.16