The AlphaRNG Software Kit ships with a Linux kernel module alrandom that can be used for distributing a random byte stream generated by an AlphaRNG device to applications in user space over a non-secure USB connection. The random byte stream generated can be concurrently accessed by consumer applications using device /dev/alrandom.

After alrandom module is loaded (using one of the methods described on this page) and an AlphaRNG device is plugged in, an application can open /dev/alrandom 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/alrandom device with a single read operation at a time.

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

alrandom module depends on 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 alrandom Kernel Module in development environments

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

linux/alrandom

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

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

We strongly recommend performing the following steps before building the alrandom 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 alrandom module on CentOS and Red Hat:

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

The alrandom module can be built with make:

cd alpharng/linux/alrandom
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-alrandom.sh script:

sudo ./ins-alrandom.sh

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

/dev/alrandom

Use the following command for downloading 10000000 bytes into a file:

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

The current version of alrandom module can only use one AlphaRNG device at a time.

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

sudo rmmod alrandom

Auto-Build alrandom 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 alrandom 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 AlphaRNG SDK which also contains the alrandom driver source code:

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

Step 3

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

sudo cp -R linux/alrandom /usr/src/alrandom-1.0.0

Step 4

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

sudo vi /usr/src/alrandom-1.0.0/dkms.conf

PACKAGE_NAME="alrandom"
PACKAGE_VERSION="1.0.0"
BUILT_MODULE_NAME[0]="alrandom"
DEST_MODULE_LOCATION[0]="/kernel/drivers/char/alrandom/"
AUTOINSTALL="yes"

Step 5

Add alrandom module to the kernel tree:

sudo dkms add -m alrandom -v 1.0.0

Step 6

Build alrandom module against the currently running kernel:

sudo dkms build -m alrandom -v 1.0.0

Step 7

Install alrandom module under the current kernel tree:

sudo dkms install -m alrandom -v 1.0.0

Step 8

Check the status of the alrandom module:

dkms status | grep alrandom

Step 9

Verify that alrandom module can be loaded successfully:

sudo modprobe alrandom

Verify that /dev/alrandom device path exists:

ls /dev/alrandom

Step 10

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

sudo vi /etc/modules

Append the following content:

alrandom

Step 11

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

sudo dd if=/dev/alrandom 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.0363772 s, 27.5 MB/s

Adding alrandom driver source to the Linux kernel source code

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

alrandom 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 AlphaRNG SDK using git and locate alrandom directory:

git clone https://github.com/tectrolabs/alpharng.git
cd alpharng/linux/alrandom

Step 2

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

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

Step 3

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

obj-$(CONFIG_RNG_ALRANDOM) += alrandom.o

Step 4

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

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

Step 5

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

obj-$(CONFIG_RNG_ALRANDOM)      += alrandom/

Step 6

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

source "drivers/char/alrandom/Kconfig"

Step 7

Run make menuconfig in the kernel source tree directory and make sure that entry TectroLabs support for AlphaRNG 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, alrandom 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/alrandom/info

The output may look similar to the following:

AlphaRNG statistical tests: enabled
maximum RCT failures per block for device: 0
maximum APT failures per block for device: 0
total RCT failures for device: 0
total APT failures for device: 0
RCT status byte for device: 0
APT status byte for device: 0
last known device status byte: 0
number of requests handled by device: 6313

Non-root access on Linux

To enable a non-root user to access the /dev/alrandom device, simply copy the supplied 80-alpharng-device-access.rules file to /etc/udev/rules.d/ location.

AlphaRNG device version compatibility

The latest version of alrandom module supports all AlphaRNG 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 (alrandom.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.

Kernel version compatibility

The alrandom 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 alrandom module for use with rngd daemon on Ubuntu server or desktop:

Step 1

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

Step 2

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

Step 3

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

sudo dd if=/dev/alrandom 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/alrandom

The command will return to command line with no message if everything went well. The rngd daemon will use the entropy from /dev/alrandom 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