This article gives information about the Linux® hardware random framework.
1. Article Purpose[edit source]
This article gives information about the use of the RNG peripheral in the OSTL ecosystem and the Linux kernel hardware random (HWRNG) framework that provides access to RNG peripherals.
2. System overview[edit source]
The HW random framework allows retrieving random numbers in the kernel userland.
- HW random core (Kernel space)
Generic interface in kernel space. This layer is in charge of creating the character device (char device) and sysfs to access hw_random.
- RNG (Kernel space)
Hardware random Linux® drivers handling the HW blocks. Either OP-TEE RNG driver or kernel RNG driver.
- RNG (Hardware)
HW blocks handling the RNG peripheral.
The RNG can be assigned to non-secure or secure world (default behavior). If the RNG is assigned to the secure world then the non-secure world can request random numbers through the OP-TEE RNG PTA. More information about this mechanism can be found in OP-TEE documentation [1]. Else, the software component uses its RNG driver directly.
The hardware RNG peripheral for Arm® Cortex®-A processor is default assigned to OP-TEE. This is the default and recommended setup.
It is possible to assign the RNG to the Linux Kernel, but it is necessary to deactivate it in OP-TEE device tree and activate it in the Linux kernel device tree, declare it as a firewall exception in the OP-TEE firewall driver and declare your board in the flavorlist-no_rng in the OP-TEE board configuration makefile .
2.1. API description[edit source]
The kernel Hardware random framework uses char device API[2] ioctl operations. For additional information, refer to:
- sysfs interface.
- Kernel Documentation directory[3]
3. Configuration[edit source]
3.1. Kernel configuration[edit source]
The Hardware random support is activated by default in ST deliveries. No specific configuration is required apart from enabling or disabling peripheral support using Linux® Menuconfig tool. Refer to Menuconfig or how to configure kernel and select:
[*] Device Drivers --->
[*] Character devices --->
[*] Hardware Random Number Generator Core support --->
[*] OP-TEE based Random Number Generator support
[*] STMicroelectronics STM32 random number generator //In case the RNG is on the kernel side
3.2. Device tree configuration[edit source]
Device tree configuration can be done using STM32CubeMX.
A detailed device tree configuration is described in RNG device tree configuration.
4. How to use the framework[edit source]
The framework provides external interfaces from userland : How to control RNG.
4.1. How to use from char device[edit source]
The community tool for using Hardware random framework is rng_tools[4] which provides a complete set of utilities related to random number generators:
- rngd: runs a background daemon that opens /dev/hwrng file (default) to connect and retrieve random numbers.
- rngtest: runs different tests that check the entropy and verify the compliance regarding FIPS 140-2 standard.
4.2. How to use from sysfs[edit source]
Available devices compatible with Hardware framework can be listed using sysfs commands:
cat /sys/class/misc/hw_random/rng_available optee-rng stm32-rng
The selected device is shown here:
cat /sys/class/misc/hw_random/rng_current optee-rng
To select a different device:
echo "stm32-rng"> /sys/class/misc/hw_random/rng_current
5. How to trace and debug the framework[edit source]
Light information on the framework can be accessed by using sysfs.
By default, the framework does not provide any specific debug output or dynamic debugging tool.
6. Source code location[edit source]
Hardware random drivers and framework are available here[5].
7. To go further[edit source]
Code examples are directly available from rng-tools[4] github.
8. References[edit source]
Arm® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere. 