SwiftRNG swrandom kernel module for Linux

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

After swrandom module is loaded (using one of the methods described on this page) and a SwiftRNG device is plugged in, an application can open /dev/swrandom as a file (using binary read mode) in user space and read random bytes produced by the device. Each application can read up to 100,000 bytes from the /dev/swrandom device with a single read operation at a time.

A loaded swrandom module, when in use, will search for connected SwiftRNG devices and will use the first device available after locking it for exclusive use.

swrandom module depends on the ACM USB driver which should be loaded in the kernel for communication to succeed. Some of the kernel builds, like those that are custom built for ARM embedded platforms, may not have the ACM USB driver available by default.

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:

cd swiftrng/linux/swrandom
make

Note: You will need to rebuild the module each time a new version of the kernel is installed on the system.

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.2.0

Step 4

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

sudo vi /usr/src/swrandom-2.2.0/dkms.conf

PACKAGE_NAME="swrandom"
PACKAGE_VERSION="2.2.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.2.0

Step 6

Build swrandom module against the currently running kernel:

sudo dkms build -m swrandom -v 2.2.0

Step 7

Install swrandom module under the current kernel tree:

sudo dkms install -m swrandom -v 2.2.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

Adding 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. Save the changes and exit.

Step 8

Build a new Kernel from sources. The exact command(s) will depend on OS or target platform. 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 

Retrieving module real-time internal statistics

When loaded, swrandom module exposes some real-time information which is available through provided specific proc file system path.

Module internal real-time statistics can be retrieved with the following command:

cat /proc/swrandom/info

The output may look similar to the following:

SwiftRNG device model: SWRNGPRO
SwiftRNG device serial number: 123456789012345
SwiftRNG device version: 2.2 
SwiftRNG post processing method: disabled
SwiftRNG statistical tests: enabled
maximum RCT failures per block for device: 1
maximum APT failures per block for device: 1
total RCT failures for device: 3
total APT failures for device: 35
RCT status byte for device: 0
APT status byte for device: 0
last known device status byte: 0
number of requests handled by device: 694375

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 device versions and models.

Module configuration and memory optimization

By default, the maximum amount of random bytes that a user can retrieve at a time is limited to 100,000 which is defined by macro MAX_BYTES_USER_CAN_REQUEST (swrandom.h header file). When loading, the module allocates that amount of 100,000 bytes from the kernel memory heap. You can improve the memory footprint of the module by modifying MAX_BYTES_USER_CAN_REQUEST definition and setting it to a lower number. Alternatively, MAX_BYTES_USER_CAN_REQUEST value can be set to a higher than 100,000 number to increase the amount of bytes that the user can request at a time.

swrandom module, when in use, will detect model and version of the SwiftRNG device and will apply an appropriate default configuration as following:

Default module configuration for SwiftRNG Pro model:

Default module configuration for SwiftRNG Z model:

Default module configuration for SwiftRNG device model:

Default module configuration for SwiftRNG LE model:

Kernel version compatibility

The swrandom module/driver has been tested on Ubuntu and CentOS platforms with kernel versions 4.14, 4.19, 5.4, 5.10, 5.15, 6.1, 6.2

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