The AlphaRNG software kit ships with the alrandom Linux kernel module, which distributes the random byte stream generated by an AlphaRNG device to applications in user space over a non-secure USB connection. The stream can be accessed concurrently by consumer applications through the /dev/alrandom device.
After the 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 in binary read mode and read random bytes produced by the device. Each application can read up to 100,000 bytes from /dev/alrandom in a single read operation.
When in use, the alrandom module searches for connected AlphaRNG devices and uses the first available device after locking it for exclusive use.
The alrandom module depends on the USB ACM driver, which must be loaded in the kernel for communication to succeed. Some kernel builds, such as those custom-built for embedded ARM platforms, may not include the USB ACM driver by default.
Building and loading the module manually in development environments
The alrandom make project is located in the following folder of the software kit:
linux/alrandom
Alternatively, the project can be downloaded with git using the following command:
git clone https://github.com/tectrolabs/alpharng.git
Before building the alrandom module on Ubuntu, run the following commands:
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install make
sudo apt-get install gcc
On older versions of Ubuntu, you may also need to run:
sudo apt-get install libelf-dev
Before building the alrandom module on CentOS or Red Hat, run the following commands:
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: the module must be rebuilt each time a new kernel version is installed on the system.
Once the module is built, load it into the kernel by running the ins-alrandom.sh script:
sudo ./ins-alrandom.sh
After the alrandom module is loaded, random bytes are available from the following device:
/dev/alrandom
Use the following command to download 10,000,000 bytes into a file:
sudo dd if=/dev/alrandom of=download.bin bs=100 count=100000
The current version of the alrandom module can use only one AlphaRNG device at a time.
The alrandom module can be unloaded from the kernel with the following command:
sudo rmmod alrandom
Building the module automatically with DKMS in development environments
Dynamic Kernel Module Support (DKMS) is a framework that builds and installs external kernel modules for each kernel in the system. With DKMS, kernel modules are rebuilt automatically when the kernel is upgraded.
The following steps show how to build the alrandom kernel module automatically with DKMS on Linux.
Step 1
On Ubuntu or Debian, install the DKMS package with the following command:
sudo apt-get install dkms
Step 2
Download the AlphaRNG software kit, which contains the alrandom driver source code:
git clone https://github.com/tectrolabs/alpharng.git
cd alpharng
Step 3
Copy the alrandom driver source code to the /usr/src directory:
sudo cp -R linux/alrandom /usr/src/alrandom-1.0.0
Step 4
Create a new dkms.conf file in the new source directory:
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 the alrandom module to the DKMS tree:
sudo dkms add -m alrandom -v 1.0.0
Step 6
Build the alrandom module against the currently running kernel:
sudo dkms build -m alrandom -v 1.0.0
Step 7
Install the 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 the alrandom module loads successfully:
sudo modprobe alrandom
Verify that the /dev/alrandom device path exists:
ls /dev/alrandom
Step 10
To load the alrandom module when the system boots, edit the /etc/modules file:
sudo vi /etc/modules
Append the following content:
alrandom
Step 11
Connect an AlphaRNG device to an available USB port and run the following command to verify that the alrandom module is working:
sudo dd if=/dev/alrandom of=/dev/null bs=100000 count=10
You should get a report similar to this one:
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 this approach for production environments on platforms such as Ubuntu, CentOS and Red Hat.
The alrandom driver code can be added to an existing Linux kernel source tree so that it is included in the kernel build. This can be done with the following steps:
Step 1
Download a copy of the AlphaRNG software kit with git and change to the 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 the TectroLabs support for AlphaRNG devices entry is enabled under Device Drivers ---> Character devices. Save the changes and exit.
Step 8
Build a new kernel from source. The exact commands depend on the OS and target platform. On Ubuntu, this can be done as part of the deb package creation step with the following command (the -j parameter sets how many CPU cores to use):
make -j4 deb-pkg
Retrieving real-time module statistics
When loaded, the alrandom module exposes real-time information through the proc file system. The 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, copy the supplied 80-alpharng-device-access.rules file to /etc/udev/rules.d/.
AlphaRNG device version compatibility
The latest version of the alrandom module supports all AlphaRNG device versions and models.
Module configuration and memory optimization
By default, the maximum number of random bytes a user can retrieve at a time is 100,000, as defined by the MAX_BYTES_USER_CAN_REQUEST macro in the alrandom.h header file. When loading, the module allocates that many bytes from the kernel memory heap. You can reduce the memory footprint of the module by setting MAX_BYTES_USER_CAN_REQUEST to a lower value, or set it higher than 100,000 to increase the number of bytes a 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 and 6.2.
Configuring for rngd on Ubuntu
rngd is a daemon that checks random data from a hardware device and feeds it to the kernel entropy pool. More information about rngd is available on the Arch Linux wiki.
The rngd daemon is part of the rng-tools package and can be installed with the following command:
sudo apt-get install rng-tools
The following steps explain how to configure the alrandom module for use with the 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
Run the following command to verify that the alrandom module is working:
sudo dd if=/dev/alrandom of=/dev/null bs=100000 count=10
You should get a report similar to this one:
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
Start the rngd daemon with the following command:
sudo rngd -r /dev/alrandom
The command returns with no message if everything went well. The rngd daemon will use entropy from /dev/alrandom to feed the /dev/random pool.
Step 5
Now you can test the /dev/random pool with the following command:
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